@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.
- package/.agents/agents/README.md +12 -0
- package/.agents/agents/planner.md +38 -0
- package/.agents/agents/reviewer.md +38 -0
- package/.agents/agents/scout.md +43 -0
- package/.agents/agents/worker.md +33 -0
- package/.agents/skills/smoke-test/SKILL.md +155 -0
- package/.agents/skills/smoke-test/references/forensics.md +46 -0
- package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
- package/.github/workflows/publish.yml +77 -0
- package/.pi/prompts/release.md +21 -0
- package/.prettierrc +10 -0
- package/AGENTS.md +88 -0
- package/CONTRIBUTING.md +177 -0
- package/LICENSE +201 -0
- package/README.md +397 -2
- package/docs/README.md +26 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -0
- package/docs/guides/installation.md +61 -0
- package/docs/guides/tool-reference.md +55 -0
- package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
- package/docs/plans/agent-labels.md +257 -0
- package/docs/plans/architecture.md +110 -0
- package/docs/plans/settings-scope.md +163 -0
- package/docs/plans/tool-surface-split.md +278 -0
- package/docs/reference/dictionary +26 -0
- package/docs/releasing.md +47 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
- package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
- package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
- package/index.ts +602 -0
- package/package.json +112 -4
- package/scripts/capture-system-prompt.mjs +45 -0
- package/scripts/extract-pi-system-prompt.mjs +277 -0
- package/scripts/host-impact.mjs +74 -0
- package/scripts/resolve-agent.mjs +43 -0
- package/scripts/show-shepherd-orchestrator.mjs +58 -0
- package/scripts/show-shepherd-prompt.mjs +96 -0
- package/scripts/verify-suites.mjs +67 -0
- package/specs/001-artifacts/spec.md +436 -0
- package/specs/002-simplify-agent-orchestration/plan.md +287 -0
- package/specs/002-simplify-agent-orchestration/spec.md +323 -0
- package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
- package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
- package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
- package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
- package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
- package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
- package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
- package/specs/005-per-workspace-settings/plan.md +230 -0
- package/specs/005-per-workspace-settings/spec.md +368 -0
- package/specs/005-per-workspace-settings/tasks.md +178 -0
- package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
- package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
- package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
- package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
- package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
- package/specs/007-unwatched-completion-notice/journal.md +145 -0
- package/specs/007-unwatched-completion-notice/plan.md +186 -0
- package/specs/007-unwatched-completion-notice/spec.md +284 -0
- package/specs/007-unwatched-completion-notice/tasks.md +147 -0
- package/specs/008-remote-machine-sheep/intent.md +174 -0
- package/specs/008-remote-machine-sheep/journal.md +57 -0
- package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
- package/specs/009-hc-runtime/intent.md +44 -0
- package/specs/009-hc-runtime/plan.md +49 -0
- package/specs/009-hc-runtime/spec.md +118 -0
- package/specs/009-hc-runtime/tasks.md +62 -0
- package/specs/010-unseen-watch-parity/intent.md +57 -0
- package/specs/010-unseen-watch-parity/journal.md +172 -0
- package/specs/010-unseen-watch-parity/plan.md +74 -0
- package/specs/010-unseen-watch-parity/spec.md +191 -0
- package/specs/010-unseen-watch-parity/tasks.md +119 -0
- package/specs/011-hc-background-poll/intent.md +57 -0
- package/specs/011-hc-background-poll/journal.md +95 -0
- package/specs/011-hc-background-poll/plan.md +87 -0
- package/specs/011-hc-background-poll/spec.md +141 -0
- package/specs/011-hc-background-poll/tasks.md +83 -0
- package/specs/012-steer-default/intent.md +12 -0
- package/specs/012-steer-default/journal.md +40 -0
- package/specs/012-steer-default/plan.md +7 -0
- package/specs/012-steer-default/spec.md +42 -0
- package/specs/012-steer-default/tasks.md +6 -0
- package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
- package/specs/013-opencode-shepherd/intent.md +59 -0
- package/specs/013-opencode-shepherd/plan.md +204 -0
- package/specs/013-opencode-shepherd/spec.md +258 -0
- package/specs/013-opencode-shepherd/tasks.md +263 -0
- package/src/core/artifact-sessions.ts +835 -0
- package/src/core/config.ts +329 -0
- package/src/core/discovery.ts +342 -0
- package/src/core/herdr.ts +1 -0
- package/src/core/host.ts +77 -0
- package/src/core/ids.ts +78 -0
- package/src/core/lifecycle.ts +1 -0
- package/src/core/messaging.ts +1 -0
- package/src/core/migration.ts +55 -0
- package/src/core/orchestration.ts +1 -0
- package/src/core/types.ts +143 -0
- package/src/core/unseen-completions.ts +114 -0
- package/src/extension/cli.ts +417 -0
- package/src/extension/config.ts +1 -0
- package/src/extension/settings-ui.ts +296 -0
- package/src/extension/shepherd-done.ts +768 -0
- package/src/extension/shepherd.ts +2548 -0
- package/src/extension/system-prompt.ts +38 -0
- package/src/extension/unseen-completions.ts +237 -0
- package/src/opencode/actions.ts +794 -0
- package/src/opencode/bridge.ts +777 -0
- package/src/opencode/display.ts +36 -0
- package/src/opencode/fieldnotes.ts +60 -0
- package/src/opencode/host.ts +62 -0
- package/src/opencode/orphans.ts +162 -0
- package/src/opencode/server.ts +458 -0
- package/src/runtimes/backend.ts +119 -0
- package/src/runtimes/detect.ts +102 -0
- package/src/runtimes/hc/hc.ts +527 -0
- package/src/runtimes/hc/runtime.ts +1898 -0
- package/src/runtimes/herdr/herdr.ts +912 -0
- package/src/runtimes/herdr/lifecycle.ts +1712 -0
- package/src/runtimes/herdr/messaging.ts +703 -0
- package/src/runtimes/herdr/orchestration.ts +1583 -0
- package/src/runtimes/herdr/runtime.ts +224 -0
- package/src/runtimes/runtime.ts +133 -0
- package/src/runtimes/settle-observations.ts +114 -0
- package/test/fixtures/context-project/AGENTS.md +2 -0
- package/test/fixtures/home/.agents/agents/same.md +6 -0
- package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
- package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
- package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
- package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
- package/test/fixtures/proj/.pi/agents/same.md +6 -0
- package/test/helpers/fake-clock.mjs +39 -0
- package/test/helpers/feature-contracts.mjs +44 -0
- package/test/helpers/test-utils.mjs +44 -0
- package/test/verify-artifact-sessions.mjs +258 -0
- package/test/verify-backend.mjs +297 -0
- package/test/verify-child-mislabel.mjs +135 -0
- package/test/verify-child-surface.mjs +321 -0
- package/test/verify-cli.mjs +197 -0
- package/test/verify-command-ux.mjs +100 -0
- package/test/verify-compat.mjs +32 -0
- package/test/verify-cross-host-notes.mjs +128 -0
- package/test/verify-delegate.mjs +161 -0
- package/test/verify-detect.mjs +151 -0
- package/test/verify-discovery.mjs +239 -0
- package/test/verify-done-nudge.mjs +238 -0
- package/test/verify-effective-prompt.mjs +98 -0
- package/test/verify-hc-matrix.mjs +246 -0
- package/test/verify-hc-poll.mjs +260 -0
- package/test/verify-host-docs.mjs +66 -0
- package/test/verify-host-impact.mjs +49 -0
- package/test/verify-ids.mjs +141 -0
- package/test/verify-launch.mjs +183 -0
- package/test/verify-message-routing.mjs +560 -0
- package/test/verify-messaging.mjs +303 -0
- package/test/verify-migration-notice.mjs +74 -0
- package/test/verify-multi-wait.mjs +42 -0
- package/test/verify-opencode-display.mjs +47 -0
- package/test/verify-opencode-fieldnotes.mjs +121 -0
- package/test/verify-opencode-notice.mjs +77 -0
- package/test/verify-opencode-nudge.mjs +116 -0
- package/test/verify-opencode-orphans.mjs +160 -0
- package/test/verify-opencode-surface.mjs +107 -0
- package/test/verify-packaging.mjs +82 -0
- package/test/verify-parent-surface.mjs +118 -0
- package/test/verify-phase0.mjs +95 -0
- package/test/verify-registry.mjs +124 -0
- package/test/verify-rename-migration.mjs +111 -0
- package/test/verify-rendering.mjs +379 -0
- package/test/verify-session-boundary.mjs +146 -0
- package/test/verify-settings.mjs +260 -0
- package/test/verify-stale-wait.mjs +339 -0
- package/test/verify-status-widget.mjs +377 -0
- package/test/verify-status.mjs +172 -0
- package/test/verify-task-completion.mjs +156 -0
- package/test/verify-task-failures.mjs +201 -0
- package/test/verify-task-mislabel.mjs +143 -0
- package/test/verify-task-registry.mjs +194 -0
- package/test/verify-task-watchers.mjs +217 -0
- package/test/verify-tool-schemas.mjs +120 -0
- package/test/verify-unseen-completions.mjs +1211 -0
- 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.
|