@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,263 @@
1
+ # Tasks — Shepherd for OpenCode
2
+
3
+ `specs/013-opencode-shepherd` · draft · spec: `spec.md` · plan: `plan.md`
4
+
5
+ ## Phase 1 — Engine decoupling (US5)
6
+
7
+ **Goal**: shared engine imports nothing host-specific; Pi behaves exactly
8
+ as before.
9
+ **Checkpoint**: full existing `verify-*` suites green, zero Pi behavior change.
10
+
11
+ - [x] T001 [US5] Inject agent/config directories and frontmatter parsing into `src/core/discovery.ts` and `src/core/config.ts` (no `@earendil-works` imports left in shared engine).
12
+ - [x] T002 [US5] Parameterize the launch-file builder (`src/runtimes/herdr/herdr.ts`) by child binary, child entry, and env-capability prefix; Pi passes today's values.
13
+ - [x] T003 [US5] Run all `verify-*` suites plus manual Pi spawn → delegate → watch → close; confirm green and unchanged.
14
+
15
+ ## Phase 2 — OpenCode spawn and inspect (US1)
16
+
17
+ **Goal**: an OpenCode user can herd visible sheep.
18
+ **Checkpoint**: spawn → status → read → close works from OpenCode; unknown names and unreachable Herdr fail cleanly.
19
+
20
+ - [x] T004 [US1] OpenCode server-plugin skeleton with tool surface for `spawn`, `herd`/`agents`, `status`, `read`, `close` routed through the shared runtime resolver.
21
+ - [x] T005 [US1] Child boot via interactive `opencode` in pane/terminal using the parameterized builder (T002); readiness/tail reuse as-is.
22
+ - [x] T006 [P] [US1] Human command surface mirroring Pi's (`agents`, `herd`, `spawn`, `status`, `read`).
23
+ - [x] T007 [US1] Acceptance: unknown agent name, unreachable Herdr, and duplicate-label spawn all produce their specified errors.
24
+
25
+ ## Phase 3 — Tracked work and messaging (US2, US3)
26
+
27
+ **Goal**: the full delegate → watch → done loop plus mid-task questions work from OpenCode.
28
+ **Checkpoint**: delegate while doing other work, receive completion; question → reply → resume completes.
29
+
30
+ - [x] T008 [US2] `delegate` + `watch` tools with watcher/notifier bridges and exactly-once delivery (settled results retrievable, late watchers served synchronously).
31
+ - [x] T009 [US2] OpenCode child `shepherd_done` tool publishing the shared `task_done` envelope (task inference, mismatch rejection, broker-unavailable error).
32
+ - [x] T010 [US3] Parent/peer `shepherd_message` on both sides with `expectsReply` waiting semantics, reply correlation, and the bounded done-nudge + stall escalation.
33
+ - [x] T011 [US2] Acceptance remainder: peer reply → resume → done end-to-end without reloads; done-nudge fires for a forgetful sheep; unknown-task done/message errors; missed deadline settles with explanation.
34
+ - Live 2026-11-18: A and B PASS (B after the sheep/parent-classification fix), C PASS for `shepherd_message` (the sheep-only `shepherd_done` gate is a correct refusal, not the bad-id error — see journal).
35
+ - Coverage check: missed deadline is engine-level shared with OpenCode (`verify-unseen-completions.mjs`); done-nudge and sheep-context unknown-task had no OpenCode coverage, so `test/verify-opencode-nudge.mjs` was added (both PASS). Full suite: 645 PASS. The handoff is complete; see the T011 journal below.
36
+ - The "live re-verify pending" wording in the older bullets below is superseded by journal entries 10–13 — both fixes were live-confirmed. Those bullets are kept only as a chronological record.
37
+ - Mechanism proven pre-restart (rose→jack reply resolved the wait; done fired the watcher). Full peer-`expectsReply` re-run pending quota reset.
38
+ - Post-restart "successes" were INVALID: the bench deleted the dev loader during cache-busting, so later tool output was model improvisation (t28 re-ran adapter logic via shell). Verify tool presence + side-effect artifacts (terminals, broker dirs, registry), never prose alone. Requires: loader file present, fresh server, trivial tool call first, no touches mid-test, fresh TUI sessions (TUIs hold stale catalogs across restarts).
39
+ - **Live T011 run, 2026-11-18 (after display fix):** sanity `shepherd agents` via tool returned 4 agents; `/shepherd agents`/`spawn` command output renders in full with no turn. **Test A PASS** — handA (`shepherd-agent-e221ed63-0ca40db9-d4b5-474a-9b36-0eb1b658c0b6`) completed `shepherd-task-e221ed63-90ac8f1e-ea03-472d-964d-331c07aabbe7`; watcher text: "Replied HAND and marked the delegated task complete." **Test B core loop completed but with two findings:** handB (`shepherd-agent-e221ed63-dea0af1a-a7f8-4232-91a9-9eb37f37bb56`) answered "My label is handB"; handA forwarded it and called `shepherd_done` completed on `shepherd-task-e221ed63-11c1e389-af86-4b61-898e-8d4ddb0c435a`. (1) handB could NOT reply via the `shepherd_message` tool: verbatim — "I'll deliver the correlated reply directly through the broker files (the tool's parent-form path can't address a peer in another session)" and "The correlated parent-form call was rejected because the peer lives in a different broker session, so I delivered the reply through the shared broker (reply envelope + parent replyReceived mirror) and relayed the answer text to handA's terminal." This is the known multi-parent broker multiplexing limit (Later), now blocking the documented peer path. (2) The watcher completion for task `11c1e389` did NOT arrive in the parent session; it appeared in **handB's** pane, while the parent received only handA's forwarded `shepherd_message` (`shepherd-message-e029df62-9911-491f-9d3a-c669d5f62044`, replyTo `shepherd-message-c607d4bd-85b7-4b6f-a6cc-1717ab660001`). **Fixed (code complete, live re-verify pending):** `src/opencode/bridge.ts` now refuses to register a sheep session as a task parent in `noteTaskParent`, refuses to notify sheep sessions in `promptParent`, and retries a transient `session.prompt` failure up to 3 times instead of silently dropping it. Regression: `test/verify-opencode-notice.mjs`. Also: the first handA id (`shepherd-agent-e221ed63-2ef15b1c-...`) was orphaned by the OpenCode server restart (in-memory registry reset; see Later reload-resilience item) — fresh spawn was required.
40
+ - **Finding (human T011 sanity, 2026-11-18) — FIXED, live re-verify pending:** the human `/shepherd` command listed the 4 agents correctly, but also started an assistant turn. Owner reported the invocation as `/shepherd agent`; the displayed header was `[shepherd agents]`. Root cause: `src/opencode/server.ts` command handler delivered every result via `ctx.session.prompt({ sessionID, text: ... })`; `session.prompt` posts a user message and wakes the model, so the command's own output re-entered the model and started a turn. Fix: command output now goes through `src/opencode/display.ts` → `ctx.session.prompt({ sessionID, text, resume: false })`. OpenCode's session layer skips `execution.wake()` when `resume: false`, so the result renders as a full normal message with no assistant turn. Rejected alternatives: `noReply` (v1 only — absent from the installed v2.3.0 prompt schema) and `session.synthetic` (the TUI renders synthetic messages as a single-line truncated notice using `description ?? text`, so a multi-line agent list collapsed to a bare `◈shepherd` label). Parent-session notices (`bridge.ts`) still use `session.prompt` without `resume: false` intentionally. Regression covered by `test/verify-opencode-display.mjs` (unit + source guard). Live confirmation is part of resuming the T011 handoff with a fresh server/TUI.
41
+
42
+ ## Phase 4 — Shared fieldnotes (US4)
43
+
44
+ **Goal**: notes flow across delegations and across hosts.
45
+ **Checkpoint**: Pi sheep reads OpenCode sheep's notes and vice versa.
46
+
47
+ - [x] T012 [US4] Parent artifact-session resolution in the OpenCode adapter onto the same shared layout Pi uses.
48
+ - Added `src/opencode/fieldnotes.ts`: resolves/creates the parent fieldnotes
49
+ session with the OpenCode session id as the opaque parent identity and the
50
+ session cwd as the project root, using the shared engine resolver — no
51
+ layout duplication and no Pi adapter import. The fieldnotes setting is
52
+ snapshotted per `(session id, cwd)` like Pi's session-scoped setting.
53
+ - `spawnSheep` resolves once and threads the session into both hc and Herdr
54
+ runtime contexts (so the agent record and later delegates reserve notes);
55
+ `delegateSheep` re-resolves so a task always reserves its note. Spawn
56
+ results now print `fieldnote: <relative path>` when enabled.
57
+ - Regression: `test/verify-opencode-fieldnotes.mjs` — layout creation/reuse,
58
+ identity+root separation, Pi↔OpenCode resolution of the same session and
59
+ shared notes, disabled/session-scoped gate, and spawn/delegate wiring.
60
+ Full suite: 650 PASS (exit 0).
61
+ - [x] T013 [US4] Acceptance: sequential delegations across hosts share notes; disabled-notes mode stays off everywhere.
62
+ - Filesystem acceptance via `test/verify-cross-host-notes.mjs`: one opaque
63
+ parent identity + one project root yields exactly one
64
+ `.shepherd/sessions/NNNN-*` directory across sequential Pi → OpenCode and
65
+ OpenCode → Pi delegations, with two/three distinct finalized notes, one
66
+ MOC linking them, metadata reload, and no global index (spec 003 non-goal).
67
+ Both per-session setting gates honor `fieldnotes: false` and stay off
68
+ across a mid-session config flip; new sessions observe the change.
69
+ Full suite: 653 PASS (exit 0).
70
+ - Scope: the handoff is verified at the resolver/gate + artifact layer, not
71
+ with two live host TUIs; cross-host sharing requires both hosts to present
72
+ the same opaque parent identity for a project. A live two-host walkthrough
73
+ remains optional (see "Later").
74
+
75
+ ## Phase 5 — One package, verified twice (US5, US6)
76
+
77
+ **Goal**: single installable package, per-host docs, both suites gating every change.
78
+ **Checkpoint**: fresh installs in each host (following only that host's docs) both herd working sheep; both suites green.
79
+
80
+ - [x] T014 [P] [US6] Manifest carries both entries (Pi extension + OpenCode plugin); install verified fresh in each host with no steps from the other host.
81
+ - `package.json` now declares `pi.extensions: ["./index.ts"]` and an
82
+ `exports` map whose root resolves to `./src/opencode/server.ts` (the
83
+ `Plugin.define` default export OpenCode loads via `plugins` in
84
+ `opencode.json`).
85
+ - `test/verify-packaging.mjs` packs the tarball, asserts both entry files
86
+ and the shared engine are shipped, installs it into an isolated consumer,
87
+ and checks bare `@luminascale/pi-shepherd` resolves to the OpenCode plugin
88
+ while the installed manifest still declares the Pi entry. Full suite:
89
+ 657 PASS (exit 0).
90
+ - [x] T015 [P] [US6] README splits into per-host tracks on the first screen.
91
+ - New title/host-neutral intro, a "Choose your host" picker linking to
92
+ "Pi track" and "OpenCode track" before shared content. Each track has its
93
+ own install/verify steps and host-specific behavior (Pi settings menu vs
94
+ OpenCode file-based config and display-only command output).
95
+ - `test/verify-host-docs.mjs` guards the first-screen split and the OpenCode
96
+ `plugins` config snippet. Full suite: 657 PASS (exit 0).
97
+ - Follow-up: the detailed per-host steps moved to
98
+ `docs/guides/installation.md`; the README keeps a compact host-neutral
99
+ install picker linking to it, and `verify-host-docs.mjs` now checks both
100
+ the picker and the guide.
101
+ - [x] T016 [US5] Mirrored OpenCode verification harness covering FR-001–FR-004; both harnesses run on every change.
102
+ - `scripts/verify-suites.mjs` derives the Pi (36 scripts) and OpenCode
103
+ (11 scripts) suites from `package.json`; `npm test` chains both, and a new
104
+ `*:test` script cannot silently escape them.
105
+ - `test/verify-opencode-surface.mjs` loads the real plugin module (module-load
106
+ smoke test) and drives `setup` with a fake host, asserting the full tool
107
+ family, visible-pane launch overrides, child-only completion, and
108
+ watcher/notice isolation (FR-001–FR-004). This absorbs the harness-hardening
109
+ "Later" item. Full suite: 661 PASS (exit 0).
110
+ - [x] T017 [US5] Release checklist: per-host impact notes; Pi-only change ships with zero OpenCode-side edits (and vice versa).
111
+ - `docs/releasing.md` requires both suites green, explicit per-host impact
112
+ lines, and the T018-before-T019 release order including the `npm deprecate`
113
+ pointer.
114
+ - `scripts/host-impact.mjs` classifies a git range (or `--files`) into
115
+ Pi-only / OpenCode-only / shared / docs and prints the verdict;
116
+ `test/verify-host-impact.mjs` covers every verdict plus the checklist.
117
+ - [x] T018 [US5] Farewell release on the old name: one-time migration notice (marker file; human sessions only; never in child sheep panes), README banner, final old-name publish plus `npm deprecate` with pointer to the new name. The old name gets its final notice-bearing release (`0.5.2`); the new package (`0.6.0`) is published first so the pointer is never a 404. See the revised ordering in `plan.md` and `docs/releasing.md`.
118
+ - `src/core/migration.ts` emits a one-time, display-only notice gated by a
119
+ per-host marker (`<agentDir>/pi-shepherd/migration-notice.json`). Child
120
+ processes (`PI_SHEPHERD_SESSION` / `SHEPHERD_TASK_ID`) never see or consume
121
+ it. Wired into Pi `session_start` and the OpenCode command output path;
122
+ README banner and the deprecated-publish/deprecate ordering added.
123
+ - `test/verify-migration-notice.mjs` covers once-only, per-host markers,
124
+ child suppression, and both host entry points.
125
+ - Operator note: the actual last old-name publish + `npm deprecate` remain a
126
+ release action documented in `docs/releasing.md`; this commit carries the
127
+ code/docs that must ship in it.
128
+ - [x] T019 [US6] Rename package to `@luminascale/shepherd` (manifest + URLs; FR-013); verify old-install → remove → new-install keeps settings and herd (SC-005).
129
+ - Manifest name is now `@luminascale/shepherd`; README install commands and
130
+ packaging tests updated. Repository URLs stay on the `pi-shepherd` repo,
131
+ which is unchanged. All functional identifiers stay frozen: `shepherd_*`
132
+ tool names, `SHEPHERD_`/`PI_SHEPHERD_` env prefixes, `pi-shepherd` user data
133
+ dir, and `.shepherd/config.json`.
134
+ - `test/verify-rename-migration.mjs` simulates old-install → remove →
135
+ new-install with isolated HOME and asserts settings and the created-pane
136
+ registry are read intact from the frozen paths. Full suite: 670 PASS
137
+ (pi 36 + opencode 11 scripts).
138
+
139
+ ## Later
140
+
141
+ - [x] Watcher completion notices must reach only human parent sessions, never a sheep pane, and must survive a transient parent-busy failure (found in live T011, 2026-11-18). `src/opencode/bridge.ts`: `noteTaskParent` and `promptParent` both reject sheep sessions; `promptParent` retries up to 3 times with backoff and logs on exhaustion instead of silently dropping. Regression: `test/verify-opencode-notice.mjs`. **Live-verified 2026-11-18:** completion notice landed in the parent session.
142
+ - [x] Reload resilience — **implemented the "document orphan-reap" option** (2026-11-18). Full rehydration would require restoring opaque-id tokens, broker singletons, task deadlines, reply correlation, watcher queues, and HC generation ids across the shared engine; the supported one-parent-per-process boundary makes that a redesign. Instead, `src/opencode/orphans.ts` detects live owned panes/terminals that have no in-memory `SheepRecord` after a reload, prunes confirmed-gone entries, and emits one display-only notice per distinct orphan set (marker: `orphan-notices.json` in the host data dir; native ids never leak). The `shepherd` tool gained `action: "reap"`, which closes only transports still recorded in the ownership registries for the calling session, then clears their entries and launch dirs. Regression: `test/verify-opencode-orphans.mjs` (fake Herdr/hc, isolated HOME) covers detection, one-time notice, new-orphan notice, reap, launch-dir cleanup, and cross-session protection. **Scope:** tracked tasks/watchers do not survive a restart; orphans are reported and reaped, not reattached. README documents the behavior.
143
+ - [x] Multi-parent broker multiplexing — **re-evaluated 2026-11-18, closed as a
144
+ documented non-issue for supported flows.** The broker caches are
145
+ process-singletons keyed by the parent session id (Herdr
146
+ `ensureParentBroker`, hc `ensureBroker`), and a session switch creates a
147
+ new broker rootDir. Interleaving two parent sessions in one server
148
+ process can strand the other session's envelopes, but the whole engine
149
+ — not just the brokers — is one-parent-per-process: `beginSession`
150
+ clears watchers and retires opaque ids, the Herdr drain timer and hc
151
+ poller each track one key, and hc ids carry a process-wide
152
+ `generationId`. None of the micro-fixes work in isolation: removing the
153
+ cache would mint a fresh empty mailbox per call, keying by root path is
154
+ impossible before `createParentBroker` generates it, and a per-session
155
+ broker map alone would still lose watchers and one-sided drains. Sheep
156
+ of different parents cannot collide at the broker layer — unique
157
+ rootDirs, broker ids, and capability validation reject cross-parent
158
+ addressing. All supported flows (one parent, many sheep, peer replies,
159
+ done-nudge, watcher notices) are covered and live-verified. If
160
+ multi-parent concurrency becomes a requirement, it is a separate spec
161
+ covering broker maps, deterministic roots, session-keyed registries and
162
+ watchers, per-session timers, and capability survival — not a broker
163
+ patch.
164
+ - [x] Sheep sessions that call a parent-only tool before binding must not be permanently misclassified as parents (found in live T011 re-run, 2026-11-18: verbatim from handB — "this session was not bound as a delegated sheep session, so the tool fell back to the parent form and returned Unknown child target"). `src/opencode/bridge.ts`: `markParentSession` no-ops for known sheep, `isParentSession` returns false for known sheep, `bindChildSession` clears stale parent marks. Regression in `test/verify-opencode-notice.mjs`. **Live-verified 2026-11-18:** handB replied via `shepherd_message` (zero shell calls), handA called `shepherd_done` completed, watcher completion reached the parent.
165
+ - [ ] Optional live T013 walkthrough — **blocked on a product decision, not
166
+ on test infrastructure.** Cross-host sharing requires both hosts to
167
+ present the same opaque parent identity; Pi uses its session id and
168
+ OpenCode uses its session id, and neither public tool surface exposes an
169
+ identity override. `test/verify-cross-host-notes.mjs` proves the shared
170
+ layout works when the identity matches, but there is currently no
171
+ supported way to arrange that in two live host sessions. Enabling this
172
+ walkthrough needs a new, explicitly designed cross-host binding key
173
+ (on both adapters, without regressing Pi) — budget it as a separate
174
+ feature rather than forcing it into this handoff. Tracked as
175
+ [GH #19](https://github.com/MikkelKappelPersson/shepherd/issues/19).
176
+ - [x] Verification-harness hardening (folded into T016 + contributor notes): the OpenCode suite loads `src/opencode/server.ts` for real via `verify-opencode-surface.mjs` (a bad import can no longer sit unnoticed), and `npm test` gates both suites. The live-testing rules remain in force for human handoffs: after every adapter change reload, confirm NO "failed to load plugin" lines, run one trivial tool call, then test; never touch plugin files mid-test; never delete the dev loader without restoring it; distrust model self-reports of tool presence and assert on artifacts.
177
+ - [ ] Native OpenCode session runtime (no Herdr dependency) — separate effort; Path A deliberately first.
178
+ - [ ] OpenCode settings UI — only if the file-config default (plan Q2) proves insufficient.
179
+ - [x] `/shepherd` command output must not start an agent turn (found during T011 sanity, 2026-11-18). Fixed via `ctx.session.prompt({ ..., resume: false })` in `src/opencode/display.ts`; unit + source-guard regression in `test/verify-opencode-display.mjs`. **Live-verified 2026-11-18:** command output rendered in full with no assistant turn (T011 journal entry 10).
180
+
181
+ ## T011 live-attempt journal (2026-11-18)
182
+
183
+ Chronological record of what was tried and what happened, so a later reader
184
+ does not repeat a dead end.
185
+
186
+ 1. **Pi-driven bench sessions (before this day)** — `hc send` into TUIs.
187
+ Failed: stale tool catalogs across restarts, 100K+ token confused contexts,
188
+ one session faked tool results by re-running adapter code via shell.
189
+ Conclusion: human-driven fresh TUI only.
190
+ 2. **Human sanity `/shepherd agent`** — listed 4 agents but started an
191
+ assistant turn. Root cause: command output delivered via `session.prompt`.
192
+ 3. **Fix attempt A — `session.synthetic(..., resume: false)`** — no turn, but
193
+ the TUI rendered only a `◈shepherd` label (synthetic notices use
194
+ `description ?? text`, single-line, truncated). Abandoned.
195
+ 4. **Fix attempt B — `session.prompt(..., resume: false)`** — full multi-line
196
+ output renders, no turn. Rejected `noReply` (v1-only, absent from v2.3.0
197
+ prompt schema). Works. Side observation: "OpenCode thinks it's working"
198
+ likely the busy indicator from the assistant's own reply; no pending inbox
199
+ rows found. Left as-is.
200
+ 5. **Test A (after restart)** — first handA id was orphaned by the OpenCode
201
+ restart (in-memory registry reset). Fresh spawn, delegate, watch → PASS.
202
+ 6. **Test B first run** — core loop completed (handB answered "My label is
203
+ handB"; handA called `shepherd_done`) but handB could not use
204
+ `shepherd_message` for the peer reply and improvised via broker files;
205
+ the watcher completion appeared in handB's pane, not the parent. Initially
206
+ attributed to multi-parent broker multiplexing.
207
+ 7. **Fix — watcher-notice routing** — `noteTaskParent`/`promptParent` reject
208
+ sheep sessions; `promptParent` retries up to 3 times. Code + unit test
209
+ green, but not yet observable in a live run (see 9).
210
+ 8. **Test B re-run (fresh plugin + herdr)** — handB again failed to reply via
211
+ `shepherd_message`, this time with a precise error: "this session was not
212
+ bound as a delegated sheep session, so the tool fell back to the parent
213
+ form and returned Unknown child target." handA stayed `waiting`, so the
214
+ task never settled and the watcher-notice fix could not be exercised.
215
+ Root cause identified: a child that called a parent-only tool before its
216
+ lazy session binding was permanently marked as a parent by
217
+ `markParentSession`; `sheepMessage` then rejected it.
218
+ 9. **Fix — sheep/parent classification** — `markParentSession` no-ops for
219
+ known sheep, `isParentSession` excludes known sheep, `bindChildSession`
220
+ clears stale parent marks. Regression in `test/verify-opencode-notice.mjs`;
221
+ full suite green.
222
+ 10. **Test B re-run after reload (SUCCESS)** — handB replied via
223
+ `shepherd_message` only (session export shows zero shell calls), handA
224
+ called `shepherd_done` completed, and the `shepherd_watcher completion`
225
+ notice landed in the parent session with the answer. Both fixes verified
226
+ live. The answer was `opencode` (the child agent's display name), which
227
+ the handoff explicitly accepts.
228
+ 11. **Close-out + Test C** — both Test B sheep were closed via
229
+ `shepherd_close` and all Herdr sheep terminals confirmed gone; the stale
230
+ `created-terminals.json` bookkeeping was cleared to `[]`. Test C results:
231
+ - `shepherd_done({ taskId: "shepherd-task-0000-0000", status: "completed" })`
232
+ from the human parent returned verbatim:
233
+ `shepherd_done is a sheep-only tool: only the delegated sheep session may complete its task.`
234
+ Correct refusal, but NOT the handoff's expected "unknown" error naming
235
+ the bad id — that path is unreachable from a parent session, so the
236
+ unknown-task error needs a sheep-context call to be exercised. No crash
237
+ or hang.
238
+ - `shepherd_message({ target: "shepherd-agent-0000-0000", message: "hi" })`
239
+ returned verbatim: `Unknown agent id "shepherd-agent-0000-0000".
240
+ Lifecycle ids are scoped to this Shepherd; use the id from the latest
241
+ shepherd_spawn result, not an agent name, label, or pane id.` PASS.
242
+ 12. **Coverage check + close** — existing suites cover missed deadline at the
243
+ shared engine level (`verify-unseen-completions.mjs`), but nothing covered
244
+ the OpenCode done-nudge path (`src/opencode/bridge.ts` event handler) or
245
+ the OpenCode sheep-context `sheepDone()` unknown-task error. Added
246
+ `test/verify-opencode-nudge.mjs`: fake Herdr + queued
247
+ `session.execution.succeeded` events assert the nudge names the task, is
248
+ delivered once, then escalates to the parent; a direct `sheepDone` call
249
+ with `shepherd-task-0000-0000` asserts the unknown-task error names the
250
+ bad id. Both PASS; full suite 645 PASS (exit 0). T011 ticked.
251
+ 13. **Outcome** — all three code fixes (command display, notice routing,
252
+ sheep/parent classification) are live-verified; the handoff's Tests A/B/C
253
+ are complete. Outstanding non-blocking items remain in "Later": reload
254
+ resilience, multi-parent broker multiplexing (narrowed), harness
255
+ hardening, Phase 4/5 tasks.
256
+
257
+ ## Notes
258
+
259
+ - `[P]` = parallel: different files, no dependency.
260
+ - `[US1]` = user story from `spec.md`; every task has one.
261
+ - Keep task ids stable; add new ones, do not renumber.
262
+ - Change code and spec together; update the plan if behavior changes.
263
+ - Tick a task only when its verification passes.