@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,453 @@
1
+ # Shepherd-bound Shepherd Note Sessions
2
+
3
+ ## Status
4
+
5
+ Proposed specification.
6
+
7
+ ## Summary
8
+
9
+ Restore durable Shepherd notes as a concern of the **parent pi session**.
10
+ The parent pi process is the shepherd. Every agent started, prompted, and
11
+ waited on through that parent must use one note session directory for the
12
+ same project root. Starting a second sheep must reserve another note in
13
+ the existing directory; it must never create a second
14
+ `.shepherd/sessions/NNNN-slug/` directory merely because it is a different
15
+ agent or a different `start` call.
16
+
17
+ The durable note session is distinct from:
18
+
19
+ - a child pi session or child JSONL session file;
20
+ - a Herdr pane, tab, or agent handle; and
21
+ - the in-memory `LifecycleRegistry.sessionId` used to namespace lifecycle
22
+ handles inside one extension process.
23
+
24
+ The parent pi session is the authoritative owner and lifetime boundary for the
25
+ note context. Notes must survive multiple Shepherd tool calls during
26
+ that parent session and must remain on disk after the parent session ends.
27
+
28
+ This specification builds on `specs/001-artifacts/spec.md` and preserves its
29
+ fieldnotes, per-invocation notes, provenance, collision handling, atomic updates,
30
+ and no-auto-cleanup requirements. It adapts those requirements to the current
31
+ low-level API from `specs/002-simplify-agent-orchestration/spec.md`.
32
+
33
+ ## Problem
34
+
35
+ The previous note design created or resumed a durable session only when a
36
+ caller supplied a workflow-level `sessionName`. The low-level `start` API has
37
+ no such workflow identity, and separate sheep starts can therefore be
38
+ interpreted as separate sessions. This breaks the intended shared note
39
+ store: a scout, planner, worker, and reviewer launched by one parent pi
40
+ conversation can receive unrelated note folders.
41
+
42
+ The note allocator must instead resolve its session from the parent
43
+ shepherd pi session before the first child is launched, cache that binding
44
+ for subsequent calls, and pass the resulting context to each child.
45
+
46
+ ## Goals
47
+
48
+ - Bind note storage to the parent/shepherd pi session.
49
+ - Reuse one durable session directory for all child agents delegated by that
50
+ parent in the same project.
51
+ - Preserve notes across multiple Shepherd tool calls, including calls made
52
+ after earlier agents complete.
53
+ - Support sequential, parallel, and caller-composed workflows without making
54
+ those workflows special lifecycle primitives.
55
+ - Reserve one unique note per delegated invocation before that invocation
56
+ starts, including parallel fan-outs.
57
+ - Keep the session fieldnotes readable, durable, and updated atomically.
58
+ - Preserve provenance, final output, errors, lifecycle status, and relative
59
+ navigation links.
60
+ - Remain safe when multiple tool calls race or when a parent session is
61
+ resumed after a restart.
62
+ - Make the binding observable in tool results and child context so an
63
+ shepherd can verify which session is being used.
64
+
65
+ ## Non-goals
66
+
67
+ - Do not create one note session per child agent, pane, tab, prompt, or
68
+ `start` call.
69
+ - Do not use `LifecycleRegistry.sessionId` as the durable note-session ID.
70
+ - Do not use a child pi JSONL path or child process environment as the parent
71
+ session identity.
72
+ - Do not create a global `.shepherd/shepherd.md` index.
73
+ - Do not require agents to edit the fieldnotes or another agent's note.
74
+ - Do not add a generic shared writable scratch file for parallel agents.
75
+ - Do not automatically commit, checkout, delete, or clean up notes.
76
+ - Do not make note persistence depend on an agent remaining open after its
77
+ prompt completes.
78
+ - Do not reintroduce workflow-specific `single`, `parallel`, or `chain` modes
79
+ into the low-level `start`, `prompt`, and `wait` API.
80
+
81
+ ## Terminology
82
+
83
+ ### Parent pi session
84
+
85
+ The pi session in which the Shepherd extension is registered and whose model
86
+ invokes the `shepherd` tool. This is the shepherd session. It owns the
87
+ note-session binding.
88
+
89
+ ### Child pi session
90
+
91
+ The pi process launched in a Herdr pane by `start`. A child may have its own
92
+ JSONL session file, but that file is execution state and is not a note
93
+ session identity.
94
+
95
+ ### Persistent note session
96
+
97
+ The durable project-local directory under
98
+ `.shepherd/sessions/NNNN-<slug>/`. It contains one `shepherd.md` fieldnotes index,
99
+ `session.json`, and one note file per child invocation.
100
+
101
+ ### Invocation
102
+
103
+ One unit of work submitted to a child and represented by one note. In the
104
+ current API this is the successful `prompt` operation associated with a child;
105
+ the implementation may reserve the note at `start` time when the initial
106
+ work plan is known, or at prompt time before submitting the message. A bare
107
+ idle `start` must not create a note for work that has not been submitted.
108
+
109
+ ## Binding model
110
+
111
+ ### Required identity
112
+
113
+ At the beginning of the parent pi session, or lazily before the first
114
+ note-producing Shepherd operation, the extension must obtain a stable
115
+ parent-session identity from the pi runtime. The identity must be available to
116
+ all subsequent tool calls in that parent session and must remain stable across
117
+ extension callbacks and asynchronous lifecycle operations.
118
+
119
+ The implementation should use the pi-provided session identity or canonical
120
+ parent session path when available. It must not invent a new durable identity
121
+ for each child. If the pi runtime exposes no stable public identity, the
122
+ extension must establish one at parent-session initialization and retain it in
123
+ an in-memory parent-session binding for the lifetime of the shepherd. The
124
+ fallback must be documented and must not be `LifecycleRegistry.sessionId`.
125
+
126
+ The binding key is:
127
+
128
+ ```text
129
+ (parentPiSessionIdentity, effectiveProjectRoot)
130
+ ```
131
+
132
+ The project root is the effective `cwd` used for the operation, normally the
133
+ parent tool context's `ctx.cwd`. A child `cwd` override does not silently move
134
+ a note session to another project: the note session remains owned by
135
+ the parent project root unless the API explicitly defines a separate,
136
+ validated parent project context. Implementations must reject or clearly
137
+ separate cross-project operations rather than merging notes from unrelated
138
+ roots.
139
+
140
+ ### Allocation and reuse
141
+
142
+ On the first note-producing operation for a binding:
143
+
144
+ 1. Resolve the effective project root.
145
+ 2. Resolve the parent pi session identity.
146
+ 3. Look up an existing binding for that pair.
147
+ 4. If found, load and validate its `session.json`.
148
+ 5. If not found, allocate exactly one numbered session directory under
149
+ `<projectRoot>/.shepherd/sessions/`, persist the parent binding metadata,
150
+ and initialize `shepherd.md` and `session.json`.
151
+ 6. Cache the resolved session context for later Shepherd calls.
152
+
153
+ Every later note-producing operation for the same parent binding must reuse
154
+ the same `sessionPath`, even if it starts a different agent, uses a different
155
+ Herdr pane, or occurs in a later tool call. In particular:
156
+
157
+ ```text
158
+ parent pi session P:
159
+ spawn scout -> .shepherd/sessions/0007-task/
160
+ prompt scout -> .shepherd/sessions/0007-task/scout-01.md
161
+ spawn planner -> .shepherd/sessions/0007-task/
162
+ prompt planner -> .shepherd/sessions/0007-task/planner-01.md
163
+ spawn worker -> .shepherd/sessions/0007-task/
164
+ prompt worker -> .shepherd/sessions/0007-task/worker-01.md
165
+ ```
166
+
167
+ The second `spawn` must not allocate `0008-*` solely because the agent differs
168
+ from the first one. A new numbered directory is allowed only when the parent
169
+ pi session identity or effective project root is different, or when the
170
+ existing binding is invalid and recovery follows the rules below.
171
+
172
+ ### Parent-session binding metadata
173
+
174
+ `session.json` must record enough information to distinguish a parent-bound
175
+ session from an unrelated durable session. In addition to the fields retained
176
+ from `001-artifacts`, it must contain a versioned binding object or equivalent
177
+ fields:
178
+
179
+ ```json
180
+ {
181
+ "noteSessionVersion": 2,
182
+ "parentPiSession": {
183
+ "identity": "<opaque pi-provided identity>",
184
+ "projectRoot": "/repo",
185
+ "boundAt": "2025-08-14T09:30:00.000Z"
186
+ }
187
+ }
188
+ ```
189
+
190
+ The identity is opaque and must not be derived from an agent name, task text,
191
+ Herdr pane ID, tab ID, lifecycle handle ID, or child JSONL file. It may be
192
+ stored as a hash or other safe representation if the raw pi identity is not
193
+ appropriate to persist, provided equality can still be checked for resumed
194
+ parent sessions.
195
+
196
+ Absolute paths may be retained for local diagnostics, but project-relative
197
+ paths must remain available for portable note links. Metadata parsing must
198
+ never trust arbitrary paths from disk without resolving and validating them
199
+ under the current project/session root.
200
+
201
+ ### Restart and resumed parent sessions
202
+
203
+ A new pi process that resumes the same pi session must resolve the existing
204
+ parent-bound note directory rather than create another one. The lookup
205
+ must use the pi session identity and validated metadata, not only a slug or
206
+ most-recent directory.
207
+
208
+ If the pi runtime creates a new identity after a true new parent session, the
209
+ new parent is allowed to receive a new note directory, even when the task
210
+ text and slug are identical. Slug equality alone must never merge two parent
211
+ sessions.
212
+
213
+ If binding metadata is missing or corrupt:
214
+
215
+ - do not silently attach the parent to an unrelated session;
216
+ - report a clear recoverable error, or allocate a new session with an explicit
217
+ recovery marker according to the implementation's documented policy; and
218
+ - preserve the old directory and notes without deleting them.
219
+
220
+ If a legacy `001-artifacts` session has no parent binding metadata, it may be
221
+ continued only through an explicit migration or compatibility operation. It
222
+ must not be selected merely because its `sessionName` or slug resembles the
223
+ current task.
224
+
225
+ ## Note layout and fieldnotes
226
+
227
+ For a parent-bound session rooted at `<project>`:
228
+
229
+ ```text
230
+ <project>/.shepherd/
231
+ └── sessions/
232
+ └── 0007-fix-oauth-login/
233
+ ├── shepherd.md
234
+ ├── session.json
235
+ ├── scout-01.md
236
+ ├── planner-01.md
237
+ └── worker-01.md
238
+ ```
239
+
240
+ The session contains exactly one fieldnotes collection. The fieldnotes collection is owned by the shepherd and
241
+ must link every note in this parent session. It must show at least the
242
+ session status, parent binding status or redacted identity, start/update times,
243
+ project, modes observed, note statuses, and flow/order links.
244
+
245
+ fieldnotes writes and `session.json` writes must be serialized and atomic. Parallel
246
+ reservations and completions must not lose entries written by another caller.
247
+ A session spanning multiple tool calls appends new notes and retains all
248
+ previous entries.
249
+
250
+ The implementation may retain the numbered `NNNN-<slug>` layout and safe slug
251
+ normalization from `001-artifacts`. Number allocation must use an exclusive
252
+ lock or equivalent retry-safe filesystem operation. Slug collisions must not
253
+ merge different parent bindings; a deterministic suffix is required when
254
+ needed.
255
+
256
+ ## Note lifecycle
257
+
258
+ Every submitted child invocation receives one note in the shared parent
259
+ session:
260
+
261
+ ```text
262
+ <safe-agent-slug>-NN.md
263
+ ```
264
+
265
+ The per-agent ordinal is scoped to the parent-bound note session and is
266
+ never reused. Different labels that normalize to the same filename must be
267
+ collision-safe. Reservations happen before the corresponding child work is
268
+ submitted, especially for parallel operations.
269
+
270
+ An note must preserve provenance such as:
271
+
272
+ ```yaml
273
+ ---
274
+ noteSessionVersion: 2
275
+ session: 0007-fix-oauth-login
276
+ sessionName: fix-oauth-login
277
+ parentPiSession: <opaque-or-redacted-identity>
278
+ agent: scout
279
+ ordinal: 1
280
+ mode: lifecycle
281
+ status: running
282
+ reservedAt: 2025-08-14T09:30:00.000Z
283
+ started: 2025-08-14T09:30:01.000Z
284
+ pane: w8:pY
285
+ handle: shepherd-agent-...
286
+ ---
287
+ ```
288
+
289
+ The exact metadata representation may evolve, but it must identify the parent
290
+ note session, child agent, invocation, and lifecycle status.
291
+
292
+ The shepherd must initialize the note before submission, update it as
293
+ lifecycle state changes, and finalize it after a safe completion boundary with:
294
+
295
+ - the child’s final text/output when available;
296
+ - failure, timeout, cancellation, or blocked details when applicable;
297
+ - start/completion timestamps; and
298
+ - Herdr and lifecycle identifiers useful for provenance.
299
+
300
+ If a child wrote report content to its assigned note, finalization must
301
+ preserve that content and add a clearly marked orchestration section rather
302
+ than overwrite it. Child instructions must include absolute and relative
303
+ note paths, tell the child to read the fieldnotes first, and prohibit editing the
304
+ fieldnotes or another child’s note.
305
+
306
+ A bare `start` creates or reuses the parent note-session binding but does
307
+ not create a per-agent note until work is actually reserved/submitted. If
308
+ the implementation chooses to reserve at `start`, it must document that the
309
+ reservation represents a planned invocation and must finalize abandoned starts
310
+ as cancelled without allocating another session directory.
311
+
312
+ ## API and integration requirements
313
+
314
+ The low-level lifecycle operations use opaque ids at the model-facing boundary:
315
+
316
+ ```text
317
+ start(agent, options) -> agent id
318
+ prompt(agent id, message, options) -> prompt id
319
+ wait(prompt id | prompt ids, options) -> Result | Result[]
320
+ status(agent id) -> Status
321
+ close(agent id) -> agent id
322
+ ```
323
+
324
+ The implementation may retain full handle objects internally for registry state
325
+ and Herdr placement metadata.
326
+
327
+ Note context is internal to the parent `shepherd` tool and is not a child
328
+ supplied option. The public result details for note-producing operations
329
+ must expose enough context for the shepherd and tests to identify the
330
+ shared session, for example:
331
+
332
+ ```ts
333
+ {
334
+ sessionName: "fix-oauth-login",
335
+ sessionPath: "/repo/.shepherd/sessions/0007-fix-oauth-login",
336
+ sessionRelativePath: ".shepherd/sessions/0007-fix-oauth-login",
337
+ notePath: "/repo/.shepherd/sessions/0007-fix-oauth-login/scout-01.md"
338
+ }
339
+ ```
340
+
341
+ The exact result shape may differ, but `sessionPath` and the note path
342
+ must be available without requiring the child to infer them. `start` may return
343
+ the current shared `sessionPath` if binding is initialized there; it must not
344
+ return a new session path per agent.
345
+
346
+ The session context passed to a child must be constructed by the parent
347
+ shepherd and appended to the task/message without replacing it:
348
+
349
+ ```text
350
+ Shepherd note session context:
351
+ - Session directory: /repo/.shepherd/sessions/0007-fix-oauth-login
352
+ - Session fieldnotes: /repo/.shepherd/sessions/0007-fix-oauth-login/shepherd.md
353
+ - Your note: /repo/.shepherd/sessions/0007-fix-oauth-login/scout-01.md
354
+ - Relative note: .shepherd/sessions/0007-fix-oauth-login/scout-01.md
355
+
356
+ Read the fieldnotes first. Write detailed findings to your assigned note when
357
+ appropriate. Do not edit shepherd.md or another agent's note.
358
+ ```
359
+
360
+ `LifecycleRegistry` may continue to own in-memory handles and prompt state,
361
+ but it must carry or reference the parent note-session binding when
362
+ needed. Its random internal `sessionId` must not be used as the persistent
363
+ session identity and must not cause note-folder allocation.
364
+
365
+ Child `shepherd_done` completion signaling remains an execution/lifecycle
366
+ mechanism. It must update the note belonging to the parent binding, not
367
+ create or resolve a child-owned note session.
368
+
369
+ ## Concurrency and safety
370
+
371
+ - Resolve the parent binding once and serialize allocation with an exclusive
372
+ lock.
373
+ - Serialize session metadata, fieldnotes, and note metadata updates.
374
+ - Reserve all planned notes before launching parallel children.
375
+ - Use same-directory temporary files followed by rename for atomic writes.
376
+ - Validate every session/note path as a descendant of the current project
377
+ and session root.
378
+ - Do not trust child-provided session paths or note paths.
379
+ - Do not let a child choose a different parent binding through prompt text or
380
+ environment variables.
381
+ - A failed child start must finalize its already-reserved note as failed or
382
+ cancelled and must not allocate a replacement session directory.
383
+ - Closing a child must not close or delete the shared note session.
384
+ - Parent shutdown, extension reload, timeout, and Herdr failure must leave
385
+ notes and metadata on disk.
386
+ - No automatic cleanup, commit, checkout, or deletion is performed.
387
+
388
+ ## Migration from the current low-level implementation
389
+
390
+ The current implementation has lifecycle state in `orchestration.ts` and
391
+ `lifecycle.ts`, while the historical note implementation lived in
392
+ `sessions.ts` and the old workflow-oriented `subagent.ts`. The implementation
393
+ should extract/reintroduce the filesystem behavior as a focused module (for
394
+ example `sessions.ts` or `artifact-sessions.ts`) and integrate it at the parent
395
+ `shepherd` tool boundary.
396
+
397
+ The implementation must not allocate notes inside `startAgent` merely
398
+ because it creates a Herdr pane. Instead, the parent orchestration layer must
399
+ resolve the shared binding and reserve notes around actual submitted work.
400
+ Child launch/session files in `herdr.ts` remain temporary execution state.
401
+
402
+ If compatibility with legacy `sessionName` is retained, it is an optional
403
+ human-readable label and lookup hint within the already-resolved parent
404
+ binding. It must not override the parent pi identity or permit two note
405
+ sessions for one parent/project pair. A caller cannot force a new note
406
+ folder for an individual child through an agent name, task, or lifecycle call.
407
+
408
+ ## Verification plan
409
+
410
+ Add filesystem-only and orchestration tests covering at least:
411
+
412
+ 1. **Shared folder regression:** start/prompt a scout, then start/prompt a
413
+ planner in the same parent session; assert both notes and the fieldnotes are in
414
+ exactly the same `sessionPath` and only one numbered directory is created.
415
+ 2. **Repeated calls:** perform the operations in separate tool calls and assert
416
+ the second call reloads the original binding and retains the first note.
417
+ 3. **Parallel fan-out:** reserve multiple notes before launches; assert
418
+ unique paths, one fieldnotes collection, and no lost metadata under concurrent completion.
419
+ 4. **Different parent sessions:** same project and same task/slug but different
420
+ parent pi identities must produce separate sessions.
421
+ 5. **Resume after restart:** reopen the same parent identity and resolve the
422
+ original directory; do not allocate a new one.
423
+ 6. **Project isolation:** the same parent identity operating on different
424
+ project roots must not merge notes.
425
+ 7. **Lifecycle separation:** changing or recreating the in-memory
426
+ `LifecycleRegistry.sessionId` must not change the persistent note path.
427
+ 8. **Bare start:** an idle start does not create an unrelated note and does
428
+ not allocate a second folder when later prompted.
429
+ 9. **Failure paths:** failed start, prompt failure, timeout, cancellation, and
430
+ close preserve note and fieldnotes metadata without deleting the session.
431
+ 10. **Security/concurrency:** traversal rejection, safe collision suffixes,
432
+ atomic writes, exclusive numbering, and ownership validation.
433
+ 11. **Child context:** every child receives the same absolute session directory
434
+ and fieldnotes path, plus its own unique note path.
435
+ 12. **Legacy data:** unbound legacy sessions are not silently attached to a
436
+ new parent session.
437
+
438
+ The primary acceptance assertion is:
439
+
440
+ ```text
441
+ same parent pi session + same project root + N child invocations
442
+ => exactly one persistent note session directory
443
+ => N distinct note files in that directory
444
+ => one fieldnotes collection linking all N notes
445
+ ```
446
+
447
+ ## Retention and cleanup policy
448
+
449
+ Notes are durable project-local records. The extension must not remove
450
+ `.shepherd/sessions/` or any session/note file automatically when a child
451
+ closes, when all prompts settle, when the parent session ends, or when the
452
+ extension reloads. Cleanup, archival, commit, and checkout remain explicit
453
+ future/user operations.
@@ -0,0 +1,141 @@
1
+ # Tasks: Shepherd-bound Note Sessions
2
+
3
+ Implement in order. Mark a task complete only after its code and focused
4
+ verification pass.
5
+
6
+ ## Phase 1 — Parent identity and foundations
7
+
8
+ - [ ] **1.1 Confirm pi identity contract**
9
+ - Verify `ctx.sessionManager.getSessionId()` is stable for a resumed parent
10
+ pi session.
11
+ - Verify `getSessionFile()` is available when the session is persisted.
12
+ - Document the fallback for non-persisted/in-memory sessions.
13
+
14
+ - [ ] **1.2 Define note types**
15
+ - Add parent binding, note session, note reference, and lifecycle
16
+ metadata types.
17
+ - Keep the parent identity opaque.
18
+ - Keep note filesystem types separate from public handle schemas.
19
+
20
+ - [ ] **1.3 Add binding resolver/cache**
21
+ - Key by parent pi session ID plus canonical parent project root.
22
+ - Make cache reuse independent of context object identity.
23
+ - Ensure cache misses reload from disk rather than creating duplicates.
24
+ - Do not use `LifecycleRegistry.sessionId`.
25
+
26
+ ## Phase 2 — Filesystem persistence
27
+
28
+ - [ ] **2.1 Add note session module**
29
+ - Create `artifact-sessions.ts` or restore/adapt `sessions.ts`.
30
+ - Keep it independent of pi, Herdr, and TUI imports.
31
+
32
+ - [ ] **2.2 Implement exact parent-bound lookup**
33
+ - Persist a versioned parent binding in `session.json`.
34
+ - Match exact parent identity and project root.
35
+ - Ignore unbound legacy sessions during normal lookup.
36
+ - Preserve malformed/legacy directories without deletion.
37
+
38
+ - [ ] **2.3 Implement safe allocation**
39
+ - Add exclusive root allocation locking.
40
+ - Allocate unique numbered directories under `.shepherd/sessions/`.
41
+ - Handle slug collisions deterministically.
42
+ - Validate all generated paths as descendants of the project/session root.
43
+
44
+ - [ ] **2.4 Implement session metadata and fieldnotes**
45
+ - Create `session.json` and `shepherd.md` atomically.
46
+ - Record parent binding, status, modes, timestamps, and notes.
47
+ - Serialize updates from parallel callers.
48
+
49
+ - [ ] **2.5 Implement note lifecycle**
50
+ - Reserve per-agent ordinals and collision-safe filenames.
51
+ - Initialize notes before prompt submission.
52
+ - Mark running/status transitions.
53
+ - Finalize output/errors without overwriting agent-authored content.
54
+
55
+ ## Phase 3 — Lifecycle integration
56
+
57
+ - [ ] **3.1 Associate sessions with agents**
58
+ - Extend internal `AgentRecord` metadata with the parent note session.
59
+ - Do not alter public handle identity or lifecycle UUID semantics.
60
+
61
+ - [ ] **3.2 Resolve/reuse on `start`**
62
+ - Resolve the parent binding before child launch.
63
+ - Return the shared session details.
64
+ - Ensure a bare idle start creates no per-agent note.
65
+ - Ensure a second start reuses the first session directory.
66
+
67
+ - [ ] **3.3 Reserve/inject on `prompt`**
68
+ - Reserve one note before submission.
69
+ - Associate it with the prompt record.
70
+ - Append shared fieldnotes/note context without replacing the task.
71
+ - Finalize failed submission and return no prompt handle.
72
+
73
+ - [ ] **3.4 Finalize on `wait`**
74
+ - Persist successful output and terminal lifecycle state.
75
+ - Persist blocked, timeout, failed, and cancelled outcomes.
76
+ - Avoid reading live child session files.
77
+ - Make finalization idempotent.
78
+
79
+ - [ ] **3.5 Preserve close/cleanup safety**
80
+ - Cancel unresolved prompt notes during close.
81
+ - Retain shared session files after close, reload, timeout, and shutdown.
82
+ - Delete only safe temporary child launch resources under existing rules.
83
+
84
+ ## Phase 4 — Tool integration
85
+
86
+ - [ ] **4.1 Expose note details**
87
+ - Include shared session path in `start` details.
88
+ - Include note path in `prompt` details.
89
+ - Include note references in `wait` results.
90
+ - Preserve complete-native-handle requirements.
91
+
92
+ - [ ] **4.2 Update model guidance**
93
+ - Explain one shared note session per parent pi session.
94
+ - Explain fieldnotes/note ownership and retention.
95
+ - Do not expose a per-child force-new-session option.
96
+
97
+ - [ ] **4.3 Verify completion signaling**
98
+ - Ensure `shepherd_done` updates parent-owned prompt/note state.
99
+ - Ensure child environment cannot allocate a new note session.
100
+
101
+ ## Phase 5 — Tests
102
+
103
+ - [ ] **5.1 Add filesystem tests**
104
+ - Shared parent/project lookup.
105
+ - Repeated tool-call retention.
106
+ - Different parent and project isolation.
107
+ - Legacy unbound session handling.
108
+ - Slug/path safety and collision handling.
109
+ - Atomic/concurrent allocation and updates.
110
+ - Lifecycle metadata and finalization.
111
+
112
+ - [ ] **5.2 Add registry tests**
113
+ - Agent-to-session and prompt-to-note association.
114
+ - Lifecycle UUID independence.
115
+ - Idempotent finalization.
116
+ - Close cancellation and retention.
117
+
118
+ - [ ] **5.3 Add orchestration regression test**
119
+ - Two child invocations from one parent context produce one session path,
120
+ two note paths, and one fieldnotes collection.
121
+ - Test calls separated by a simulated tool-call boundary.
122
+
123
+ - [ ] **5.4 Run verification**
124
+ - Run `git diff --check`.
125
+ - Run the new note tests.
126
+ - Run `npm test`.
127
+ - Perform live Herdr verification with two agents sharing one directory.
128
+
129
+ ## Phase 6 — Documentation
130
+
131
+ - [ ] **6.1 Update README**
132
+ - Document parent-session binding, layout, retention, and child context.
133
+
134
+ - [ ] **6.2 Update PLAN.md**
135
+ - Document the note module and its integration boundaries.
136
+
137
+ - [ ] **6.3 Review implementation against spec**
138
+ - Confirm no per-child session allocation remains.
139
+ - Confirm no automatic cleanup/commit/checkout was introduced.
140
+ - Confirm `LifecycleRegistry.sessionId` is not persisted or used for folder
141
+ allocation.