@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,145 @@
1
+ # Journal — 007 unwatched completion notice
2
+
3
+ ## Status — 2026-10-18
4
+
5
+ - **Scope: implement all of spec 007** (unseen-settlement ledger + settle
6
+ boundary / idle-wake notice). The design is the approved direction in
7
+ GitHub issue #15.
8
+ - Branch: `feat/007-unwatched-completion-notice`, created off `main`.
9
+ - No auto-watch on `delegate`; no child-side `task_done_ack` (deferred); no
10
+ broker protocol, tool schema, prompt, or settings changes; no new
11
+ dependencies; existing `verify-*.mjs` suites must stay untouched.
12
+ - **Merge condition:** reviewer pass + `npm test` green (existing suites
13
+ untouched, new `verify-unseen-completions` in the chain) + live smoke
14
+ (an unwatched settlement produces the boundary notice with the retrieval
15
+ command; `shepherd_watch` retrieves the result; no duplicate notice).
16
+ Then merge `feat/007-unwatched-completion-notice` back into `main`.
17
+ - **Status: implemented, reviewed, and verified.** Full `npm test`
18
+ EXIT=0 with 487 PASS assertions (new suite in the chain; no existing
19
+ test file modified); live Herdr smoke ALL PASS twice, including once
20
+ after the review fixes.
21
+
22
+ ## Decisions
23
+
24
+ - The runtime-neutral seam is a registry observer:
25
+ `onTaskSettled(result, { hadWatchers, agent?, label?, source? })`, fired
26
+ after the watcher fan-out on the transition into a terminal task state.
27
+ - The ledger is pure core (`src/core/unseen-completions.ts`, singleton like
28
+ `taskWatcherService`, structural `UnseenSettlement`, no runtime imports);
29
+ delivery policy lives in `src/extension/unseen-completions.ts`.
30
+ - The ledger is a queue of **un-noticed** settlements: notify drains the
31
+ entry, so notify-once and loop-safety hold by construction. Entries clear
32
+ on retrieval (watch action) / close (`clearForAgent`, reported) / session
33
+ end.
34
+ - Clearing for a late `shepherd_watch` lives in the **watch action**, not
35
+ the watcher notifier: settled tasks are delivered inline inside
36
+ `TaskWatcherService.watch` before the watcher id exists, so the notifier
37
+ never sees them.
38
+ - Parent-initiated cancellations (`shepherd_close` → `cancelled`) never
39
+ enter the ledger; neither do `delegateAgent` submission failures (tagged
40
+ `source: "delegate-submission-failure"` — the Shepherd already sees the
41
+ error in the tool result).
42
+ - No persistence: the ledger is session-scoped like the task registry.
43
+ - The bridge is wired in `index.ts` (parent surface), not in
44
+ `registerShepherdTools`, and subscribes only while a parent session is
45
+ active.
46
+
47
+ ## Log
48
+
49
+ - 2026-10-18: spec/plan/tasks drafted
50
+ (`specs/007-unwatched-completion-notice/`), branch
51
+ `feat/007-unwatched-completion-notice` created off `main`.
52
+ - 2026-10-18: static spec review delegated to the `reviewer` sheep
53
+ (`shepherd-task-3a2282a0-d0e0c413-…`), watcher registered.
54
+ - 2026-10-18: review returned 3 Critical + 6 Warning + suggestions; verified
55
+ against source and folded in before the implementation commit:
56
+ 1. clear-on-watch was impossible as specified (late delivery bypasses the
57
+ notifier) → clear in the watch action;
58
+ 2. wiring inside `registerShepherdTools` would break six fake-pi suites →
59
+ wire in `index.ts` after the worker guard, session-scoped subscription,
60
+ `sendMessage` surface guard;
61
+ 3. the core ledger could not import `TaskResult` from the Herdr runtime →
62
+ structural `UnseenSettlement` in core;
63
+ 4. observer context now carries `agent`/`label`/`source`;
64
+ 5. delegate submission failures no longer produce a false notice;
65
+ 6. `details` uses `settlements` (the generic collapsed formatter owns
66
+ `completions`); close reports dropped entries; drop-on-notify replaces
67
+ the `unseen|notified` two-state design; debounce/ledger injectable for
68
+ deterministic tests; docs fix for the stale "follow-ups" wording.
69
+ - 2026-10-18: implementation delegated to worker-05
70
+ (`shepherd-task-3a2282a0-93277d49-…`, watched). It delivered the ledger,
71
+ observer + `source` tag, bridge, wiring, tests, and docs without
72
+ committing. I inspected the diff, ran the full suite, and ran the live
73
+ smoke, which caught one harness bug (counting every `sendMessage` instead
74
+ of the unseen-notice custom type) and then passed.
75
+ - 2026-10-18: independent code review delegated to reviewer-05
76
+ (`shepherd-task-3a2282a0-713bd813-…`, watched). Verdict: **no
77
+ Critical**; all 3 spec-review Criticals and all 8 warnings confirmed
78
+ fixed, boundary semantics cross-checked against pi's runner internals.
79
+ Two warnings fixed after review: (a) `hadWatchers` no longer counts a
80
+ callback-less watcher registration as observed, and (b) the test suite
81
+ now guards the delegate-failure source tag end-to-end and watched
82
+ settlement suppression at the bridge level.
83
+ - 2026-10-18: post-review polish adopted from the suggestions: summary
84
+ detail falls back to error text on an empty summary and is clipped at
85
+ 200 chars (full result stays one `shepherd_watch` away); the renderer
86
+ falls back to message content when `details.settlements` is absent;
87
+ `agent_settled` no longer schedules an empty-ledger timer; the boundary
88
+ comment names the cross-extension projection trigger. Not adopted:
89
+ clearing on `waitForTasks` retrieval (not reachable from the tool
90
+ surface; the spec defines clearing on the watch action and the notice is
91
+ accurate) and close-details duplication (consistent with existing
92
+ actions).
93
+ - 2026-10-18: final verification after the fixes: `npm test` EXIT=0,
94
+ 487 PASS, no failures; live smoke ALL PASS; then merge to `main`.
95
+
96
+ ## Landing — 2026-10-18
97
+
98
+ - Landed on `main` as `93fafe8` (fast-forward from
99
+ `feat/007-unwatched-completion-notice`).
100
+ - Evidence at landing: `npm test` EXIT=0, 487 PASS assertions (new
101
+ `unseen-completions:test` in the chain; every pre-existing suite
102
+ untouched); live Herdr smoke ALL PASS — a real spawned worker with no
103
+ watcher produced exactly one boundary notice (`continue: true`) while
104
+ busy, exactly one coalesced `triggerTurn` notice while idle, and
105
+ `shepherd_watch` retrieval of the settled task cleared the ledger with
106
+ no duplicate notice.
107
+ - Review: reviewer-05 found no Critical; all three spec-review Criticals
108
+ and all eight warnings were verified fixed before merge.
109
+ - Deferred non-goals (kept in issue #15): auto-watch on delegate;
110
+ child-side `task_done_ack`; ledger persistence across sessions; a
111
+ fallback when a watcher exists but its notification delivery is
112
+ swallowed; clearing on `waitForTasks` retrieval.
113
+
114
+ ## Correction — 2026-10-19
115
+
116
+ - **Defect (#16):** the `agent_before_settle` handler bailed out when
117
+ `event.context.canContinue` was false. pi builds that snapshot from the
118
+ entries that existed *before* the handler runs (`emitBoundary` in
119
+ `dist/core/extensions/runner.js`), so at a completed boundary it is
120
+ `finalRole === 'assistant'` and therefore always false: the primary
121
+ boundary route was dead code and only the 250ms idle wake ever delivered
122
+ a notice. `pi -p` lost notices entirely — the unref'd timer never fires
123
+ and `session_shutdown` clears the ledger.
124
+ - **Fix:** `ccf339c` drops the pre-entry guard. The handler always returns
125
+ `{ entries: [entry], continue: true }` for a completed run with pending
126
+ entries; `_runBeforeSettleBoundary` in `dist/core/agent-session.js`
127
+ commits the drafts via `_commitBoundaryDrafts` and only then recomputes
128
+ `finalContext.canContinue` via `_buildBoundaryContext`, where a committed
129
+ `custom_message` projects through `convertToLlm` as a user-role message.
130
+ - **Live evidence (real pi):** the `pi -p` probe logs
131
+ `canContinue=true pending=0` followed by exactly one continuation
132
+ (previously `canContinue=false pending=1` and the notice was discarded);
133
+ an unwatched child settling mid-turn is announced 61ms after the
134
+ turn-end marker. That is faster than the 250ms idle-wake debounce, so the
135
+ idle path cannot have produced it and the boundary route is demonstrably
136
+ the delivering path.
137
+ - **This entry (#17)** corrects the test and spec contract that still
138
+ pinned the old behavior: the suite's busy-boundary fixture used a
139
+ synthetic `canContinue: true` (a pre-entry shape pi only emits when
140
+ queued or pending messages already exist) and asserted that
141
+ `canContinue: false` returns `undefined`; `spec.md` plus the plan/tasks
142
+ notes described the same pre-entry assumption. Fixtures now use pi's
143
+ real clean-boundary shape and assert the continuation, with a drift-guard
144
+ comment naming the pi internals; the post-commit gate stays covered by
145
+ the real-pi probe, not the hermetic suite.
@@ -0,0 +1,186 @@
1
+ # Implementation Plan: Unwatched completion notice
2
+
3
+ This plan implements `spec.md` (reviewer fixes folded in). Three stages:
4
+ core detection + ledger, extension notice delivery, verification + docs. No
5
+ behavior change for watched tasks, no broker or tool-surface change.
6
+
7
+ ## Files
8
+
9
+ | File | Change |
10
+ |---|---|
11
+ | `src/core/unseen-completions.ts` | new: `UnseenCompletionLedger` + singleton, structural `UnseenSettlement` |
12
+ | `src/runtimes/herdr/orchestration.ts` | `onTaskSettled(listener)` observer + `source` tag on the delegate failure settle |
13
+ | `src/runtimes/herdr/lifecycle.ts` | tag the `delegateAgent` failure settle with `source: "delegate-submission-failure"` |
14
+ | `src/extension/unseen-completions.ts` | new: session-scoped subscription, activity tracking, idle wake, boundary continuation, renderer |
15
+ | `src/extension/shepherd.ts` | export `renderShepherdNotification`; clear-on-watch in the `watch` action; clear-on-close with report in the `close` action |
16
+ | `index.ts` | call `configureUnseenCompletionBridge(pi)` after the worker guard (parent surface only) |
17
+ | `test/verify-unseen-completions.mjs` | new suite (core cases first, bridge cases added in Stage 3) |
18
+ | `package.json` | register `unseen-completions:test` in the `test` chain |
19
+ | `README.md`, `docs/guides/tool-reference.md` | watch/notification behavior note; fix the stale "follow-ups" wording |
20
+
21
+ ## Stage 1 — Detection + ledger (core)
22
+
23
+ 1. `UnseenCompletionLedger` (`src/core/unseen-completions.ts`):
24
+ - `tasks: Map<taskId, UnseenSettlement>` insertion-ordered.
25
+ - `record` flattens a `TaskResult` + observer context into
26
+ `UnseenSettlement`; returns false for `hadWatchers === true`,
27
+ `status === "cancelled"`, `source === "delegate-submission-failure"`,
28
+ or an existing entry.
29
+ - `pending()`; `drain(ids)`; `clear(ids): string[]`;
30
+ `clearForAgent(agentId): string[]`; `clearAll()`.
31
+ - Pure module: only builtins; no `@earendil-works/*`, `src/runtimes/`,
32
+ or `src/extension/` imports. Export the class and the
33
+ `unseenCompletionLedger` singleton.
34
+ 2. Registry observer in `orchestration.ts`:
35
+ - `private readonly settlementListeners = new Set<...>()`.
36
+ - `onTaskSettled(listener)` adds and returns an unsubscribe function.
37
+ - Compute `hadWatchers` in the fan-out by marking when
38
+ `notifyTaskWatcher(...)` actually runs (the watcher `delivered` check
39
+ already gates duplicates), capture the agent handle for
40
+ `agent`/`label`, then invoke listeners inside a `try/catch` after the
41
+ fan-out. Pass `{ ...result }` and a fresh context object; carry the
42
+ internal `source` tag through from `settleTask`.
43
+ - Fire only on the transition to terminal (the existing early-return for
44
+ already-settled tasks stays untouched); prompt settlement paths are not
45
+ touched.
46
+ - `settleTask` gains an optional internal options argument for `source`;
47
+ only `delegateAgent`'s failure path in `lifecycle.ts` passes it.
48
+
49
+ Rationale: the observer gives one runtime-neutral seam. The extension
50
+ subscribes; tests can subscribe directly. The durable runtime (spec 006,
51
+ Phase 1) implements the same hook instead of duplicating the ledger.
52
+
53
+ ## Stage 2 — Notice delivery (extension)
54
+
55
+ `src/extension/unseen-completions.ts`, module state:
56
+
57
+ - `active` subscription flag, `unsubscribe`, `idle` boolean (default true),
58
+ `flushTimer`, captured lifecycle `ctx`.
59
+ - `configureUnseenCompletionBridge(pi, options?: { coalesceMs?, ledger? })`:
60
+ - `pi.on("session_start")` → `clearAll()`, idle, subscribe to
61
+ `ledger`'s registry observer (`lifecycleRegistry.onTaskSettled`) if not
62
+ already subscribed. Idempotent across repeated session starts.
63
+ - `pi.on("agent_start")` → busy; `pi.on("agent_settled")` → idle +
64
+ `scheduleIdleWake()` (no-op without pending entries; catches settlements
65
+ whose boundary did not run).
66
+ - `pi.on("session_shutdown")` → clear timer, `clearAll()`, unsubscribe,
67
+ reset to idle.
68
+ - `pi.on("agent_before_settle", event => ...)`:
69
+ - return `undefined` unless `event.outcome === "completed"`,
70
+ - **and** the ledger has pending entries (no pre-entry
71
+ `event.context.canContinue` check: that snapshot predates our draft,
72
+ and pi recomputes `canContinue` after committing the drafts; #16),
73
+ - build the `custom_message` entry, drain its task ids, and return
74
+ `{ entries: [entry], continue: true }`.
75
+ - `pi.registerMessageRenderer("shepherd.task.unseen", ...)` using
76
+ `renderShepherdNotification` (exported from `shepherd.ts`) with the
77
+ notice formatter reading `details.settlements`.
78
+ - Observer callback:
79
+ `lifecycleRegistry.onTaskSettled((result, context) => {
80
+ if (ledger.record(result, context)) scheduleIdleWake(); })`.
81
+ - `scheduleIdleWake()`: return if a timer is pending or not idle;
82
+ `setTimeout(flush, coalesceMs)` (unref) → `flush()`:
83
+ - return unless `typeof pi.sendMessage === "function"`, idle, and
84
+ `ledger.pending().length > 0`;
85
+ - build the notice, `pi.sendMessage(notice, { triggerTurn: true })`,
86
+ drain only after the synchronous call returns without throwing;
87
+ wrap in try/catch so a throw leaves entries pending.
88
+ - Notice formatter (exported for tests) produces the exact spec text:
89
+ header `Shepherd notice — N task(s) settled with no watcher attached:`,
90
+ per-entry `- <taskId> (<agent>[, "label"]): <status> — <summary|error>`,
91
+ and `Full results: shepherd_watch({ id: [ "id", ... ] })`.
92
+
93
+ Wiring in `src/extension/shepherd.ts`:
94
+
95
+ - Export `renderShepherdNotification` (its internals stay private; new
96
+ module imports it — no cycle because `shepherd.ts` imports only the core
97
+ ledger).
98
+ - In the `watch` action, after `taskWatcherService.watch(taskIds)` returns:
99
+ `unseenCompletionLedger.clear(registration.taskIds)`. Do **not** add
100
+ clearing to the watcher notifier: late `shepherd_watch` deliveries never
101
+ reach it (verified against `TaskWatcherService.watch` and
102
+ `verify-task-watchers.mjs`).
103
+ - In the `close` action, after `runtime.close(id)` succeeds:
104
+ `const cleared = unseenCompletionLedger.clearForAgent(handle.id)` and
105
+ append a report line/details when `cleared.length > 0`.
106
+
107
+ Wiring in `index.ts` (after `if (process.env.PI_SHEPHERD_SESSION) return;`
108
+ and `registerShepherdTools(pi)`, line ~447):
109
+
110
+ - `configureUnseenCompletionBridge(pi);`
111
+ - Not inside `registerShepherdTools` (six suites pass fakes without `on`
112
+ and with renderer allow-lists).
113
+
114
+ ## Stage 3 — Tests, docs, verification
115
+
116
+ - `test/verify-unseen-completions.mjs` (created in Stage 1 for core cases,
117
+ extended here):
118
+ - ledger: cancelled excluded; had-watchers excluded;
119
+ delegate-submission-failure excluded; dedupe; drain; `clear` /
120
+ `clearForAgent` return ids; `clearAll`.
121
+ - observer: settle with watcher → `hadWatchers: true`; without → `false`
122
+ + agent/label; `source` passthrough; listener throw does not break
123
+ `settleTask`; unsubscribe works.
124
+ - bridge with a fake pi surface (capture `on`,
125
+ `registerMessageRenderer`, `sendMessage` like
126
+ `test/verify-parent-surface.mjs`): idle burst → exactly one
127
+ `triggerTurn` send and no duplicates; busy settle → single
128
+ `agent_before_settle` result with `continue: true`; second boundary →
129
+ `undefined`; `aborted` outcome → no continuation; a completed boundary
130
+ with `canContinue: false` (pi's real pre-entry shape) → still
131
+ continues; late `shepherd_watch` clears (assert through the real watch
132
+ action or a direct `clear`); close clears and reports; renderer
133
+ registered; fake pi without `sendMessage` never throws; unsubscribe on
134
+ `session_shutdown`.
135
+ - Use injected `coalesceMs` and an isolated ledger instance to keep the
136
+ suite deterministic.
137
+ - Register `unseen-completions:test` in `package.json` and append it to
138
+ the `test` chain.
139
+ - Full `npm test` green with all existing suites untouched.
140
+ - Docs: README `### Delegate, then watch` gains the no-watcher notice
141
+ paragraph; `docs/guides/tool-reference.md` `shepherd_watch` entry notes
142
+ that unwatched settlements surface at the next settle boundary or as one
143
+ idle wake, and that `shepherd_watch` still retrieves settled tasks
144
+ synchronously. While there, fix the pre-existing "delivered as
145
+ follow-ups" wording in the `shepherd_watch` description
146
+ (`docs/guides/tool-reference.md`, `src/extension/shepherd.ts` ~1570) to
147
+ match the actual `steer` delivery.
148
+ - Live smoke (throwaway script): delegate to a real agent without a watch,
149
+ confirm the boundary notice + retrieval command; confirm `shepherd_watch`
150
+ returns the result and no duplicate notice follows.
151
+
152
+ ## Risks and decisions
153
+
154
+ - **pi boundary continuation safety** — guarded by the pending → drained
155
+ transition; a second boundary with no new entries returns `undefined`.
156
+ - **Boundary `valid: false` drop window** — entries are drained when handed
157
+ to pi; a pi-side rejection is not retried (documented residual). The
158
+ entry is a well-formed `CustomMessageEntryDraft`, so rejection is
159
+ unlikely.
160
+ - **Busy/idle desync** — `agent_settled` always transitions to idle and
161
+ re-checks pending entries, so a missed boundary (abort/error) still
162
+ yields one idle wake; `ctx.isIdle()` is preferred when available.
163
+ - **Delegate failure false positive** — eliminated by the
164
+ `delegate-submission-failure` source tag.
165
+ - **Send failure** — synchronous throw keeps entries pending; no unbounded
166
+ retry. `sendMessage` has no return value, so an async failure inside pi is
167
+ invisible (same as existing bridges).
168
+ - **Race: watcher registers between drain and flush** — `clear` in the
169
+ watch action removes the entry; a notice already sent can list a just
170
+ retrieved entry, which is harmless (the model still has the result). No
171
+ locking added.
172
+ - **Close drops pending entries** — reported in the close tool result so
173
+ nothing vanishes silently.
174
+ - **No persistence** — a parent restart drops the ledger with the
175
+ session-scoped registry; recovery for orphaned children is unchanged and
176
+ outside this spec.
177
+ - **Existing suites** — subscription is session-scoped and the busy-pi
178
+ flush checks the `sendMessage` surface, so suites that settle tasks with
179
+ fake pi objects never break.
180
+
181
+ ## Verification gates
182
+
183
+ 1. Stage 1 + 2 unit suites green.
184
+ 2. Full `npm test` green, existing suites untouched.
185
+ 3. Live smoke passes (notice delivered, retrieval works, no duplicate).
186
+ 4. No new dependencies; no tool schema, prompt, or settings diff.
@@ -0,0 +1,284 @@
1
+ # Unwatched completion notice
2
+
3
+ ## Status
4
+
5
+ Reviewed specification (reviewer pass 2026-10-18 folded in, see journal).
6
+ No behavior change yet. Implements the approved direction in issue #15
7
+ (`bug: unwatched task completions are silently missed`).
8
+
9
+ ## Summary
10
+
11
+ A tracked task that settles while the Shepherd has zero watchers is
12
+ currently silent: `settleTask` fans out only to registered watchers
13
+ (`src/runtimes/herdr/orchestration.ts`), so the durable result is never
14
+ surfaced and an idle Shepherd can sleep through it.
15
+
16
+ Add an **unseen-settlement ledger** and a parent-side notice:
17
+
18
+ - **Shepherd busy** → the notice is appended at pi's `agent_before_settle`
19
+ boundary and the handler returns `continue: true` for one extra model
20
+ request. No mid-turn interruption; the batch is read at the point where
21
+ the run would otherwise end.
22
+ - **Shepherd idle** → one coalesced notice sent with
23
+ `pi.sendMessage(..., { triggerTurn: true })`. This is the overnight
24
+ guarantee.
25
+ - **Aborted/errored run** → no boundary continuation; entries stay pending
26
+ and the idle path still delivers them once.
27
+
28
+ `shepherd_watch` stays the explicit, opt-in batching primitive (choose when
29
+ to become observable, choose which set of agents is one wake-up batch).
30
+ `shepherd_delegate` stays subscription-free. Nothing auto-subscribes.
31
+
32
+ ## Problem
33
+
34
+ - `src/runtimes/herdr/orchestration.ts` — the task settlement fan-out
35
+ delivers only to `taskWatchers`; with zero watchers the result is durable
36
+ but unobserved.
37
+ - `src/extension/shepherd.ts` — `taskWatcherService.watch(...)` is the only
38
+ subscription point (the `watch` action). `delegate` never subscribes.
39
+ - Incident (issue #15): task `shepherd-task-3a2282a0-1dcb4518-…` settled
40
+ `completed` at 11:50:50 with no watcher; no notification was ever
41
+ delivered; a later explicit `shepherd_watch` recovered it at 11:53.
42
+ - Delivery machinery itself works mid-turn when a watcher exists
43
+ (`TaskWatcherService.flush` → `configureTaskWatcherBridge` →
44
+ `pi.sendMessage` with `steer`), so the gap is purely "no subscriber".
45
+
46
+ ## Goals
47
+
48
+ - Every non-cancelled tracked-task settlement that had no watcher at settle
49
+ time is surfaced: delivered at the next boundary, or via one wake when the
50
+ Shepherd is idle.
51
+ - Preserve `watch` flexibility: explicit timing and multi-task batching
52
+ remain the Shepherd's choice; no auto-watch.
53
+ - Overnight safety: an idle Shepherd cannot sleep through a completion
54
+ batch; a busy Shepherd is never interrupted mid-run.
55
+ - Notify once per settlement; no continuation loops; results stay
56
+ retrievable until retrieved or closed.
57
+ - Zero change for watched tasks, legacy prompt watchers, lifecycle timing,
58
+ broker protocol, tool schemas, and settings.
59
+
60
+ ## Non-goals
61
+
62
+ - Auto-watch on `delegate` (rejected in issue #15).
63
+ - Child-side `shepherd_done` return changes and a `task_done_ack` envelope
64
+ (deferred in issue #15).
65
+ - Broker envelope/schema changes of any kind.
66
+ - Persisting the ledger across sessions; it is in-memory and session-scoped
67
+ like the task registry.
68
+ - Changes to legacy prompt watchers, watcher delivery mode (`steer`), or
69
+ watcher batching semantics.
70
+ - New model-facing tools; a `shepherd_status` unseen-count is a possible
71
+ follow-up, not part of this spec.
72
+
73
+ ## Design
74
+
75
+ ### 1. Detection: registry settlement observer
76
+
77
+ Add `onTaskSettled(listener): () => void` to the task registry
78
+ (`src/runtimes/herdr/orchestration.ts`). It fires once per actual
79
+ transition into a terminal task state, after the watcher fan-out, with:
80
+
81
+ - `result`: a shallow copy of the settled `TaskResult`, and
82
+ - `context: { hadWatchers: boolean; agent?: string; label?: string;
83
+ source?: "delegate-submission-failure" }`
84
+ - `hadWatchers` means "at least one watcher callback was invoked for
85
+ this settlement";
86
+ - `agent`/`label` come from the settled agent's handle so the notice can
87
+ name the sheep without a registry lookup;
88
+ - `source` lets callers mark settlements that are not unseen-at-source
89
+ (see below).
90
+
91
+ - The observer is inert until subscribed; no existing call site changes
92
+ behavior.
93
+ - Listener errors must never affect settlement (same discipline as the
94
+ existing watcher callbacks).
95
+ - Prompt (legacy) settlements are not observed.
96
+ - **Delegate submission failure is not an unseen completion.** When
97
+ `delegateAgent` fails before the child ever receives the task, it settles
98
+ the task `failed` and throws; the Shepherd already sees the error in the
99
+ `shepherd_delegate` tool result. That settle path passes
100
+ `source: "delegate-submission-failure"` and the ledger ignores it.
101
+ - The hook is a registry capability, not one of the seven
102
+ `ShepherdRuntime` methods. When the durable runtime lands (spec 006,
103
+ Phase 1+), its registry equivalent must expose `onTaskSettled` with the
104
+ same semantics; the extension subscribes through the active runtime's
105
+ registry instead of importing the Herdr module directly.
106
+
107
+ ### 2. Ledger: `src/core/unseen-completions.ts`
108
+
109
+ A small pure module exporting `UnseenCompletionLedger` plus a module-level
110
+ singleton `unseenCompletionLedger`, matching the `taskWatcherService`
111
+ precedent. It must import nothing from `@earendil-works/*`,
112
+ `src/runtimes/`, or `src/extension/`; it defines its own structural result
113
+ shape so it never depends on the Herdr runtime:
114
+
115
+ ```ts
116
+ export interface UnseenSettlement {
117
+ taskId: string;
118
+ agentId: string;
119
+ agent?: string;
120
+ label?: string;
121
+ status: "completed" | "blocked" | "failed" | "timed_out";
122
+ ok: boolean;
123
+ returnCode: number;
124
+ text?: string;
125
+ error?: string;
126
+ }
127
+ ```
128
+
129
+ The ledger is a **queue of settlements that have not yet been noticed**,
130
+ keyed by `taskId`, in insertion order. Entries exist only while un-noticed;
131
+ notifying (boundary or idle) drains them. API:
132
+
133
+ - `record(result, { hadWatchers, agent?, label?, source? }): boolean` — adds
134
+ only when `hadWatchers === false`, `source !== "delegate-submission-failure"`,
135
+ `result.status !== "cancelled"`, and no entry exists. Returns whether a
136
+ new entry was added.
137
+ - `pending(): ReadonlyArray<UnseenSettlement>` — un-noticed entries in
138
+ insertion order.
139
+ - `drain(taskIds: string[]): void` — called after a notice was successfully
140
+ handed to pi (boundary entry appended / idle send returned).
141
+ - `clear(taskIds: string[]): string[]` — retrieval; returns removed ids.
142
+ - `clearForAgent(agentId: string): string[]` — close; returns removed ids
143
+ so the close tool result can report what was dropped.
144
+ - `clearAll(): void` — session lifecycle.
145
+
146
+ Excluded: parent-initiated cancellations (`shepherd_close` → `cancelled`)
147
+ and delegate submission failures. Included: `completed`, `blocked`,
148
+ `failed`, `timed_out`.
149
+
150
+ ### 3. Notice content
151
+
152
+ Custom message `customType: "shepherd.task.unseen"`, `display: true`,
153
+ `details: { taskIds, settlements }`:
154
+
155
+ ```text
156
+ Shepherd notice — N task(s) settled with no watcher attached:
157
+ - shepherd-task-… (worker "label"): completed — summary
158
+ - shepherd-task-… (reviewer): failed — error
159
+ Full results: shepherd_watch({ id: [ "id", ... ] })
160
+ ```
161
+
162
+ - `details` uses `settlements`, not `completions`: the generic collapsed
163
+ formatter (`formatCollapsedNotification` in `src/extension/shepherd.ts`)
164
+ special-cases `details.completions` with watcher wording, which would
165
+ replace the notice text in collapsed view.
166
+ - The custom type gets its own renderer (via the existing
167
+ `renderShepherdNotification` helper, which must be exported from
168
+ `shepherd.ts` for that purpose); the renderer formats from `settlements`
169
+ and never falls through to the watcher formatter.
170
+ - The wording must say "no watcher attached", never "never retrievable": a
171
+ watcher registered after settlement still receives the result
172
+ synchronously. The notice never claims the result is lost.
173
+
174
+ ### 4. Delivery policy
175
+
176
+ New extension bridge `src/extension/unseen-completions.ts`,
177
+ `configureUnseenCompletionBridge(pi, options?)`.
178
+
179
+ - **Wiring point:** called from `index.ts` after the
180
+ `PI_SHEPHERD_SESSION` worker guard, next to `registerShepherdTools(pi)`
181
+ — *not* inside `registerShepherdTools`. Six existing suites call
182
+ `registerShepherdTools` with fake pi objects that have no `on` and an
183
+ allow-list of renderer custom types (`verify-tool-schemas.mjs`,
184
+ `verify-compat.mjs`, `verify-delegate.mjs`, `verify-stale-wait.mjs`,
185
+ `verify-task-watchers.mjs`, `verify-watchers.mjs`); wiring there would
186
+ break them. The index factory is exercised by suites that already pass
187
+ `on` + `registerMessageRenderer` and is the real parent surface.
188
+ - **Session-scoped activation:** the bridge registers the `onTaskSettled`
189
+ subscription on `session_start` and releases it on `session_shutdown`; a
190
+ process that only imports the factory and settles tasks without a
191
+ session never records anything. Re-subscription is idempotent
192
+ (repeated `session_start` keeps one subscription).
193
+ - **Options:** `{ coalesceMs?, ledger? }`, defaulting to
194
+ `UNSEEN_NOTICE_COALESCE_MS = 250` and the `unseenCompletionLedger`
195
+ singleton, so tests can inject small timings and an isolated ledger.
196
+ - **Idle detection:** the bridge tracks busy/idle from `agent_start` →
197
+ busy, `agent_settled` → idle, `session_start` → idle, and prefers
198
+ `ctx.isIdle()` from the captured lifecycle context when available
199
+ (`ExtensionContext.isIdle()`, pi types line 236). `pi.sendMessage` during
200
+ the run-start window joins the starting run, so the fallback is safe.
201
+ - **Surface guard:** `flush` no-ops unless `pi.sendMessage` is a function;
202
+ the fake-pi suites stay safe even if a timer fires.
203
+
204
+ Idle wake:
205
+
206
+ - `record()` returning true while idle schedules one debounced flush. A
207
+ burst produces exactly one `pi.sendMessage(notice, { triggerTurn: true })`
208
+ covering all pending entries; entries are drained after the call returns
209
+ without throwing.
210
+ - If the timer fires while busy, it does nothing; the boundary path owns
211
+ delivery.
212
+ - Delivery is best-effort: `pi.sendMessage` returns `void`, so only a
213
+ synchronous throw is observable; that throw leaves entries pending so a
214
+ later boundary/wake retries. Rejections and async failures inside pi are
215
+ invisible and are not retried (consistent with the existing bridges).
216
+ - `session_shutdown` clears the timer; pending entries are dropped with the
217
+ session-scoped ledger.
218
+
219
+ Boundary continuation:
220
+
221
+ - `pi.on("agent_before_settle", event)` — when `event.outcome ===
222
+ "completed"` and pending entries exist, build one
223
+ `custom_message` entry, drain those task ids, and return
224
+ `{ entries: [entry], continue: true }`.
225
+ - Aborted/errored runs return no continuation. In real pi an aborted run
226
+ generally never reaches the boundary; this guard is defense-in-depth and
227
+ the idle path is the actual catch-all.
228
+ - The pre-entry `event.context` is not authoritative, so the handler always
229
+ offers the continuation for a completed run with pending entries. pi
230
+ builds that snapshot from the entries that existed before the handler
231
+ ran, so it is non-continuable at a completed boundary; pi then commits
232
+ the returned drafts and decides. A committed `custom_message` projects
233
+ through `convertToLlm` as a user-role message, so the run continues. If
234
+ pi still declines, the entry is already committed (rendered, not lost).
235
+ See #16.
236
+ - pi may discard a boundary result it considers invalid (the runner's
237
+ `valid: false` window). Our entry is a well-formed
238
+ `CustomMessageEntryDraft`, so this is a rare residual: entries are
239
+ drained when handed to pi and are not re-notified if pi rejects the
240
+ result. This is documented, not retried.
241
+ - Loop safety: only the pending → drained transition produces a
242
+ continuation; a second boundary with no pending entries returns
243
+ `undefined`.
244
+
245
+ ### 5. Clearing
246
+
247
+ - **Watch action** (`src/extension/shepherd.ts`, `watch` case):
248
+ `unseenCompletionLedger.clear(registration.taskIds)` after
249
+ `taskWatcherService.watch(...)` returns. This is the authoritative
250
+ retrieval clear. It must not rely on the watcher notifier: for an
251
+ already-settled task `watchTasks` delivers inline inside
252
+ `TaskWatcherService.watch` *before* `watcherId` is assigned, so the
253
+ queued delivery is dropped (`lifecycle.ts` `queue()` early-returns on an
254
+ empty watcher id) and the notifier never sees it
255
+ (`test/verify-task-watchers.mjs` already asserts that).
256
+ - **Close action:** after a successful `runtime.close(id)`, call
257
+ `clearForAgent(handle.id)`; if it removed entries, the close tool result
258
+ reports the dropped task ids (the Shepherd can `shepherd_watch` them
259
+ before closing instead).
260
+ - `session_start` and `session_shutdown`: `clearAll()`.
261
+ - Pending entries are removed by retrieval, close, or session end. There is
262
+ no second chance after a notice: a noticed entry is gone from the ledger.
263
+
264
+ ### 6. Invariants
265
+
266
+ - Settlement is authoritative; the ledger and notice never change task
267
+ state and never invent a completion.
268
+ - The settlement observer cannot slow or break settlement.
269
+ - Watched deliveries are byte-for-byte unchanged (mid-turn `steer`).
270
+ - No `continue: true` after an aborted or errored run.
271
+ - Notify-once per entry: no duplicate notices, no continuation loops.
272
+ - No tool-schema, prompt, settings, broker, or fieldnote changes.
273
+ - `registerShepherdTools` behavior is unchanged; all existing suites pass
274
+ untouched.
275
+ - The ledger does not record while no parent pi session is active; session
276
+ teardown clears it.
277
+
278
+ ## Compatibility
279
+
280
+ - Existing `verify-*.mjs` suites pass untouched.
281
+ - Herdr-only installs keep working with no new dependencies and no
282
+ settings.
283
+ - The observer hook is additive; `settleTask` behavior without a subscriber
284
+ is identical.