@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,109 @@
1
+ # Phase 10 — Artifacts, cleanup, compatibility, and documentation (design notes)
2
+
3
+ Phase 10 closes the feature by (a) confirming the artifact lifecycle follows
4
+ task settlement, (b) confirming shutdown/cleanup behavior, (c) making the
5
+ explicit compatibility decisions for `shepherd_prompt` and `shepherd_wait`,
6
+ and (d) updating the active documentation.
7
+
8
+ ## Artifacts
9
+
10
+ Delegate-time allocation was already in place from Phase 4: `delegateAgent`
11
+ reserves exactly one artifact per delegated task (mode `single`, task text
12
+ attached), marks it `running` with the taskId, and attaches a finalizer via
13
+ `attachTaskArtifact`. Ordinary messages never allocate artifacts — only
14
+ `delegateAgent` calls `reserveArtifacts`, so a `shepherd_message` cannot
15
+ create a note. "Open while waiting" is free because the note stays
16
+ `running` (only the frontmatter status changes; agents append freely) and
17
+ `settleTask` is the single authoritative finalization point:
18
+
19
+ - completed -> `completed`
20
+ - blocked (reply deadline, parent failure, ...) -> `failed`
21
+ - failed -> `failed`
22
+ - cancelled (close/cancel) -> `cancelled`
23
+ - timed_out -> `timed-out`
24
+
25
+ `settleTask` guards duplicate settlement (`if (record.settled) return
26
+ record.result!`), so repeated `shepherd_done`/reply/timeout/cancellation
27
+ events cannot double-finalize; `onSettled` runs exactly once and is wrapped
28
+ so an artifact failure never breaks task settlement. Final summaries
29
+ (`result.text`) and errors (`result.error`) are preserved in the note's
30
+ "## Shepherd orchestration" section, so "preserve final summaries and
31
+ errors" holds. Useful request/message references: the finalizer metadata
32
+ carries only the taskId (one note per task, not per chat — messages that
33
+ are correlated with a task use the task's artifact, not a new one).
34
+
35
+ Verified by `verify-delegate.mjs` (allocation + start + cancel finalization)
36
+ and `verify-artifact-sessions.mjs` (all four terminal artifact statuses +
37
+ final output/error sections + in-memory mirroring).
38
+
39
+ ## Cleanup and shutdown
40
+
41
+ All of the following were already implemented in Phases 4–8:
42
+
43
+ - parent shutdown: `shutdownParentBroker` stops the parent mailbox poll and,
44
+ via `stopParentBrokerMonitor`, the stale-wait monitor;
45
+ - child shutdown: the child surface (`shepherd-done.ts`) closes its own
46
+ broker channel on session end;
47
+ - persisted task outcomes survive parent shutdown because they are on-disk
48
+ (session.json + note files);
49
+ - a closing agent cancels its active task (`registry.close()` ->
50
+ `cancelTask()`, rc 130) and the task settlement clears its pending
51
+ requests; duplicate events are idempotent (settleTask guard);
52
+ - created-pane ownership protects foreign panes (existing invariant,
53
+ verified by the launch suite); mailbox consumption is parent-only
54
+ (broker capability is parent-scoped; children get a child capability).
55
+
56
+ No new cleanup code was required in Phase 10; these behaviors are pinned by
57
+ existing tests plus the compat suite's "timeout never touches the task"
58
+ check.
59
+
60
+ ## Compatibility decisions
61
+
62
+ `shepherd_prompt`
63
+ RETAINED, DEPRECATED. Fire-and-forget one-turn submission stays available so
64
+ existing transcripts/templates keep working, but every model-facing field
65
+ (label, description, promptSnippet, message parameter) now states it is a
66
+ deprecated compatibility path and names the migration target
67
+ (`shepherd_delegate` + `shepherd_watch`). Its one-turn completion semantics
68
+ are unchanged and documented, so they are not "silently active": the docs
69
+ say exactly what it does and what to use instead.
70
+
71
+ `shepherd_wait`
72
+ RETAINED, UPGRADED to be task-aware. It now accepts task ids (preferred) or
73
+ legacy prompt ids (unchanged path); mixing them in one call is rejected,
74
+ mirroring shepherd_watch. Task waits:
75
+ - resolve via the task-watcher registry hook (no polling), in input order
76
+ including for tasks that settle out of order;
77
+ - resolve instantly for already-settled tasks;
78
+ - a wait timeout is a wait-level timeout: it rejects with
79
+ LifecycleError('timeout', ...) and removes the watcher. The underlying
80
+ tasks keep running (their own deadlines remain authoritative) and the
81
+ error message points the model at shepherd_watch.
82
+ No task or message depends on the parent calling shepherd_wait; the tool
83
+ description says shepherd_watch is preferred for new orchestration.
84
+
85
+ Implementation: `LifecycleRegistry.waitForTasks(handles, timeoutMs)` plus a
86
+ public `removeWatcher(watcherId)`; `watchTasks` additionally delivers
87
+ already-settled tasks synchronously in input order (Set-callback form, used by
88
+ waitForTasks) while keeping the legacy single-callback contract intact.
89
+
90
+ Verification: `test/verify-compat.mjs` (descriptions/pointers, schema
91
+ accepts both id kinds with flat-object root, in-order resolution, instant
92
+ already-settled, timeout leaves the task untouched, unknown-id rejection,
93
+ doAction public task mapping with returnCode).
94
+
95
+ ## Documentation
96
+
97
+ - README: new "Task delegation workflow" section (delegate ->
98
+ message/watch -> done, with a delegate+watch example and a child-to-child
99
+ message example), the task/message id explanation, idle-child-with-waiting-
100
+ task behavior, followUp vs steer, stale-wait reminders, and explicit
101
+ compatibility status for shepherd_prompt/shepherd_wait.
102
+ - docs/guides/tool-reference.md: delegate/message/done tools added;
103
+ prompt/wait/watch rows updated to reflect deprecation, task ids, and
104
+ mixing rules.
105
+ - docs/reference/dictionary: entries for task, task id, message, message id,
106
+ request/reply correlation, waiting tasks (idle child), and the deprecated
107
+ tools.
108
+ - docs/plans/architecture.md: task/message surface and broker added; the
109
+ "completed implementation" list now lists the tracked-task primitives.
@@ -0,0 +1,69 @@
1
+ # Phase 6 — design notes (working decisions)
2
+
3
+ Canonical requirement: `worker asks planner while planner is busy → planner
4
+ receives the question as a queued follow-up → worker task stays waiting →
5
+ planner replies → worker returns to running.` The parent must own request and
6
+ task state because later phases (watchers, stale-wait, status) read the parent
7
+ `lifecycleRegistry`, which the child process cannot touch.
8
+
9
+ ## How the pieces fit
10
+
11
+ 1. **Transport.** `messaging.ts` already routes child↔child *through the
12
+ parent-owned broker* and child→parent into the parent inbox (Phase 2). No
13
+ routing change needed. One fix: acknowledgement/dedup is keyed by
14
+ `(participant, messageId)`, so the parent can consume an envelope and later
15
+ relay a **fresh**-`messageId` copy to a child without the old ack blocking.
16
+
17
+ 2. **Request tracking (child-originated).** A child cannot put its task into
18
+ `waiting` by itself (the registry lives in the parent). So when the child
19
+ sends `shepherd_message` with `expectsReply` + a task, the child extension
20
+ also mirrors a `runtime` envelope (`requestOpen: true`) to the **parent**
21
+ inbox alongside the question. The parent opens a pending request on the
22
+ sender task and transitions it `running → waiting`.
23
+
24
+ 3. **Reply (child-originated).** A child answers a question by sending
25
+ `shepherd_message` with `replyTo` to `shepherd`. The parent resolves the
26
+ matching pending request (clears it + `waiting → running`) and **relays**
27
+ the reply to the original sender's child inbox with a fresh `messageId`
28
+ (provenance preserved: `senderId` stays the replier's agent id). If no
29
+ matching request exists the reply is surfaced to the parent as a notification.
30
+
31
+ 4. **Parent-originated.** `shepherd_message` tool → `publishFromParent` to the
32
+ target child inbox. If `expectsReply` + `taskId`, the parent also opens a
33
+ pending request on that task (parent can expect a reply from a delegated
34
+ agent the same way).
35
+
36
+ 5. **Reply deadline.** Each pending request stores `deadlineAt` (settings
37
+ `timeout` minutes). The existing parent monitor settles expired request
38
+ owners as `blocked` (initial task policy).
39
+
40
+ 6. **Parent notifications.** Child→parent `message`/`reply` are delivered to
41
+ the parent pi session as custom messages (`shepherd.message.incoming` /
42
+ `.reply`) with followUp delivery, reusing the prompt-completion
43
+ renderer/bridge pattern. No fieldnote is created.
44
+
45
+ 7. **Delivered vs accepted.** `accepted` = the broker accepted the envelope
46
+ into the target inbox. It never means the recipient read it or replied.
47
+
48
+ ## Envelope contract (Phase 6 usage)
49
+
50
+ - `message` → normal conversational content to a target.
51
+ - `reply` → `replyTo` set; answers a tracked question.
52
+ - `task` / `task_done` → existing (Phase 4/5).
53
+ - `runtime` with `taskId` + `expectsReply: true` + `requestOpen: true` →
54
+ child mirrors that it opened a tracked request (parent sets task to waiting).
55
+ `requestOpen` is a boolean field (envelope-validated).
56
+
57
+ ## Explicit Phase-6 scope (initial)
58
+
59
+ - Parent `shepherd_message` tool + request/task integration.
60
+ - Parent inbox routing: message/reply → parent session; runtime request-open →
61
+ task waiting; reply → resolve + relay.
62
+ - Child mirrors request-open; child already delivers incoming to its inbox.
63
+ - Reply deadline + blocked settlement.
64
+ - `test/verify-message-routing.mjs` + schema/contract updates.
65
+
66
+ Deferred to later phases: child-side `replyTo` UX polish, thread id routing,
67
+ stale-wait (Phase 8), task-aware watchers (Phase 7), direct child-to-child
68
+ "question to a busy peer" as first-class (transport already supports the
69
+ relay; the request-tracking path targets the parent as the hub).
@@ -0,0 +1,100 @@
1
+ # Phase 7 — Task-aware `shepherd_watch` (design notes)
2
+
3
+ Phase 7 makes `shepherd_watch` observe **tracked tasks** rather than individual
4
+ Pi turns. `shepherd_wait` and the legacy prompt watcher remain for
5
+ prompt-based flows, but new orchestration uses tasks.
6
+
7
+ ## Core idea
8
+
9
+ Tasks settle only from explicit lifecycle events (a child calling
10
+ `shepherd_done`, or an explicit failure / cancellation / timeout). Because that
11
+ settlement always flows through `LifecycleRegistry.settleTask()`, the registry
12
+ already has a single, authoritative settlement point. The task watcher hooks
13
+ into *that* point instead of polling:
14
+
15
+ - `LifecycleRegistry.watchTasks(handles, callback)` registers a one-shot
16
+ observer for task ids. Synchronous, like `watchPrompts`: an already-settled
17
+ task is returned in `completed` immediately, pending tasks are tracked.
18
+ - `LifecycleRegistry.settleTask()` now, after writing the durable result,
19
+ notifies each registered task watcher **exactly once** for that task id
20
+ (mirroring how `settlePrompt` notifies prompt watchers). The callback is
21
+ wrapped in try/catch so a broken notifier can never affect settlement.
22
+ - A `TaskWatcherService` (in `lifecycle.ts`) wraps the registry: it coalesces
23
+ up to `coalesceMs` (25 ms) of completions per watcher and delivers one
24
+ `TaskWatcherNotification`, sorting coalesced completions into the caller's
25
+ input order. The flush timer is `unref()`'d, and `shutdown()` clears timers
26
+ + registry registrations.
27
+
28
+ There is **no polling and no interval**: unlike `PromptWatcherService`
29
+ (which shells out to Herdr every 500 ms to infer prompt completion from
30
+ pane/agent state), a task watcher is driven purely by registry settlement.
31
+ Idle, `agent_end`, `agent_settled`, and `waiting` never call `settleTask`, so
32
+ they can never fire the watcher — the invariant holds by construction.
33
+
34
+ ## Watcher identity / idempotency
35
+
36
+ The registry stores a `watchers` map keyed by `watcherId`, now generalized
37
+ with a `kind: 'prompt' | 'task'` tag, a `taskIds: string[]`, a `pending:
38
+ Set<string>`, and a `delivered: Set<string>`. `settleTask` removes the task's
39
+ entry from `taskWatchers` immediately after reading its watcher ids, so a task
40
+ can never notify the same watcher twice. Per-watcher `pending.size === 0`
41
+ removes the watcher from the map. `clearWatchers()` (called on parent
42
+ shutdown) drops both prompt and task registrations and indices.
43
+
44
+ ## Dispatch and compatibility
45
+
46
+ `doAction('watch')` in `src/extension/shepherd.ts`:
47
+
48
+ 1. Collects the id(s) (single or array).
49
+ 2. Any id that `lifecycleRegistry.isTaskId(id)` accepts is a task; every other
50
+ id must resolve via `getPrompt(id)` or it is rejected with a
51
+ `LifecycleError('invalid_handle')` that names the bad id. Agent ids and
52
+ Herdr pane ids therefore fail with a clear error instead of being silently
53
+ mis-targeted.
54
+ 3. A call cannot **mix** task ids and prompt ids (ambiguous scope) — it throws.
55
+ 4. Task ids -> `taskWatcherService.watch(...)`; prompt ids -> the existing
56
+ `promptWatcherService.watch(...)`.
57
+
58
+ **Chosen compatibility behavior:** `shepherd_watch` **accepts** legacy prompt
59
+ ids (the pre-Phase-7 contract) and routes them to the prompt-watcher path.
60
+ Prompt ids are **not** re-interpreted as task ids; they continue to use the
61
+ prompt lifecycle and its pane/polling semantics. Task ids use the new
62
+ task path. This preserves `shepherd_wait`/prompt flows verbatim while adding
63
+ the task flow.
64
+
65
+ ## Parent notification bridge
66
+
67
+ `configureTaskWatcherBridge(pi)` (extension) registers a
68
+ `shepherd.task.completion` message renderer and a
69
+ `configureTaskWatcherNotifications` handler that, when
70
+ `taskWatcherSessionActive` is true, formats the completion with the standard
71
+ `call:/return:/details:` layout (call name `shepherd_watch`, argument `id` =
72
+ task id or array) and sends a custom message with
73
+ `{ deliverAs: 'followUp', triggerTurn: true }`. A terminal task outcome always
74
+ triggers a parent turn (the child must then decide the next step), matching
75
+ the prompt bridge's policy.
76
+
77
+ `index.ts` toggles `setTaskWatcherSessionActive` on `session_start`/
78
+ `session_shutdown` and calls `shutdownTaskWatchers()` on shutdown so timers are
79
+ released and no notification is queued for a session that is gone.
80
+
81
+ ## Test coverage
82
+
83
+ `test/verify-task-watchers.mjs` (added to the `npm test` chain after
84
+ `message-routing:test`):
85
+
86
+ - Non-blocking registration of a pending task.
87
+ - A task entering `waiting` does *not* complete the watcher (the canonical
88
+ "scout waits on a busy planner" property).
89
+ - No delivery while running/waiting.
90
+ - Completion -> exactly one notification carrying taskId, agentId, status,
91
+ returnCode, agent, label, and summary text.
92
+ - Already-settled task returns immediately and is not re-delivered.
93
+ - Array of task ids: independent settlement, coalesced in watch input order,
94
+ with correct terminal statuses and return codes (completed 0, blocked 2,
95
+ failed 1, cancelled 130, timed_out 124).
96
+ - Cancelled and timed-out tasks report their terminal status/return code.
97
+ - Two independent watchers on the same task each observe it exactly once.
98
+ - Unknown id and duplicate ids are rejected.
99
+ - Extension bridge: one turn-triggering custom follow-up keyed by task id
100
+ (no `promptId`), and delivery is suppressed once the session is deactivated.
@@ -0,0 +1,127 @@
1
+ # Phase 8 — Stale-wait monitoring (design notes)
2
+
3
+ Phase 8 adds a *non-invasive* nudge for a tracked task that is sitting in the
4
+ `waiting` state — i.e. waiting on a required reply that has not yet arrived —
5
+ for longer than a configurable threshold. It never settles a task; it only
6
+ informs the parent that something has been waiting a long time.
7
+
8
+ ## What counts as "stale"
9
+
10
+ A task is stale when **all** of these hold:
11
+
12
+ 1. `task.state === 'waiting'` — the task has entered the `waiting` state.
13
+ 2. `task.pendingReplyMessageId` is set — there is a specifically expected reply
14
+ (an `expectsReply` question, or a child mirror of one). A task that is
15
+ `waiting` for any other reason (a bare `agent_end`, a manual `setTaskWaiting`
16
+ with no outstanding reply) is *not* stale by definition, because there is no
17
+ reply to time out.
18
+ 3. `now - task.waitingSince >= staleWaitThreshold` (minutes, from settings).
19
+ 4. `task.staleNotifiedAt` is unset — the monitor has not yet nudged for this
20
+ waiting episode.
21
+
22
+ `waitingSince` is the timestamp the task entered `waiting` (set in
23
+ `setTaskWaiting` / `openPendingRequest`). The stale condition is evaluated on
24
+ the *task* record, not on the raw Herdr agent state, so an agent that is merely
25
+ idle but owns no waiting task never triggers a stale reminder. A completed,
26
+ failed, cancelled, or blocked task has already left the set of `waiting`
27
+ records and therefore never produces one.
28
+
29
+ ## One notification per episode
30
+
31
+ Stale delivery is idempotent per *episode* (a single contiguous wait), not per
32
+ poll. `markStaleNotified(taskId)` stamps `task.staleNotifiedAt` the moment the
33
+ monitor emits a reminder; the monitor skips a task whenever the flag is present.
34
+ The flag is cleared at every state transition that ends or re-opens a wait:
35
+
36
+ - `setTaskRunning` (a resume) — clears `staleNotifiedAt`.
37
+ - `resolvePendingRequest` / `resolveReplyForTask` (a reply arrived) — clears it.
38
+ - `settleTask` (any terminal outcome) — the task leaves the `waiting` set.
39
+
40
+ Because a *reply* is normally the event that ends a stale wait, the practical
41
+ effect is: one reminder, then a reply (or a manual resume / settle) resets the
42
+ state. If the same task re-enters `waiting` with a new reply later, it is a new
43
+ episode and is entitled to its own reminder. This is exactly the exit-gate
44
+ property: "a reply clears the stale condition."
45
+
46
+ ## Setting: `staleWaitThreshold`
47
+
48
+ `src/extension/config.ts`:
49
+
50
+ - Stored in **minutes**, like `timeout`.
51
+ - Default `5`. `0` (and negative) is a valid way to *disable* reminders
52
+ entirely; the UI exposes this as the `off (no reminders)` choice.
53
+ - `validField` treats `0` as a real value (unlike `timeout`, where `0`/invalid
54
+ means "fall back to the default"), so a user can deliberately turn the
55
+ feature off.
56
+ - In the monitor, a effective threshold `< 1` minute short-circuits the poll:
57
+ no reminder is ever emitted and the monitor stops itself.
58
+
59
+ It lives in both the user layer and the project delta (it is an
60
+ `OverridableField`), appears in the `/shepherd settings` menu, and is
61
+ documented in the README settings table with a dedicated "Stale-wait
62
+ reminders" section.
63
+
64
+ ## The monitor (`StaleWaitMonitor` in `lifecycle.ts`)
65
+
66
+ A self-managing timer that:
67
+
68
+ - **Starts** (`kick()`) only when a task opens a pending reply — the two call
69
+ sites are `sendParentMessage` (`expectsReply` + task id) and the child
70
+ `runtime` mirror in `applyMessageEnvelope`. Both mean the task just entered
71
+ `waiting` on an expected reply.
72
+ - **Polls** at 1s (unref'd — it never keeps the process alive) and inspects
73
+ *task* state.
74
+ - **Stops** itself (`maybeStop()`) as soon as no `waiting` task remains; that
75
+ also covers shutdown via `stopParentBrokerMonitor` →
76
+ `shutdownStaleWaitMonitor()`.
77
+ - Emits **at most one** `StaleWaitInfo` per episode through
78
+ `configureStaleWaitNotifications`.
79
+
80
+ `StaleWaitInfo` carries the full context the parent needs to decide what to do:
81
+ `taskId`, `agentId`/display name, `description`, `waitingSince`, `elapsedMs`,
82
+ the `requestMessageId` being waited on, the `question`, the `recipientId` +
83
+ resolved `recipientName` and the recipient's own lifecycle `recipientState`, and
84
+ the applied `thresholdMinutes`.
85
+
86
+ ## Parent delivery (`src/extension/shepherd.ts`)
87
+
88
+ A new `shepherd.stale.wait` custom message + renderer. It is delivered with
89
+ `deliverAs: 'followUp'` and **`triggerTurn: false`**.
90
+
91
+ That is the deliberate "no wake-up" policy: a stale wait is *information*, not a
92
+ decision point that needs an immediate parent turn. Forcing a turn here would
93
+ (i) wake the parent on every normal long wait and (ii) risk a notification
94
+ storm if several tasks went stale together or the parent were busy. The parent
95
+ sees the reminder in its next turn and can choose to nudge the recipient with
96
+ `shepherd_message`, or simply wait for the reply (or for the reply *deadline*
97
+ to settle the task as `blocked`). The body even lists those possible actions.
98
+
99
+ The reminder never mutates task state; the reply deadline (Phase 6) remains the
100
+ only authoritative mechanism that turns a stale wait into `blocked`.
101
+
102
+ ## Compatibility / invariants preserved
103
+
104
+ - The Phase 5 invariant is untouched: only `shepherd_done` (or an explicit
105
+ failure/cancellation/timeout) settles a tracked task. A stale reminder is a
106
+ pure observation.
107
+ - Existing `setTaskRunning` / `resolve*` / `settleTask` behavior is unchanged
108
+ except for clearing the new `staleNotifiedAt` flag.
109
+ - The `timeout` reply-deadline path is unchanged; stale-wait is additive.
110
+
111
+ ## Test coverage
112
+
113
+ `test/verify-stale-wait.mjs` uses the fake-clock helper to drive time
114
+ deterministically and asserts:
115
+
116
+ - No notification below the threshold; exactly one once crossed.
117
+ - No second notification while the episode remains open (no storm).
118
+ - Full notification content (task, owner, description, question, request id,
119
+ recipient id + state, elapsed time, threshold).
120
+ - A reply clears the episode; a *new* episode re-notifies.
121
+ - A completed task and an idle agent with no waiting task produce nothing.
122
+ - Stale-wait does **not** settle the task (it stays `waiting`); the reply
123
+ deadline is what settles it to `blocked`.
124
+ - The monitor starts only while a waiting task exists and stops when none remain.
125
+ - A disabled (`0`) threshold produces no notification.
126
+ - Bridge delivery is a follow-up with `triggerTurn: false`, and is suppressed
127
+ once the parent session goes inactive.
@@ -0,0 +1,104 @@
1
+ # Phase 9 — Status and TUI integration (design notes)
2
+
3
+ Phase 9 makes the *status surface* aware that a pi-shepherd agent now tracks
4
+ two independent dimensions: the **Herdr process state** (`working` /
5
+ `idle` / `done` / …) and the **tracked task state** (`created` / `running` /
6
+ `waiting` / terminal). The critical interaction: a child whose process is
7
+ `idle` may own a task that is `waiting` on a required reply — and vice versa.
8
+ Reporting only the process state (the pre-Phase 9 behavior) made in-flight
9
+ work invisible exactly when the child was parked.
10
+
11
+ ## Status model
12
+
13
+ `AgentStatus` (`src/core/orchestration.ts`) gained an optional `task`
14
+ (`AgentTaskStatus`) alongside the process-level `state`. The view is produced
15
+ by a new `LifecycleRegistry.taskStatusForAgent(record)` which:
16
+
17
+ - returns `undefined` when the agent owns no open task (a settled task is not
18
+ "active" and is dropped — an intentional status semantics, not an error);
19
+ - surfaces `id`, `state`, `description`, and only the *applicable* optional
20
+ fields: `waitingSince` / `waitingMs` (age of the current `waiting` episode),
21
+ `pendingRequestMessageId` (the expected reply), `waitingRecipient` (the
22
+ display name of the agent the reply is expected from), and `stale` (true
23
+ once the Phase 8 monitor has reminded for this episode).
24
+ - never touches Herdr; everything is in-memory registry state, so
25
+ `shepherd_status` and the widget poll can both call it cheaply.
26
+
27
+ `registry.status()` now includes the task view; `statusAgent()` (lifecycle)
28
+ still resolves live process state from the pane when one exists, but the task
29
+ view comes from the registry in either path.
30
+
31
+ The `status` doAction case in `src/extension/shepherd.ts` maps that into a
32
+ compact **public** result:
33
+
34
+ ```json
35
+ {
36
+ "id": "shepherd-agent-…",
37
+ "state": "idle",
38
+ "task": {
39
+ "id": "shepherd-task-…",
40
+ "state": "waiting",
41
+ "waitingMs": 423120,
42
+ "pendingRequest": "shepherd-message-…",
43
+ "waitingOn": "planner: rollout-planner",
44
+ "stale": true
45
+ }
46
+ }
47
+ ```
48
+
49
+ and the summary text names both dimensions: `agent idle; task
50
+ shepherd-task-… waiting.` Opaque agent/task ids are passed through verbatim;
51
+ Herdr pane ids stay internal diagnostics (they are only present on the
52
+ `AgentStatus` shape, not on the public `status` result or the rendered
53
+ output).
54
+
55
+ ## Status widget projection
56
+
57
+ `src/core/herdr.ts`:
58
+
59
+ - `activeTasksByPane()` maps paneId → active task (registry read only).
60
+ - `workingOrWaitingSubagents()` extends the old `workingSubagents()` filter:
61
+ an owned pane is listed when `state !== "idle"` **or** the pane's agent
62
+ owns an open task. This is the "do not filter waiting tasks out because the
63
+ process is idle" rule. `workingSubagents()` is retained as a working-only
64
+ projection; the widget uses the new query. Session-ownership filtering
65
+ (`paneOwner === sessionOwner`) is unchanged, so foreign sessions' panes are
66
+ still excluded.
67
+
68
+ `index.ts` (the widget):
69
+
70
+ - the per-second snapshot now attaches each row's `task` view;
71
+ - the header counts both dimensions: `N working · N waiting`;
72
+ - while a task is open the **task state** wins the right-hand label: a working
73
+ process with a `waiting` task renders `waiting`, not `working` (the process
74
+ is churning but the *work* is blocked);
75
+ - waiting rows append ` ⏳<minutes>m ←<recipient>` (elapsed wait + who still
76
+ has to answer). `stateIcon` renders them with the existing waiting glyph,
77
+ and a stale episode renders `waiting (stale)`.
78
+ - pane ids and opaque task ids are never painted into rows; only display
79
+ names, state labels, and the wait marker appear. Polling cadence is
80
+ unchanged (the 1s unref'd interval + sheep-animation interval); the task
81
+ overlay adds no new I/O.
82
+
83
+ ## Tests
84
+
85
+ - `test/verify-status.mjs` (new): process/task independence (idle+waiting,
86
+ working+running, no-task), waiting fields (age, pending request,
87
+ recipient, stale flag and its clearing on reply), completed-task removal
88
+ from the view, and the public `doAction('status')` mapping (opaque ids
89
+ only, no pane leakage, dual-state summary text).
90
+ - `test/verify-status-widget.mjs` (extended): three snapshot phases over a
91
+ fake Herdr with one working pane (plain), one working pane with a running
92
+ task, one idle pane with a waiting+stale task, and a foreign working pane.
93
+ Phase 1/2 cover crash regression, cwd-driven emojiSheep (🐑 vs plain),
94
+ session-ownership filtering, pane-id opacity, and row-width fit. Phase 3
95
+ settles the waiting task and asserts the idle pane drops out of the widget.
96
+
97
+ ## Invariants
98
+
99
+ - Phase 5 completion invariant untouched: status is a pure read; nothing here
100
+ settles or mutates tasks.
101
+ - Idle ≠ done: an idle process with a waiting task remains visible in every
102
+ status surface (exit gate: "an idle waiting scout remains visible").
103
+ - No new mailbox reads per render frame; the widget only ever reads the
104
+ in-memory registry plus the existing Herdr `agent list` snapshot.