@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,141 @@
1
+ # Spec — hc background poll
2
+
3
+ ## Status
4
+
5
+ Proposed. No behavior change yet. Direct continuation of 010: the settle
6
+ path is converged, but nothing *triggers* it promptly on hc. Spec-only:
7
+ no `src` changes in this spec; implementation follows one worker per
8
+ phase (see `plan.md`).
9
+
10
+ ## Background: the gap
11
+
12
+ 010 proved the ledger/observer/notice contract on both backends, and
13
+ Phase 3 made the deadline timer drain-first. The remaining hole is what
14
+ *pumps* the drain on hc:
15
+
16
+ - Herdr: `startParentBrokerMonitor()` (`src/runtimes/herdr/lifecycle.ts`
17
+ ~line 84) runs `processParentBrokerMessages()` every 250 ms, unref'd,
18
+ from broker creation until shutdown. Tool calls never need to drain;
19
+ completions settle within ~250 ms of arrival, watchers fire, the
20
+ unseen bridge notices.
21
+ - hc: `drainBrokerInbox()` (`src/runtimes/hc/runtime.ts`) runs only
22
+ inside `message`, the `watch` blocking loop, and the delegate
23
+ deadline timer. The extension's `watch` action uses the non-blocking
24
+ `hcTaskWatcherService.watch` (no drain) and `status` uses
25
+ `describeHcStatusView` (no drain).
26
+
27
+ Live evidence (010 smoke-1): `task_done` + `reply` sat in
28
+ `parent/inbox` ~10 minutes across several `status`/`watch` calls; only
29
+ the deadline timer's drain settled them (`completed`, done beat
30
+ timeout — the Phase 3 guarantee working as a backstop). With the
31
+ default 60-minute delegate timeout, an idle hc parent could wait an
32
+ hour for a completion it already holds.
33
+
34
+ A second, smaller defect rides along: `applyMessageEnvelope` resolves
35
+ its own broker with a bare `ensureBroker()` (no session id), which —
36
+ when that helper runs outside a session-keyed drain — mints a
37
+ fallback-keyed junk broker (`hc-parent-<gen>`), replaces the module
38
+ broker, orphans the session mailbox for later drains, and addresses
39
+ reply relays to a store the child never polls (010 journal: junk dirs
40
+ `AyfED1`, `84O93R`). Any background poller must never do this: it must
41
+ drain through the session-keyed broker only.
42
+
43
+ ## Contract
44
+
45
+ ### 1. Background drain while work is open
46
+
47
+ The hc runtime runs one background poll while delegated work may still
48
+ settle:
49
+
50
+ - Interval 250 ms, matching Herdr. Single timer per process, idempotent
51
+ start, `unref`'d so it never keeps the host alive.
52
+ - Started on the first `delegate` (first open task — before that no
53
+ completion can arrive); stopped when zero unsettled tasks remain.
54
+ A later `delegate` restarts it. Stopped on module shutdown alongside
55
+ the existing `shutdownHcStaleWaitMonitor` /
56
+ `shutdownHcTaskWatchers` seams.
57
+ - Each tick calls exactly the existing `drainBrokerInbox()` (which
58
+ already ends with `settleDueReplyTimeouts()`). Synchronous poll;
59
+ a tick never overlaps the previous one in a way tool-call drains
60
+ don't already handle (all drains are idempotent; settlement is
61
+ first-wins per 010 §3).
62
+ - No session-identity drift, ever: the tick drains through the same
63
+ session-keyed broker the tool calls use. It must not call bare
64
+ `ensureBroker()` (see §3).
65
+
66
+ ### 2. Observable behavior
67
+
68
+ - `delegate` with no `watch` and no `message` settles within ~1 s of
69
+ child `shepherd_done` while the poller runs (bounded by the 250 ms
70
+ tick, not by the delegate deadline).
71
+ - `watch` registration and `status` drain first, then report: an
72
+ already-settled task returns `completed` synchronously instead of
73
+ `pending`. Return shapes are unchanged, only the staleness is gone.
74
+ (Decision: drain-first AND the background poll. Drain-first covers
75
+ active parents at read time; the poll covers idle parents that make
76
+ no calls at all — without it an idle Shepherd would still wait for
77
+ the delegate deadline, up to the 60-minute default, before anything
78
+ settles and the unseen notice fires. Herdr has both; parity needs
79
+ both.)
80
+ - The unseen-notice contract (007/010) is unchanged; notices now fire
81
+ promptly instead of at the deadline. No new entry kinds, no new
82
+ timing guarantees beyond "tick-bounded".
83
+ - No new broker dirs, no new diagnostics, no retained timers after
84
+ quiescence/shutdown. The process exits exactly as before with no
85
+ open work.
86
+
87
+ ### 3. Bare-`ensureBroker` hardening
88
+
89
+ `applyMessageEnvelope` already takes the drain's `active` broker (010
90
+ follow-up fix). The same rule becomes an invariant: **no settle-path
91
+ code may resolve a broker without the caller's session id.** The
92
+ background tick uses the session-keyed broker; if no session broker
93
+ can be resolved (no session context — e.g., after shutdown), the tick
94
+ skips instead of minting a fallback store.
95
+
96
+ Deliberate asymmetry (review resolution): `registerHcPollSession`
97
+ resolves through `ownerSessionKey` and never skips — the tick must poll
98
+ the same store the tool drains use (explicit id, env session, or the
99
+ process fallback). `drainHcInboxForSession` skips on blank ids instead:
100
+ a read path must never create state. Consequence: env-session runtimes
101
+ get background drains with no matching drain-first reads (the
102
+ registered key still matches the tool-call store, so settlement is
103
+ correct; only the read-side freshness guarantee rests on the tick
104
+ alone). Rejected-completion diagnostics are written beside the drain's
105
+ own `active` broker, never the module-cached one.
106
+
107
+ ### 4. Verification: deterministic, no live spawn
108
+
109
+ - Unit-tick seam: the poller exposes start/stop plus a synchronous
110
+ single-tick entry (same precedent as 010 Phase 0 exporting the
111
+ observer call for testability), so suites drive it without
112
+ wall-clock waits and without live terminals.
113
+ - New suite file (e.g., `test/verify-hc-poll.mjs`), wired into
114
+ `package.json` scripts + the `test` chain: tick with queued
115
+ `task_done` settles it; tick with empty inbox is a no-op; timer
116
+ starts on delegate and stops at quiescence; no fallback broker is
117
+ ever minted by the tick; `unref` is set so the timer can't hold the
118
+ process open.
119
+ - Live smoke (throwaway, both runtimes for contrast): delegate with no
120
+ watch and no message; Herdr settles in ~250 ms as today, hc now too
121
+ (previously hc waited for a message or the deadline).
122
+
123
+ ## Non-goals
124
+
125
+ - Changing `watch` (still non-blocking registration), `status` (still a
126
+ view), watcher batching, legacy prompt paths, or notice semantics.
127
+ - Persisting timers/ledgers across sessions; new settings (the 250 ms
128
+ interval is fixed, mirroring Herdr — not configurable).
129
+ - Touching the Herdr poller, the broker transport, envelopes, or
130
+ fieldnotes.
131
+ - Retrying failed drains, backoff, jitter, or adaptive intervals.
132
+
133
+ ## Invariants (007/010 carried forward)
134
+
135
+ - Settlement is authoritative; the tick never settles directly and
136
+ never invents a completion.
137
+ - First-wins ordering unchanged (010 §3); `cancelled` still excluded;
138
+ `delegate-submission-failure` still excluded.
139
+ - Watched deliveries byte-for-byte unchanged; no new wake kinds.
140
+ - No tool-schema, prompt, settings, broker, or fieldnote changes.
141
+ - Existing suites pass untouched.
@@ -0,0 +1,83 @@
1
+ # Tasks — 011 hc background poll
2
+
3
+ Work in order. One worker per phase — phases run strictly sequential (the
4
+ timer touches the drain/settle seam 010 just stabilized). A task is done
5
+ only when its implementation + verification are complete. This spec is
6
+ `011-hc-background-poll` (spec.md contract, plan.md design). Continues
7
+ 010, converges hc onto the Herdr promptness contract.
8
+
9
+ **This task is spec-only: no `src` changes.** The checkboxes below bind
10
+ the later implementation.
11
+
12
+ ## Overnight run + testing (no reload)
13
+
14
+ - The main Pi session cannot reload extensions, so never rely on in-place
15
+ reload for live verification (same rule as 009/010).
16
+ - For live tests needing new code: `hc run --bg` a fresh herdr-core agent
17
+ (full `pi` path), then have that child call `shepherd_*`
18
+ (`spawn`/`delegate`/`watch`/`done`) to spawn agents — a fresh Pi session
19
+ with updated code.
20
+ - Keep `npm test` green in the current session for unit checks; use the
21
+ fresh `hc` child only for live spawn/delegate/watch proof.
22
+
23
+ ## Phase 0 — poller wiring + drain-first watch/status
24
+
25
+ - [x] **0.1 Background poller in the hc runtime**
26
+ - In `src/runtimes/hc/runtime.ts`: module timer (250 ms fixed,
27
+ `unref`'d, idempotent start), started on first `delegate`, stopped
28
+ when zero unsettled tasks remain, restarted by the next `delegate`,
29
+ stopped on module shutdown alongside `shutdownHcTaskWatchers` /
30
+ `shutdownHcStaleWaitMonitor`.
31
+ - Each tick calls exactly the existing `drainBrokerInbox()`; no new
32
+ settle logic, no reordering, no invented completions.
33
+ - Session-keyed broker only: the tick never calls bare
34
+ `ensureBroker()`; audit every settle-path call site so each passes
35
+ a session id (grep must show no bare settle-path calls left).
36
+ - Export start/stop + a synchronous tick entry for tests (name TBD;
37
+ precedent: 010 Phase 0 exporting the observer call).
38
+
39
+ - [x] **0.2 Drain-first hc watch registration + status view**
40
+ - `shepherd_watch` (hc path): drain first via the session-keyed
41
+ `drainBrokerInbox`, then the existing non-blocking
42
+ `hcTaskWatcherService.watch`. Already-settled tasks report
43
+ `completed` synchronously; return shapes unchanged.
44
+ - `describeHcStatusView`: drain first for the same reason (stale
45
+ `running` for settled tasks goes away).
46
+ - The background poll stays required: it covers idle parents that
47
+ make no calls (drain-first alone would still leave them
48
+ deadline-bound).
49
+
50
+ - [x] **0.3 Verify Phase 0**
51
+ - `npm test` green; no existing suite modified.
52
+ - No fallback broker is minted by any settle-path call (source audit
53
+ + unit probe); timer is `unref`'d; start is idempotent; stop fires
54
+ at quiescence.
55
+
56
+ ## Phase 1 — verification, docs, landing
57
+
58
+ - [x] **1.1 Deterministic suite** (`test/verify-hc-poll.mjs`, wired into
59
+ `package.json` scripts + the `test` chain)
60
+ - Tick with a queued `task_done` settles it through the 010 observer
61
+ path (single winner, transcript readable); tick with an empty inbox
62
+ is a no-op; tick with no session context skips without minting a
63
+ store.
64
+ - Timer starts on `delegate`, stops at zero unsettled tasks,
65
+ restarts on the next `delegate`; `unref` set (cannot hold the
66
+ process open).
67
+ - Deterministic: exported tick seam, isolated ledger/registry, fake
68
+ pi surface where needed, no live spawn, no wall-clock waits.
69
+
70
+ - [x] **1.2 Docs + live proof**
71
+ - One-row note where 007/010 documented the notice (README `###
72
+ Delegate, then watch` paragraph + `docs/guides/tool-reference.md`
73
+ `shepherd_watch` entry): hc completions now settle tick-promptly
74
+ even with no `watch` and no `message`.
75
+ - Live smoke (throwaway script, both backends): delegate with no
76
+ watch and no message; Herdr settles in ~250 ms as today, hc now in
77
+ ~1 s (previously waited for a message or the deadline); no junk
78
+ broker dirs; close drops + reports as before.
79
+
80
+ - [x] **1.3 Full suite + landing**
81
+ - `npm test` green with all existing suites untouched.
82
+ - Record scope, evidence, and the landing note in a `journal.md`
83
+ before merging (follow the 007/010 journal precedent).
@@ -0,0 +1,12 @@
1
+ # Intent — 012 steer default
2
+
3
+ Parent→child and peer messages that omit `delivery` currently arrive
4
+ as `followUp` (queue passively). Observed live (011 Track C): a
5
+ followUp request to an idle hc child sat queued for minutes; the
6
+ steer retry completed promptly. Sheep are task-driven — a message to
7
+ one is almost always actionable — so the passive default is
8
+ backwards. Child→parent already upgrades wake-deserving messages to
9
+ steer (`parentMessageDeliveryOptions`); this aligns the other
10
+ direction. Every intentionally-passive internal sender (nudges,
11
+ stale bridges, herdr task publish) already passes explicit
12
+ `followUp`, so only agent-authored messages change behavior.
@@ -0,0 +1,40 @@
1
+ # Journal — 012 steer default
2
+
3
+ ## Scope
4
+
5
+ One user sentence ("default should be steer") → compact spec, six
6
+ ternary flips, one suite pin, live proof, land.
7
+
8
+ ## What changed
9
+
10
+ - `deliveryMode()` inverted (child-side choke point).
11
+ - hc: three envelope stamps + the direct-terminal send (now
12
+ `--force` by default) inverted. The forcesend matches what the
13
+ explicit-steer C1b run already proved prompt.
14
+ - herdr: both `sendParentMessage` stamps inverted.
15
+ - Parent schema description + hc-path `returnValue` fallback report
16
+ the effective default.
17
+ - `test/verify-message-routing.mjs`: the plain-message default pin
18
+ `followUp` → `steer` (the one pin that contradicted the spec).
19
+
20
+ ## Design notes
21
+
22
+ - The wake (`triggerTurn`) stays kind-driven and untouched; only
23
+ interruption urgency changed. Child→parent already steered
24
+ wake-deserving messages — this aligns the other direction.
25
+ - Choke-point correction: the first cut assumed `deliveryMode` was
26
+ the single default site; the runtimes stamp their own. All six
27
+ found by grep, all flipped.
28
+ - Deliberate trade recorded in spec §1: flagless FYI now interrupts.
29
+ Say `followUp` for passivity.
30
+ - Live proof limits: the C2-omitted run proves the child-side
31
+ default (fresh child processes build their own envelopes).
32
+ Post-reload C1-omitted (C4, `mango-69416`): the parent request
33
+ with no flag carried `steer` forensically and completed intact —
34
+ parent-side stamp proven too. All six sites now proven live.
35
+
36
+ ## Verification
37
+
38
+ - `npm test` exit 0.
39
+ - Live C2-omitted: crossed `ping-69415`/`pong-69415`, envelopes
40
+ forensically `steer`, zero junk dirs, both sheep closed.
@@ -0,0 +1,7 @@
1
+ # Plan — 012 steer default
2
+
3
+ 1. Invert `deliveryMode()` + parent schema description.
4
+ 2. `npm test` full; fix only pins that contradict the spec.
5
+ 3. Live Track C1 with omitted `delivery` (fresh sheep, new nonce).
6
+ 4. Skill one-liner (steer now default, may omit flag) + journal.
7
+ 5. Land: branch → merge → push.
@@ -0,0 +1,42 @@
1
+ # Spec — 012 steer default
2
+
3
+ ## 1. Behavior
4
+
5
+ - The default `delivery` for `shepherd_message` (parent and child
6
+ surfaces, both runtimes) becomes `steer`. Explicit `followUp` still
7
+ queues passively; explicit `steer` is unchanged.
8
+ - Wake semantics are untouched: `triggerTurn` stays kind-driven
9
+ (`expectsReply` / `replyTo` / task delegation wake; plain chatter
10
+ does not). The change is interruption urgency for busy recipients
11
+ and prompt turn-start for idle ones, not who wakes.
12
+ - Deliberate trade: a plain FYI with no flag now interrupts a busy
13
+ recipient instead of queueing. Senders who want passivity say
14
+ `followUp` explicitly. Rationale: FYI-to-a-sheep is rare; actionable
15
+ traffic is the norm.
16
+
17
+ ## 2. Implementation
18
+
19
+ - `deliveryMode()` (`src/extension/shepherd-done.ts`): invert —
20
+ `'followUp'` only when explicitly passed, else `'steer'`. Covers
21
+ child-side ingestion and child-built envelopes on both runtimes.
22
+ - hc stamps (`src/runtimes/hc/runtime.ts`, three envelope sites +
23
+ the direct-terminal `--force` send): invert each ternary. The
24
+ `--force` send now fires by default, matching the prompt-delivery
25
+ intent (proven live in Track C1b).
26
+ - herdr stamps (`src/runtimes/herdr/lifecycle.ts`, expectsReply +
27
+ plain branches): invert both.
28
+ - Parent `shepherd_message` schema description + the hc-path
29
+ `returnValue` fallback (`?? 'steer'`): report the effective default.
30
+ - No changes to explicit `delivery: 'followUp'` senders (nudges,
31
+ stale/task bridges, task-delegation envelopes — delegation wakes
32
+ by kind). No changes to `triggerTurn` logic anywhere.
33
+
34
+ ## 3. Verification
35
+
36
+ - Full `npm test` green (no suite pins the default; any that does
37
+ gets updated only if the pin contradicts this spec).
38
+ - Live: skill Track C2 rerun with the `delivery` flag omitted on
39
+ both legs — crossed summaries exact (`ping-69415` / `pong-69415`),
40
+ and broker forensics show both envelopes carried `steer`. (C1 with
41
+ an omitted flag needs a reloaded parent, since the stale session
42
+ stamps the old default; deferred to the next reload.)
@@ -0,0 +1,6 @@
1
+ # Tasks — 012 steer default
2
+
3
+ - [x] **0.1** Invert `deliveryMode()`, update parent schema description.
4
+ - [x] **0.2** Full `npm test` green.
5
+ - [x] **0.3** Live C1 with omitted `delivery` completes promptly, code word intact.
6
+ - [x] **0.4** Skill one-liner + journal, land (branch → merge → push).
@@ -0,0 +1,94 @@
1
+ # Handoff: T011 live acceptance in OpenCode (human-driven)
2
+
3
+ **Spec:** `specs/013-opencode-shepherd` · **Task:** T011 remainder
4
+ **Date:** 2026-11-17 · **Status:** READY (verified 2026-11-18 morning: loader
5
+ present, fresh server, `shepherd agents` works, registries empty, quota back)
6
+
7
+ ## Why human-driven
8
+
9
+ Pi-driven bench sessions (`hc send` into TUIs) proved unreliable for
10
+ acceptance: stale tool catalogs across restarts, 100K+ tokens of confused
11
+ context, and at least one session that faked tool results by re-running
12
+ adapter code via shell. A fresh human-opened session avoids all three and
13
+ matches real usage. The engine code is committed (`820f5da`) and the pi
14
+ suite is green (631 pass); only live OpenCode acceptance remains.
15
+
16
+ ## Preconditions (assistant verifies before you start)
17
+
18
+ - [ ] `~/.config/opencode/plugins/shepherd-dev.ts` exists (the dev loader)
19
+ - [ ] Server log shows `loading plugin ... shepherd-dev.ts` with NO
20
+ `failed to load plugin ... shepherd` lines after it
21
+ - [ ] Registries empty: `~/.config/opencode/pi-shepherd/created-terminals.json`
22
+ and `created-panes.json` contain `[]`
23
+ - [ ] Assistant will NOT touch plugin/repo files, restart the server, or
24
+ send anything into your session while you test (coordinate first)
25
+
26
+ ## Setup (you)
27
+
28
+ 1. Open a **new** terminal, `cd` to the repo
29
+ (`/home/mikkelkp/.pi/agent/extensions/pi-shepherd`), run `opencode`.
30
+ 2. Fresh session (new TUI = new session). Do not reuse an old session —
31
+ TUIs hold stale tool catalogs across server restarts.
32
+ 3. Sanity check first — paste: `Call the shepherd tool with action agents.
33
+ Report the agent names.`
34
+ Expect 4 agents (reviewer, worker, planner, scout). If the model says
35
+ the tool is unavailable, STOP and tell the assistant (do not let it
36
+ improvise via shell — that invalidates the test).
37
+
38
+ ## Test A — basic loop (must pass before B)
39
+
40
+ Paste, one step at a time, waiting for each result:
41
+
42
+ 1. `Spawn scout label handA. Report the agent id, stop.`
43
+ 2. `Delegate to <agent-id> with task: Reply with the word HAND then call
44
+ shepherd_done with completed. Then watch the task id and report, stop.`
45
+
46
+ **Pass criteria:** watcher completion arrives with status completed and the
47
+ summary mentions HAND. Report back: agent id, task id, watcher text.
48
+
49
+ ## Test B — peer question loop (the actual T011 goal)
50
+
51
+ 1. `Spawn scout label handB. Report the agent id, stop.`
52
+ 2. `Delegate to <handA-id> with task: Ask <handB-id> (label handB) the
53
+ question "What is your label" using shepherd_message. When it replies,
54
+ call shepherd_done with completed and the answer. Then watch, stop.`
55
+
56
+ **Pass criteria:** handA's question reaches handB; handB replies via
57
+ shepherd_message (with replyTo set); handA calls shepherd_done; the watcher
58
+ fires completed with the answer ("handB" — note: the sheep may answer
59
+ "scout", its agent type; either is fine as long as the loop completes).
60
+ Report back: both agent ids, task id, and the full watcher completion text.
61
+ If handB instead claims the tool is missing or improvises via shell, STOP —
62
+ paste its exact words back (that is itself a finding).
63
+
64
+ ## Test C — error paths (cheap, do if quota allows)
65
+
66
+ 1. `Call shepherd_done with taskId shepherd-task-0000-0000 and status
67
+ completed. Report the exact error text, stop.`
68
+ 2. `Call shepherd_message to shepherd-agent-0000-0000 with message hi.
69
+ Report the exact error text, stop.`
70
+
71
+ **Pass criteria:** both fail with "unknown" errors naming the bad id (not
72
+ a crash, not a hang). Report the exact error strings.
73
+
74
+ ## Test D — done-nudge (optional, slow)
75
+
76
+ Only if quota is comfortable: delegate a trivial task to handA, then ask
77
+ handA nothing further and wait ~3 minutes without prompting it. The parent
78
+ should receive a nudge reminder about the open task. Report whether any
79
+ nudge arrived (check the session — it appears as a shepherd notice).
80
+
81
+ ## Rules while testing
82
+
83
+ - Do NOT edit repo files, restart the server, or touch
84
+ `~/.config/opencode/plugins/` mid-test. If something looks broken,
85
+ report it instead of fixing it.
86
+ - Keep pastes sequential: one tool-using instruction per message, wait
87
+ for the result before the next.
88
+ - Report VERBATIM outputs (agent ids, task ids, watcher text, errors).
89
+ Do not summarize — the ids are needed for log forensics.
90
+
91
+ ## Report back
92
+
93
+ Paste into chat: for each test, PASS/FAIL/STOP + the verbatim artifacts.
94
+ The assistant correlates with server logs, ticks T011, and moves to Phase 4.
@@ -0,0 +1,59 @@
1
+ # Intent — Shepherd for OpenCode
2
+
3
+ `specs/013-opencode-shepherd` · Author: Mikkel (product owner) · 2026-11-17 · approved
4
+
5
+ ## Problem
6
+
7
+ Shepherd (herding subagents in visible Herdr panes, with tracked tasks and
8
+ shared fieldnotes) only exists for Pi. I also work in OpenCode, and there I
9
+ have no equivalent: no persistent visible sheep, no delegate/watch flow, no
10
+ shared session notes across agents. Every OpenCode session starts from zero.
11
+
12
+ ## Proposed outcome
13
+
14
+ Shepherd becomes available inside OpenCode too, working the same way it does
15
+ in Pi: I can ask for a planner/scout/worker, it spawns in a visible Herdr
16
+ pane, I can delegate tracked work to it, message it, watch for completion,
17
+ and the agents share fieldnotes. Herdr stays the execution substrate — how
18
+ sheep run today does not change. The same repo hosts both, and each host
19
+ (Pi, OpenCode) stays flexible and independent: using one must never require
20
+ or break the other.
21
+
22
+ ## Affected users and systems
23
+
24
+ - Me and any other Shepherd users who work in both Pi and OpenCode.
25
+ - `pi-shepherd` extension as it exists today (must keep working untouched).
26
+ - Herdr / `hc` runtimes (reused, not replaced).
27
+ - The repo layout and npm packaging (must accommodate a second host).
28
+
29
+ ## Constraints
30
+
31
+ - Herdr remains the main course: sheep still run in Herdr panes/terminals.
32
+ Path A only — no native OpenCode session runtime in this effort.
33
+ - Pi behavior must not regress; Pi users who never touch OpenCode should
34
+ notice nothing (apart from repo reorganization).
35
+ - One repo, one package — but host independence must hold in code layout:
36
+ the Pi and OpenCode adapters stay separate with no cross-imports, so a
37
+ change on one side never requires a change on the other. Both hosts'
38
+ verification suites run on every change, and releases call out per-host
39
+ impact.
40
+ - Agent definitions (Markdown) and project config (`.shepherd/config.json`)
41
+ should be shared, not forked per host.
42
+
43
+ ## Decisions
44
+
45
+ - **Package name: `@luminascale/shepherd` (decided 2026-11-17).** Bare
46
+ `shepherd` is taken on npm; the scoped name is free. Only the package
47
+ name changes — tool names, env vars, and config/registry paths stay
48
+ frozen so existing users keep their settings and herd. A final
49
+ `@luminascale/pi-shepherd` release carries a one-time migration notice
50
+ and ships *before* the rename.
51
+
52
+ ## Open questions
53
+
54
+ - Does the OpenCode side need its own settings surface from day one, or is
55
+ file-based config enough for the first slice?
56
+
57
+ ## Approval
58
+
59
+ - [x] Product owner reviewed and approved — Mikkel, 2026-11-17