@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,212 @@
1
+ # Tasks: Low-Level Agent Orchestration
2
+
3
+ Work through these tasks in order unless a task is explicitly marked as
4
+ independent. Cross off a task only after its implementation and verification
5
+ are complete.
6
+
7
+ ## Phase 1 — Foundations
8
+
9
+ - [x] **1.1 Define public lifecycle types**
10
+ - Add serializable `AgentHandle`, `PromptHandle`, `Status`, and `Result`
11
+ shapes.
12
+ - Define supported lifecycle states and structured error fields.
13
+ - Keep public handles opaque; do not require callers to pass raw pane IDs.
14
+
15
+ - [x] **1.2 Add agent and prompt registries**
16
+ - Track live agents by stable handle ID.
17
+ - Track prompts by stable prompt ID.
18
+ - Associate each prompt with its owning agent.
19
+ - Track one unresolved prompt per agent.
20
+ - Add lookup, invalidation, settlement, and cleanup helpers.
21
+
22
+ - [x] **1.3 Preserve ownership and safety invariants**
23
+ - Reuse the created-pane registry for ownership checks.
24
+ - Reject foreign, unknown, and closed handles clearly.
25
+ - Ensure raw pane IDs cannot bypass close ownership checks.
26
+ - Define behavior for stale registries and extension reloads.
27
+
28
+ ## Phase 2 — Persistent `start`
29
+
30
+ - [x] **2.1 Separate launch from task submission**
31
+ - Refactor Herdr launch helpers so starting pi does not require a task.
32
+ - Preserve agent system prompt, tools, model, cwd, and prompt-mode behavior.
33
+ - Remove `stayOpen` from the new low-level start path.
34
+ - Ensure the launched agent remains alive until explicitly closed.
35
+
36
+ - [x] **2.2 Add placement options**
37
+ - Support requested tab or sibling-pane placement.
38
+ - Preserve caller cwd unless overridden.
39
+ - Use `--no-focus` by default for background agents.
40
+ - Parse all Herdr IDs from command results rather than predicting them.
41
+
42
+ - [x] **2.3 Implement `start(agent, options)`
43
+ - Discover the agent fresh from disk.
44
+ - Apply user/project scope and trust confirmation.
45
+ - Ensure Herdr is available.
46
+ - Create and record the pane/tab.
47
+ - Launch pi with no initial user message.
48
+ - Wait for shell readiness and Herdr agent detection.
49
+ - Register and return an `AgentHandle`.
50
+ - Clean up safely if startup fails after pane creation.
51
+
52
+ - [x] **2.4 Verify `start`**
53
+ - Confirmed `startAgent("scout", ...)` returned a stable serialized handle.
54
+ - Confirmed the agent was detected and reported `idle` through `statusAgent`.
55
+ - Confirmed the persistent agent remained addressable after `start` returned.
56
+ - Confirmed the created Herdr tab/pane was closed through the ownership-safe path.
57
+ - The live check used the current workspace and explicit cwd; placement is currently tab-based.
58
+ - Project-agent trust gating remains implemented in `startAgent`.
59
+
60
+ ## Phase 3 — Non-blocking `prompt`
61
+
62
+ - [x] **3.1 Add non-blocking prompt submission**
63
+ - Resolve and validate the `AgentHandle`.
64
+ - Reject agents with an unresolved prompt.
65
+ - Confirm Herdr detects the agent before sending.
66
+ - Submit exactly one message without waiting for completion.
67
+ - Detect failed submission and settle it without returning a usable handle.
68
+ - Register and immediately return a `PromptHandle`.
69
+
70
+ - [x] **3.2 Track prompt lifecycle**
71
+ - Store submission time and timeout.
72
+ - Associate prompt state with its agent.
73
+ - Ensure submission errors do not leave phantom active prompts.
74
+ - Ensure an agent becomes promptable again after settlement.
75
+
76
+ - [x] **3.3 Verify `prompt`**
77
+ - Confirmed `promptAgent` returned a prompt handle without waiting for completion.
78
+ - Confirmed a second prompt on the same agent was rejected while active.
79
+ - Confirmed waiting settled the prompt and a subsequent prompt was accepted.
80
+ - Confirmed prompt/result IDs remained associated across both prompts.
81
+ - Submission failure handling is implemented; a dedicated forced-failure check remains useful.
82
+
83
+ ## Phase 4 — `wait`
84
+
85
+ - [x] **4.1 Implement single-prompt wait**
86
+ - Waits for a post-submission Herdr transition rather than accepting pre-submit idle.
87
+ - Handles idle, done, blocked, timeout, and cancellation results.
88
+ - Recovers diagnostic response text from the pane after settlement.
89
+ - Does not read or delete the live child session file.
90
+ - Returns a structured `Result` tied to prompt and agent IDs.
91
+ - Clears the agent's active prompt exactly once.
92
+
93
+ - [x] **4.2 Implement multi-prompt wait**
94
+ - Accepts one prompt handle or an array of handles.
95
+ - Waits concurrently for arrays using `Promise.all`.
96
+ - Preserves input ordering in the result array.
97
+ - Returns one structured result per input, including failures.
98
+ - Converts individual wait errors into failed results so successful results remain visible.
99
+ - Supports wait-for-all only.
100
+
101
+ - [x] **4.3 Verify `wait`**
102
+ - Verified prompt results preserve their corresponding prompt IDs.
103
+ - Verified two prompts were waited concurrently.
104
+ - Verified multi-wait preserves input order.
105
+ - Verified an unknown prompt produced a failed result alongside a successful result.
106
+ - Verified settled prompts can be reused for subsequent lifecycle checks.
107
+
108
+ ## Phase 5 — `status` and `close`
109
+
110
+ - [x] **5.1 Implement handle-based `status`**
111
+ - Resolves an `AgentHandle`.
112
+ - Queries Herdr without focusing or mutating the pane.
113
+ - Returns stable identity and placement metadata.
114
+ - Maps missing panes to `failed` and closed handles to `closed`.
115
+ - Handles stale and closed handles with clear errors/results.
116
+
117
+ - [x] **5.2 Implement handle-based `close`**
118
+ - Resolves only valid lifecycle handles.
119
+ - Refuses panes absent from the pi-shepherd ownership registry.
120
+ - Cancels unresolved prompts deterministically.
121
+ - Closes the pane through the existing safe path.
122
+ - Cleans temporary resources only after pane disappearance.
123
+ - Repeated close calls are idempotent.
124
+
125
+ - [x] **5.3 Verify lifecycle termination**
126
+ - Verified `wait` leaves the agent alive after normal settlement.
127
+ - Verified `close` terminated the created Herdr pane.
128
+ - Verified waiting after close returned `cancelled`.
129
+ - Verified status after close returned `closed`.
130
+ - Verified an unowned/foreign handle is rejected without closing its pane.
131
+
132
+ ## Phase 6 — Shepherd tool integration
133
+
134
+ - [x] **6.1 Add tool schemas**
135
+ - Add `action: "start"` with agent and launch/placement options.
136
+ - Add `action: "prompt"` with agent handle and message.
137
+ - Add `action: "wait"` with one or many prompt handles.
138
+ - Update `status` and `close` to accept agent handles.
139
+ - Keep `sheep`, `herd`, `read`, and `prune`.
140
+
141
+ - [x] **6.2 Update tool execution**
142
+ - Route actions to the lifecycle primitives.
143
+ - Return structured handles, statuses, and results.
144
+ - Preserve useful human-readable text output.
145
+ - Return partial multi-wait results on failure.
146
+ - Maintain clear invalid-handle errors.
147
+
148
+ - [x] **6.3 Update model-facing guidance**
149
+ - Explain start-without-task semantics.
150
+ - Explain prompt-then-wait semantics.
151
+ - Show parallel work using `wait([promptA, promptB])`.
152
+ - Show chains as explicit caller composition.
153
+ - Explain that `close` is explicit.
154
+
155
+ ## Phase 7 — Compatibility migration
156
+
157
+ - [x] **7.1 Remove legacy delegation**
158
+ - Deleted the legacy `delegate` action and workflow modes.
159
+ - Removed `subagent.ts` and the one-shot delegation runner.
160
+ - Low-level lifecycle primitives are now the only orchestration API.
161
+
162
+ - [x] **7.2 Resolve lifecycle cleanup policy**
163
+ - Legacy compatibility cleanup is no longer applicable because delegation was removed.
164
+ - `start` never closes automatically; callers explicitly call `close`.
165
+ - One-shot behavior is explicitly composed as `start + prompt + wait + close`.
166
+ - `stayOpen` is not exposed on the low-level `start` schema.
167
+
168
+ - [x] **7.3 Update slash commands**
169
+ - Keep existing slash-command compatibility where useful.
170
+ - Ensure its implementation does not depend on task-bearing `start`.
171
+ - Update output to show returned handles where relevant.
172
+
173
+ ## Phase 8 — Documentation and tests
174
+
175
+ - [x] **8.1 Update README**
176
+ - Documents the low-level primitive API.
177
+ - Replaces workflow examples with explicit composition examples.
178
+ - Documents persistent start and explicit close.
179
+ - Documents that legacy delegation modes were removed.
180
+
181
+ - [x] **8.2 Update root `PLAN.md`**
182
+ - Replaced the workflow-centric architecture description.
183
+ - Recorded lifecycle primitive implementation status.
184
+ - Kept runtime, Herdr, and security invariants accurate.
185
+
186
+ - [x] **8.3 Add registry tests**
187
+ - Added `test/verify-registry.mjs` covering serialization, lookup, unknown handles,
188
+ active-prompt enforcement, idempotent settlement, and cancellation.
189
+
190
+ - [x] **8.4 Add multi-wait tests**
191
+ - Added `test/verify-multi-wait.mjs` covering concurrent waiting and input order.
192
+ - Live verification covered partial failure results and cancellation handling.
193
+
194
+ - [x] **8.5 Run live Herdr verification**
195
+ - Started idle `scout` agents in live Herdr tabs.
196
+ - Confirmed non-blocking prompt return and exact response recovery.
197
+ - Waited for a single result and verified prompt/result association.
198
+ - Started two agents, prompted both, and waited concurrently with ordered results.
199
+ - Exercised iterative prompting on one persistent agent.
200
+ - Closed agents and verified cancellation, closed status, and cleanup.
201
+ - Verified background starts preserved the focused caller pane.
202
+ - Verified ownership protection refused a foreign pane handle.
203
+
204
+ ## Completion checklist
205
+
206
+ - [x] All Phase 1–5 lifecycle primitives work independently of workflow modes.
207
+ - [x] All Phase 6 tool actions are available and documented.
208
+ - [x] Legacy workflows were removed rather than retained as wrappers.
209
+ - [x] Existing discovery, trust, Herdr, and temp-file safety behavior remains
210
+ intact.
211
+ - [x] README and root `PLAN.md` are synchronized with the implementation.
212
+ - [x] Tests and live Herdr verification pass.
@@ -0,0 +1,396 @@
1
+ # Implementation Plan: Shepherd-bound Note Sessions
2
+
3
+ This plan implements `spec.md` by restoring the durable note layer as a
4
+ parent-pi-session concern while preserving the low-level lifecycle API from
5
+ `specs/002-simplify-agent-orchestration/`.
6
+
7
+ The central invariant is:
8
+
9
+ ```text
10
+ same parent pi session + same project root
11
+ => one persistent note session directory
12
+ => one note per submitted child invocation
13
+ ```
14
+
15
+ A child pane, child JSONL file, agent handle, prompt handle, or
16
+ `LifecycleRegistry.sessionId` must never allocate a new persistent note
17
+ session.
18
+
19
+ ## Target architecture
20
+
21
+ ```text
22
+ pi parent context
23
+ ctx.sessionManager.getSessionId()
24
+ ctx.cwd
25
+ │
26
+ ▼
27
+ parent-session binding
28
+ { parentPiSessionId, projectRoot, noteSession }
29
+ │
30
+ ├── startAgent(...)
31
+ │ └── starts idle child; reuses binding; no note yet
32
+ │
33
+ └── promptAgent(...)
34
+ ├── reserve note in binding.sessionPath
35
+ ├── append note context to child message
36
+ ├── submit message
37
+ └── finalize note from wait result
38
+
39
+ artifact-sessions.ts
40
+ filesystem allocation, lookup, locking, fieldnotes, metadata, notes
41
+
42
+ orchestration.ts
43
+ in-memory handles/prompts plus internal note association
44
+ ```
45
+
46
+ ## Design decisions
47
+
48
+ 1. **Parent identity source** — use the pi-provided
49
+ `ctx.sessionManager.getSessionId()` as the opaque parent identity. Use
50
+ `getSessionFile()` as diagnostic/resume metadata, not as the child note
51
+ file. Do not derive identity from a task, agent name, pane ID, or lifecycle
52
+ UUID.
53
+ 2. **Binding root** — use the parent tool context's effective `ctx.cwd` as the
54
+ note project root. A child `start` `cwd` override affects child launch
55
+ only; it does not move the shared note session to another project.
56
+ 3. **Lazy shared allocation** — the first `start` resolves and creates the
57
+ parent-bound note session so its result can expose the shared path.
58
+ `start` itself reserves no per-agent note. Later starts in the same
59
+ parent/project binding reuse the existing directory.
60
+ 4. **Per-invocation reservation** — `prompt` reserves one note immediately
61
+ before message submission. This represents actual work and gives each
62
+ prompt a stable note path. Parallel prompt calls reserve under the
63
+ session lock.
64
+ 5. **Internal association** — attach the resolved note session to each
65
+ registered agent record and the reserved note to each prompt record.
66
+ Public handles remain lifecycle handles; note paths are returned in tool
67
+ details and are not caller-supplied handle identity.
68
+ 6. **No implicit legacy continuation** — old sessions lacking parent binding
69
+ metadata are not selected by slug/name alone. Any migration must be
70
+ explicit and separate from normal allocation.
71
+ 7. **Durability boundary** — note writes are finalized after the existing
72
+ completion signal/state boundary. Closing a child never removes the shared
73
+ note session.
74
+
75
+ ## Phase 1 — Establish the parent-session contract
76
+
77
+ ### 1.1 Add parent context types
78
+
79
+ Add an internal type, for example `ParentNoteContext`, containing:
80
+
81
+ - opaque `parentPiSessionId`;
82
+ - optional `parentSessionFile` for diagnostics;
83
+ - canonical `projectRoot`;
84
+ - resolved persistent note-session metadata/path.
85
+
86
+ Add an `NoteSessionRef` and `NoteRef` type for the data needed by
87
+ lifecycle records and tool result details. Keep filesystem implementation
88
+ objects out of public TypeBox schemas where possible.
89
+
90
+ ### 1.2 Resolve identity from pi
91
+
92
+ Add a helper at the Shepherd tool boundary that receives the real extension
93
+ context and obtains:
94
+
95
+ ```ts
96
+ const parentPiSessionId = ctx.sessionManager.getSessionId();
97
+ const parentSessionFile = ctx.sessionManager.getSessionFile();
98
+ const projectRoot = path.resolve(ctx.cwd);
99
+ ```
100
+
101
+ Validate that the identity is non-empty and that the project root is usable.
102
+ Do not use `lifecycleRegistry.sessionId` for this purpose.
103
+
104
+ Confirm the session manager behavior for a resumed session: the same pi
105
+ session must return an identity that finds the existing note directory.
106
+ Document the fallback policy if a non-persisted/in-memory pi context has no
107
+ session file.
108
+
109
+ ### 1.3 Add parent-binding cache
110
+
111
+ Create a small parent binding registry, either in a new `parent-session.ts` or
112
+ inside the note session module. It should:
113
+
114
+ - key entries by `(parentPiSessionId, projectRoot)`;
115
+ - return the same binding for repeated tool calls;
116
+ - be safe if the extension receives an equivalent context object each call;
117
+ - never key by child handle, agent, or prompt;
118
+ - allow reloading the binding from disk after an extension restart.
119
+
120
+ The cache is an optimization, not the source of truth. `session.json` remains
121
+ the durable authority.
122
+
123
+ ## Phase 2 — Restore the filesystem note module
124
+
125
+ ### 2.1 Reintroduce the historical persistence code
126
+
127
+ Create `artifact-sessions.ts` (or restore `sessions.ts` with the new contract)
128
+ by extracting the useful filesystem behavior from the deleted historical
129
+ `sessions.ts`:
130
+
131
+ - safe session and agent slugging;
132
+ - numbered session allocation;
133
+ - exact metadata lookup;
134
+ - `.alloc`/exclusive allocation locking;
135
+ - note reservation and per-agent ordinals;
136
+ - atomic same-directory writes;
137
+ - serialized session updates;
138
+ - fieldnotes rendering;
139
+ - note status transitions and finalization.
140
+
141
+ Keep this module independent of pi, Herdr, and TUI imports so it can be tested
142
+ with temporary directories.
143
+
144
+ ### 2.2 Implement parent-bound lookup/allocation
145
+
146
+ Implement an API similar to:
147
+
148
+ ```ts
149
+ resolveOrCreateParentNoteSession({
150
+ projectRoot,
151
+ parentPiSessionId,
152
+ parentSessionFile,
153
+ }): NoteSession
154
+ ```
155
+
156
+ Under the project `.shepherd/sessions/` directory:
157
+
158
+ 1. acquire the root allocation lock;
159
+ 2. scan only validated numbered session directories;
160
+ 3. parse and validate `session.json`;
161
+ 4. find an exact binding match for both parent identity and project root;
162
+ 5. return that directory if found;
163
+ 6. otherwise allocate a unique ordinal and create one new directory;
164
+ 7. write versioned `session.json` and `shepherd.md` atomically; and
165
+ 8. release the lock.
166
+
167
+ The persisted metadata must include a note-session version and parent
168
+ binding fields. Do not trust persisted absolute paths; derive paths from the
169
+ current validated project/session root.
170
+
171
+ If metadata is malformed or an old session lacks the binding, skip it for
172
+ normal lookup and leave it untouched. Do not silently attach it to the current
173
+ parent.
174
+
175
+ ### 2.3 Preserve collision and path safety
176
+
177
+ Retain and test the existing behavior for:
178
+
179
+ - traversal/control-character rejection;
180
+ - safe lowercase slugs;
181
+ - same-slug/different-identity suffixes;
182
+ - unique ordinals under concurrent allocation;
183
+ - note filename collisions;
184
+ - descendant checks for all generated paths.
185
+
186
+ No global `.shepherd/shepherd.md` file is introduced.
187
+
188
+ ### 2.4 Add note lifecycle operations
189
+
190
+ Expose operations for:
191
+
192
+ ```ts
193
+ reserveNotes(session, planned)
194
+ markNoteStarted(session, note, metadata)
195
+ markNoteStatus(session, note, status, metadata)
196
+ finalizeNote(session, note, result)
197
+ updateSessionMoc(session, update)
198
+ readSessionMetadata(sessionPath)
199
+ ```
200
+
201
+ Every mutating operation must lock the session, reload current metadata,
202
+ update it, and atomically rewrite `session.json`, note content, and fieldnotes as
203
+ needed. Preserve agent-authored note content while appending orchestration
204
+ metadata/output.
205
+
206
+ ## Phase 3 — Integrate binding with lifecycle state
207
+
208
+ ### 3.1 Extend internal records
209
+
210
+ Update `orchestration.ts` so `AgentRecord` can reference the parent note
211
+ session and `PromptRecord` can reference its reserved note. These fields
212
+ are internal and must not change handle validation semantics.
213
+
214
+ The record association must survive all operations in one parent extension
215
+ process:
216
+
217
+ ```text
218
+ AgentRecord -> NoteSessionRef
219
+ PromptRecord -> NoteRef + NoteSessionRef
220
+ ```
221
+
222
+ Do not replace or repurpose `LifecycleRegistry.sessionId`.
223
+
224
+ ### 3.2 Resolve the binding on `start`
225
+
226
+ Update the model-facing `doAction` path in `shepherd.ts` and the lifecycle
227
+ boundary so `start`:
228
+
229
+ 1. resolves the parent binding from the current `ctx`;
230
+ 2. creates/reuses the single note session;
231
+ 3. starts the idle Herdr child exactly as today;
232
+ 4. registers the agent with the note-session reference; and
233
+ 5. returns the handle plus shared session details.
234
+
235
+ A failed child launch may leave the already-created shared session directory,
236
+ but must not create a second session during cleanup and must not create an
237
+ agent note for an idle start.
238
+
239
+ ### 3.3 Reserve and inject context on `prompt`
240
+
241
+ Before submitting a prompt:
242
+
243
+ 1. resolve the canonical agent handle;
244
+ 2. obtain its parent note-session reference;
245
+ 3. reserve one note under the session lock;
246
+ 4. mark it running or pending according to the chosen lifecycle boundary;
247
+ 5. append the note context block to the original message;
248
+ 6. create the prompt record with the note reference; and
249
+ 7. submit the augmented message without waiting.
250
+
251
+ The original task must remain intact. The context block must include absolute
252
+ and project-relative session/fieldnotes/note paths and the read/write ownership
253
+ instructions from the spec.
254
+
255
+ If submission fails, finalize the reserved note as `failed` or `cancelled`
256
+ and return no usable prompt handle. Do not allocate a replacement session or
257
+ note.
258
+
259
+ ### 3.4 Finalize from `wait`
260
+
261
+ Update `waitOne` so every terminal path finalizes the prompt's note:
262
+
263
+ - completed/idle/done: preserve final text;
264
+ - blocked: preserve blocked state and available output;
265
+ - timeout: record timeout details without reading a still-live child file;
266
+ - cancellation/close: record cancellation;
267
+ - failure: record error and diagnostic output.
268
+
269
+ Ensure finalization is idempotent when multiple callers wait on the same
270
+ settled prompt. Keep current prompt settlement and active-slot behavior.
271
+
272
+ ### 3.5 Handle close and parent lifecycle
273
+
274
+ `closeAgent` must:
275
+
276
+ - cancel/finalize any unresolved note owned by the agent;
277
+ - close only the owned pane;
278
+ - remove only safe temporary child launch resources after pane exit; and
279
+ - retain the shared note session and all notes.
280
+
281
+ Add a parent-session shutdown/reload policy that flushes in-memory metadata if
282
+ needed but never deletes the persistent note directory.
283
+
284
+ ## Phase 4 — Tool results and child guidance
285
+
286
+ ### 4.1 Extend result details
287
+
288
+ Update `shepherd.ts` result details so note-producing actions expose the
289
+ shared session without making callers reconstruct paths:
290
+
291
+ - `start`: opaque `id` plus `noteSession`/`sessionPath`;
292
+ - `prompt`: opaque `id` plus reserved `note` and shared session path;
293
+ - `wait`: result(s) including note reference where available.
294
+
295
+ Use relative paths for project-internal links and absolute paths where the
296
+ child needs to write. Keep the public lifecycle id schemas compatible with the opaque-id contract;
297
+ full handles remain internal implementation state.
298
+
299
+ ### 4.2 Update tool descriptions and previews
300
+
301
+ Update the tool description, prompt snippet, guidelines, and call preview only
302
+ as needed to explain:
303
+
304
+ - all agents started by one parent share one note session;
305
+ - prompt notes are reserved before submission;
306
+ - children must read the shared fieldnotes and write only their assigned note;
307
+ - lifecycle ids must be passed as top-level strings (or an array of strings for multi-wait); and
308
+ - notes are retained and not automatically cleaned up.
309
+
310
+ Do not expose a user option that lets an individual child force a new
311
+ note-session directory.
312
+
313
+ ### 4.3 Preserve child completion signaling
314
+
315
+ Keep `shepherd_done.ts` and the completion sidecar focused on child execution
316
+ completion. If completion signaling needs to identify a note, pass the
317
+ assigned note reference through the child launch/prompt context or retain
318
+ it in the parent prompt record. The child must not allocate a session from its
319
+ own environment.
320
+
321
+ ## Phase 5 — Tests
322
+
323
+ ### 5.1 Filesystem tests
324
+
325
+ Add `test/verify-artifact-sessions.mjs` covering:
326
+
327
+ - safe slugs and traversal rejection;
328
+ - first parent binding allocation;
329
+ - repeated lookup of the same parent/project pair;
330
+ - same task with different parent IDs producing separate sessions;
331
+ - same parent ID across repeated calls retaining notes;
332
+ - project-root isolation;
333
+ - note ordinals and collision-safe filenames;
334
+ - fieldnotes and metadata updates;
335
+ - parallel reservation before execution;
336
+ - atomic writes and no temporary-file leftovers;
337
+ - failure/timeout/cancellation finalization;
338
+ - concurrent numbering and binding allocation; and
339
+ - legacy unbound sessions not being implicitly selected.
340
+
341
+ Use temporary project roots and fake opaque parent IDs. Never write tests into
342
+ the repository's real `.shepherd/sessions/` tree.
343
+
344
+ ### 5.2 Registry/lifecycle tests
345
+
346
+ Extend `test/verify-registry.mjs` or add a focused test for:
347
+
348
+ - agent records retaining note-session references;
349
+ - prompts retaining note references;
350
+ - lifecycle UUID changes not changing note paths;
351
+ - duplicate finalization being harmless;
352
+ - close cancellation retaining note metadata; and
353
+ - handles from a different parent binding being rejected or clearly invalid.
354
+
355
+ ### 5.3 Integration seam
356
+
357
+ If direct lifecycle tests would require a live Herdr server, add a narrow
358
+ injectable seam around the note resolver/reserver rather than mocking the
359
+ whole Herdr CLI. Verify that two `start` calls and two `prompt` calls made with
360
+ the same parent context receive one session path.
361
+
362
+ A live Herdr check should then cover one scout and one planner in the same
363
+ parent session, with both note paths reported under the same directory.
364
+
365
+ ## Phase 6 — Documentation and migration
366
+
367
+ Update:
368
+
369
+ - `README.md` with the shared parent-session note behavior and layout;
370
+ - `PLAN.md` with the note binding architecture and lifecycle boundaries;
371
+ - relevant comments in `shepherd.ts`, `lifecycle.ts`, and
372
+ `orchestration.ts`; and
373
+ - the spec's migration notes if implementation choices differ.
374
+
375
+ Keep `.shepherd/` ignored as runtime data. Do not add automatic cleanup or
376
+ silently migrate existing unbound sessions.
377
+
378
+ ## Verification and completion order
379
+
380
+ Run in this order:
381
+
382
+ 1. `git diff --check`.
383
+ 2. Filesystem note-session tests.
384
+ 3. Registry/lifecycle tests.
385
+ 4. Full `npm test`.
386
+ 5. Live Herdr verification of two agents sharing one directory.
387
+ 6. Manual inspection of `session.json`, `shepherd.md`, and both notes.
388
+
389
+ Completion requires the regression assertion:
390
+
391
+ ```text
392
+ one parent session, two child invocations
393
+ => one .shepherd/sessions/NNNN-* directory
394
+ => two distinct note files in that directory
395
+ => one fieldnotes collection linking both files
396
+ ```