@luminascale/shepherd 0.0.0-stage → 0.6.0

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 (203) 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 +424 -2
  16. package/docs/README.md +25 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/tool-reference.md +55 -0
  20. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  21. package/docs/plans/agent-labels.md +257 -0
  22. package/docs/plans/architecture.md +110 -0
  23. package/docs/plans/settings-scope.md +163 -0
  24. package/docs/plans/tool-surface-split.md +278 -0
  25. package/docs/reference/dictionary +26 -0
  26. package/docs/releasing.md +47 -0
  27. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  37. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  38. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  39. package/index.ts +599 -0
  40. package/package.json +112 -4
  41. package/scripts/capture-system-prompt.mjs +45 -0
  42. package/scripts/extract-pi-system-prompt.mjs +277 -0
  43. package/scripts/host-impact.mjs +74 -0
  44. package/scripts/resolve-agent.mjs +43 -0
  45. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  46. package/scripts/show-shepherd-prompt.mjs +96 -0
  47. package/scripts/verify-suites.mjs +67 -0
  48. package/specs/001-artifacts/spec.md +436 -0
  49. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  50. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  51. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  52. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  53. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  54. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  55. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  56. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  57. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  58. package/specs/005-per-workspace-settings/plan.md +230 -0
  59. package/specs/005-per-workspace-settings/spec.md +368 -0
  60. package/specs/005-per-workspace-settings/tasks.md +178 -0
  61. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  62. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  63. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  64. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  65. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  66. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  67. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  68. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  69. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  70. package/specs/008-remote-machine-sheep/intent.md +174 -0
  71. package/specs/008-remote-machine-sheep/journal.md +57 -0
  72. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  73. package/specs/009-hc-runtime/intent.md +44 -0
  74. package/specs/009-hc-runtime/plan.md +49 -0
  75. package/specs/009-hc-runtime/spec.md +118 -0
  76. package/specs/009-hc-runtime/tasks.md +62 -0
  77. package/specs/010-unseen-watch-parity/intent.md +57 -0
  78. package/specs/010-unseen-watch-parity/journal.md +172 -0
  79. package/specs/010-unseen-watch-parity/plan.md +74 -0
  80. package/specs/010-unseen-watch-parity/spec.md +191 -0
  81. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  82. package/specs/011-hc-background-poll/intent.md +57 -0
  83. package/specs/011-hc-background-poll/journal.md +95 -0
  84. package/specs/011-hc-background-poll/plan.md +87 -0
  85. package/specs/011-hc-background-poll/spec.md +141 -0
  86. package/specs/011-hc-background-poll/tasks.md +83 -0
  87. package/specs/012-steer-default/intent.md +12 -0
  88. package/specs/012-steer-default/journal.md +40 -0
  89. package/specs/012-steer-default/plan.md +7 -0
  90. package/specs/012-steer-default/spec.md +42 -0
  91. package/specs/012-steer-default/tasks.md +6 -0
  92. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  93. package/specs/013-opencode-shepherd/intent.md +59 -0
  94. package/specs/013-opencode-shepherd/plan.md +204 -0
  95. package/specs/013-opencode-shepherd/spec.md +258 -0
  96. package/specs/013-opencode-shepherd/tasks.md +259 -0
  97. package/src/core/artifact-sessions.ts +835 -0
  98. package/src/core/config.ts +329 -0
  99. package/src/core/discovery.ts +342 -0
  100. package/src/core/herdr.ts +1 -0
  101. package/src/core/host.ts +77 -0
  102. package/src/core/ids.ts +78 -0
  103. package/src/core/lifecycle.ts +1 -0
  104. package/src/core/messaging.ts +1 -0
  105. package/src/core/migration.ts +55 -0
  106. package/src/core/orchestration.ts +1 -0
  107. package/src/core/types.ts +143 -0
  108. package/src/core/unseen-completions.ts +114 -0
  109. package/src/extension/cli.ts +417 -0
  110. package/src/extension/config.ts +1 -0
  111. package/src/extension/settings-ui.ts +296 -0
  112. package/src/extension/shepherd-done.ts +768 -0
  113. package/src/extension/shepherd.ts +2548 -0
  114. package/src/extension/system-prompt.ts +38 -0
  115. package/src/extension/unseen-completions.ts +237 -0
  116. package/src/opencode/actions.ts +794 -0
  117. package/src/opencode/bridge.ts +777 -0
  118. package/src/opencode/display.ts +36 -0
  119. package/src/opencode/fieldnotes.ts +60 -0
  120. package/src/opencode/host.ts +62 -0
  121. package/src/opencode/orphans.ts +162 -0
  122. package/src/opencode/server.ts +458 -0
  123. package/src/runtimes/backend.ts +119 -0
  124. package/src/runtimes/detect.ts +102 -0
  125. package/src/runtimes/hc/hc.ts +527 -0
  126. package/src/runtimes/hc/runtime.ts +1898 -0
  127. package/src/runtimes/herdr/herdr.ts +912 -0
  128. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  129. package/src/runtimes/herdr/messaging.ts +703 -0
  130. package/src/runtimes/herdr/orchestration.ts +1583 -0
  131. package/src/runtimes/herdr/runtime.ts +224 -0
  132. package/src/runtimes/runtime.ts +133 -0
  133. package/src/runtimes/settle-observations.ts +114 -0
  134. package/test/fixtures/context-project/AGENTS.md +2 -0
  135. package/test/fixtures/home/.agents/agents/same.md +6 -0
  136. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  137. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  148. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  149. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  150. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  151. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  153. package/test/helpers/fake-clock.mjs +39 -0
  154. package/test/helpers/feature-contracts.mjs +44 -0
  155. package/test/helpers/test-utils.mjs +44 -0
  156. package/test/verify-artifact-sessions.mjs +258 -0
  157. package/test/verify-backend.mjs +297 -0
  158. package/test/verify-child-mislabel.mjs +135 -0
  159. package/test/verify-child-surface.mjs +321 -0
  160. package/test/verify-cli.mjs +197 -0
  161. package/test/verify-command-ux.mjs +100 -0
  162. package/test/verify-compat.mjs +32 -0
  163. package/test/verify-cross-host-notes.mjs +128 -0
  164. package/test/verify-delegate.mjs +161 -0
  165. package/test/verify-detect.mjs +151 -0
  166. package/test/verify-discovery.mjs +239 -0
  167. package/test/verify-done-nudge.mjs +238 -0
  168. package/test/verify-effective-prompt.mjs +98 -0
  169. package/test/verify-hc-matrix.mjs +246 -0
  170. package/test/verify-hc-poll.mjs +260 -0
  171. package/test/verify-host-docs.mjs +35 -0
  172. package/test/verify-host-impact.mjs +49 -0
  173. package/test/verify-ids.mjs +141 -0
  174. package/test/verify-launch.mjs +183 -0
  175. package/test/verify-message-routing.mjs +560 -0
  176. package/test/verify-messaging.mjs +303 -0
  177. package/test/verify-migration-notice.mjs +69 -0
  178. package/test/verify-multi-wait.mjs +42 -0
  179. package/test/verify-opencode-display.mjs +47 -0
  180. package/test/verify-opencode-fieldnotes.mjs +121 -0
  181. package/test/verify-opencode-notice.mjs +77 -0
  182. package/test/verify-opencode-nudge.mjs +116 -0
  183. package/test/verify-opencode-orphans.mjs +160 -0
  184. package/test/verify-opencode-surface.mjs +107 -0
  185. package/test/verify-packaging.mjs +82 -0
  186. package/test/verify-parent-surface.mjs +118 -0
  187. package/test/verify-phase0.mjs +95 -0
  188. package/test/verify-registry.mjs +124 -0
  189. package/test/verify-rename-migration.mjs +111 -0
  190. package/test/verify-rendering.mjs +379 -0
  191. package/test/verify-session-boundary.mjs +146 -0
  192. package/test/verify-settings.mjs +260 -0
  193. package/test/verify-stale-wait.mjs +339 -0
  194. package/test/verify-status-widget.mjs +377 -0
  195. package/test/verify-status.mjs +172 -0
  196. package/test/verify-task-completion.mjs +156 -0
  197. package/test/verify-task-failures.mjs +201 -0
  198. package/test/verify-task-mislabel.mjs +143 -0
  199. package/test/verify-task-registry.mjs +194 -0
  200. package/test/verify-task-watchers.mjs +217 -0
  201. package/test/verify-tool-schemas.mjs +120 -0
  202. package/test/verify-unseen-completions.mjs +1211 -0
  203. package/test/verify-watchers.mjs +181 -0
@@ -0,0 +1,96 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Print the exact system-prompt body pi-shepherd passes for a discovered agent.
4
+ *
5
+ * Usage:
6
+ * node --experimental-strip-types scripts/show-shepherd-prompt.mjs scout
7
+ * node --experimental-strip-types scripts/show-shepherd-prompt.mjs scout --scope both --cwd /path/to/project
8
+ * node --experimental-strip-types scripts/show-shepherd-prompt.mjs scout --raw
9
+ *
10
+ * This shows Shepherd's contribution only. Pi's built-in prompt and project
11
+ * context files (AGENTS.md / CLAUDE.md) are assembled separately by pi.
12
+ */
13
+
14
+ import process from 'node:process';
15
+ import { resolve } from 'node:path';
16
+ import { discoverAgents } from '../src/core/discovery.ts';
17
+
18
+ function usage() {
19
+ console.error(`Usage: show-shepherd-prompt <agent> [options]
20
+
21
+ Options:
22
+ --cwd <path> Cwd used for agent discovery (default: current directory)
23
+ --scope <scope> user, project, or both (default: user)
24
+ --omit Force replacement mode (--system-prompt)
25
+ --append Force append mode (--append-system-prompt)
26
+ --raw Print only the agent prompt body
27
+ --help Show this help
28
+ `);
29
+ process.exit(2);
30
+ }
31
+
32
+ const args = process.argv.slice(2);
33
+ let agentName;
34
+ let cwd = process.cwd();
35
+ let scope = 'user';
36
+ let omit;
37
+ let raw = false;
38
+
39
+ for (let i = 0; i < args.length; i++) {
40
+ const arg = args[i];
41
+ if (arg === '--help' || arg === '-h') usage();
42
+ if (arg === '--raw') {
43
+ raw = true;
44
+ continue;
45
+ }
46
+ if (arg === '--omit' || arg === '--append') {
47
+ if (omit !== undefined) usage();
48
+ omit = arg === '--omit';
49
+ continue;
50
+ }
51
+ if (arg === '--cwd') {
52
+ cwd = args[++i];
53
+ if (!cwd) usage();
54
+ continue;
55
+ }
56
+ if (arg === '--scope') {
57
+ scope = args[++i];
58
+ if (!scope) usage();
59
+ continue;
60
+ }
61
+ if (arg.startsWith('--')) usage();
62
+ if (agentName) usage();
63
+ agentName = arg;
64
+ }
65
+
66
+ if (!agentName || !['user', 'project', 'both'].includes(scope)) usage();
67
+ cwd = resolve(cwd);
68
+
69
+ const { agents, projectDirs } = discoverAgents(cwd, scope);
70
+ const agent = agents.find(candidate => candidate.name === agentName);
71
+ if (!agent) {
72
+ console.error(`Agent not found: ${agentName}`);
73
+ console.error(
74
+ `Available agents: ${agents.map(candidate => candidate.name).join(', ') || 'none'}`
75
+ );
76
+ if (projectDirs.length > 0) console.error(`Project agent dirs: ${projectDirs.join(', ')}`);
77
+ process.exit(1);
78
+ }
79
+
80
+ if (raw) {
81
+ process.stdout.write(agent.systemPrompt);
82
+ if (!agent.systemPrompt.endsWith('\n')) process.stdout.write('\n');
83
+ process.exit(0);
84
+ }
85
+
86
+ const effectiveOmit = omit ?? agent.omitSystemPrompt ?? false;
87
+ const mode = effectiveOmit ? 'replacement (--system-prompt)' : 'append (--append-system-prompt)';
88
+ console.log(`Agent: ${agent.name}`);
89
+ console.log(`Source: ${agent.source}`);
90
+ console.log(`Definition: ${agent.filePath}`);
91
+ console.log(`Discovery cwd: ${cwd}`);
92
+ console.log(`Scope: ${scope}`);
93
+ console.log(`Launch mode: ${mode}`);
94
+ console.log('\n=== Shepherd system-prompt contribution ===\n');
95
+ process.stdout.write(agent.systemPrompt);
96
+ if (!agent.systemPrompt.endsWith('\n')) process.stdout.write('\n');
@@ -0,0 +1,67 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Mirrored verification harnesses (T016).
4
+ *
5
+ * Partitions the `*:test` scripts into the Pi-side and OpenCode-side suites
6
+ * and runs one suite in fresh child processes. `npm test` chains both, so a
7
+ * change on either side gates the whole package. The lists are derived from
8
+ * package.json, so a new test script cannot silently escape both suites.
9
+ */
10
+ import fs from 'node:fs';
11
+ import path from 'node:path';
12
+ import { spawnSync } from 'node:child_process';
13
+
14
+ const repo = path.resolve(import.meta.dirname, '..');
15
+ const pkg = JSON.parse(fs.readFileSync(path.join(repo, 'package.json'), 'utf8'));
16
+
17
+ const OPENCODE_SUITE = new Set([
18
+ 'opencode-display:test',
19
+ 'opencode-notice:test',
20
+ 'opencode-nudge:test',
21
+ 'opencode-fieldnotes:test',
22
+ 'opencode-surface:test',
23
+ 'cross-host-notes:test',
24
+ 'packaging:test',
25
+ 'host-docs:test',
26
+ 'host-impact:test',
27
+ 'migration-notice:test',
28
+ 'rename-migration:test',
29
+ 'opencode-orphans:test',
30
+ ]);
31
+
32
+ const suite = process.argv[2];
33
+ if (suite !== 'pi' && suite !== 'opencode') {
34
+ console.error('usage: node scripts/verify-suites.mjs <pi|opencode>');
35
+ process.exit(2);
36
+ }
37
+ const names = Object.keys(pkg.scripts)
38
+ .filter(
39
+ name =>
40
+ name.endsWith(':test') &&
41
+ name !== 'smoke:poll' &&
42
+ name !== 'pi-suite:test' &&
43
+ name !== 'opencode-suite:test'
44
+ )
45
+ .filter(name => OPENCODE_SUITE.has(name) === (suite === 'opencode'));
46
+
47
+ if (names.length === 0) {
48
+ console.error(`no tests found for the ${suite} suite`);
49
+ process.exit(2);
50
+ }
51
+ console.log(`== ${suite} suite: ${names.length} test scripts ==`);
52
+ const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('npm_config_')));
53
+ const failed = [];
54
+ for (const name of names) {
55
+ const result = spawnSync(pkg.scripts[name], {
56
+ shell: true,
57
+ cwd: repo,
58
+ stdio: 'inherit',
59
+ env,
60
+ });
61
+ if (result.status !== 0) failed.push(name);
62
+ }
63
+ if (failed.length) {
64
+ console.error(`\n${suite} suite FAILED: ${failed.join(', ')}`);
65
+ process.exit(1);
66
+ }
67
+ console.log(`\n${suite} suite OK (${names.length} scripts)`);
@@ -0,0 +1,436 @@
1
+ # Note-backed Shepherd Sessions
2
+
3
+ ## Status
4
+
5
+ Proposed specification.
6
+
7
+ ## Summary
8
+
9
+ A Shepherd delegation workflow is backed by a durable, human-readable session
10
+ folder under the project being worked on. The session contains a `shepherd.md`
11
+ file acting as a map of content (fieldnotes) and one note per delegated agent
12
+ invocation. A session may span multiple `shepherd` tool calls. Reusing the same
13
+ session name continues the existing session rather than creating a new one.
14
+
15
+ There is intentionally **no global or project-level `shepherd.md` index file**.
16
+ The session's own `shepherd.md` is the only Shepherd fieldnotes index.
17
+
18
+ ## Goals
19
+
20
+ - Create a durable session automatically for delegated work.
21
+ - Use meaningful, stable session names and monotonically allocated numbers.
22
+ - Allow a session to span multiple single, parallel, and chain delegation calls.
23
+ - Let a later delegation call consume and extend notes from earlier calls.
24
+ - Give every agent a unique note path and enough session context to navigate
25
+ the work.
26
+ - Keep the session fieldnotes readable and useful to both agents and humans.
27
+ - Support Markdown links between notes and to files, URLs, and other project
28
+ resources.
29
+ - Preserve safe behavior when multiple agents run in parallel or multiple
30
+ Shepherd calls happen close together.
31
+ - Remain backwards compatible for callers that do not provide a session name.
32
+
33
+ ## Non-goals
34
+
35
+ - No global `.shepherd/shepherd.md` index.
36
+ - No requirement that agents edit the session fieldnotes directly.
37
+ - No generic shared writable scratch file for parallel agents.
38
+ - No second LLM call solely to generate a session name.
39
+ - No attempt to make Markdown itself a transactional database.
40
+ - No automatic commit, checkout, or cleanup of session notes.
41
+
42
+ ## Directory layout
43
+
44
+ For a project rooted at `<project>`:
45
+
46
+ ```text
47
+ <project>/.shepherd/
48
+ └── sessions/
49
+ └── 0001-fix-oauth-login/
50
+ ├── shepherd.md
51
+ ├── session.json
52
+ ├── scout-01.md
53
+ ├── scout-02.md
54
+ ├── planner-01.md
55
+ ├── worker-01.md
56
+ └── reviewer-01.md
57
+ ```
58
+
59
+ Only the session directory is created automatically. `.shepherd/` must not
60
+ contain a top-level `shepherd.md` index.
61
+
62
+ The numbered directory name consists of:
63
+
64
+ ```text
65
+ NNNN-<slug>
66
+ ```
67
+
68
+ `NNNN` is a zero-padded decimal sequence scoped to the project's
69
+ `.shepherd/sessions/` directory. `<slug>` is a deterministic, filesystem-safe
70
+ lowercase name.
71
+
72
+ ## Session identity and continuation
73
+
74
+ ### Session name
75
+
76
+ Delegation accepts an optional session name, exposed as `sessionName` in the
77
+ Shepherd tool API. The name is both:
78
+
79
+ 1. the human-facing identity used to find or create a session; and
80
+ 2. the source for the directory slug when a new session is created.
81
+
82
+ The caller should use a stable, descriptive name such as
83
+ `fix-oauth-login`, not a transient task description.
84
+
85
+ ### Create or continue
86
+
87
+ For a given project root and session name:
88
+
89
+ - If a matching session exists, continue that session.
90
+ - If no matching session exists, create a new numbered session directory.
91
+ - A new `shepherd` tool call with the same `sessionName` appends new work to the
92
+ existing session, regardless of whether the previous call was single,
93
+ parallel, or chain mode.
94
+ - The session remains usable after completion, failure, timeout, cancellation,
95
+ or a pi restart.
96
+
97
+ The implementation must not identify a session by slug alone if that could
98
+ permit an unsafe path. It should resolve the requested name through validated
99
+ metadata (`session.json`) and/or an exact safe directory match under the
100
+ current project's sessions directory.
101
+
102
+ The project root is the effective delegation `cwd` (normally the parent
103
+ session's `ctx.cwd`). A session name is not allowed to escape that root.
104
+
105
+ ### Missing name
106
+
107
+ For backwards compatibility, a call without `sessionName` still works. It
108
+ creates a new session using a deterministic slug derived from the first task,
109
+ for example `fix-oauth-login` or `delegation`. The returned result must include
110
+ the resolved session path and name so a later call can explicitly continue it.
111
+
112
+ If a workflow needs to span calls, the shepherd should pass the same
113
+ `sessionName` on every call. An optional future `sessionId` can be added if a
114
+ stable opaque identifier becomes necessary, but it is not required for this
115
+ specification.
116
+
117
+ ### Name collision and numbering
118
+
119
+ Two different names may produce the same slug. Slug collisions must not merge
120
+ sessions. The allocator must resolve this deterministically, for example by
121
+ adding a short safe suffix, while preserving exact continuation for the
122
+ original name through `session.json`.
123
+
124
+ Number allocation must be safe under concurrent callers. A scan-for-highest
125
+ followed by mkdir is not sufficient. Use an exclusive filesystem operation
126
+ (or an equivalent retry loop) so two processes cannot claim the same number.
127
+ A failed or abandoned allocation must not be reused within the normal
128
+ allocation sequence.
129
+
130
+ ## Session fieldnotes: `shepherd.md`
131
+
132
+ Each session has one fieldnotes collection at:
133
+
134
+ ```text
135
+ .shepherd/sessions/NNNN-name/shepherd.md
136
+ ```
137
+
138
+ The shepherd owns this file. Agents may read it but should not update it.
139
+ fieldnotes writes must be serialized and performed atomically (write a temporary file
140
+ in the same directory, then rename it).
141
+
142
+ Minimum content:
143
+
144
+ ```markdown
145
+ # Session 0001 — Fix OAuth Login
146
+
147
+ - **Status:** running
148
+ - **Session name:** `fix-oauth-login`
149
+ - **Started:** 2025-08-14T09:30:00Z
150
+ - **Updated:** 2025-08-14T09:32:00Z
151
+ - **Project:** `.`
152
+ - **Mode(s):** chain, parallel
153
+
154
+ ## Notes
155
+
156
+ 1. [Scout 01](./scout-01.md) — completed
157
+ 2. [Planner 01](./planner-01.md) — running
158
+ 3. [Worker 01](./worker-01.md) — pending
159
+
160
+ ## Flow
161
+
162
+ ```text
163
+ [scout-01](./scout-01.md) → [planner-01](./planner-01.md) → [worker-01](./worker-01.md)
164
+ ```
165
+
166
+ ## Related files
167
+
168
+ - [Authentication service](../../src/auth/service.ts)
169
+ - [Issue](https://example.com/issues/123)
170
+ ```
171
+
172
+ The exact presentation may evolve, but links should be relative whenever the
173
+ link target is inside the session or project. External URLs remain ordinary
174
+ Markdown links.
175
+
176
+ The fieldnotes should be updated when:
177
+
178
+ - the session is created;
179
+ - a delegation invocation is registered;
180
+ - a note is reserved;
181
+ - an agent starts, completes, fails, times out, or is cancelled; and
182
+ - the session reaches a terminal state, when that can be determined.
183
+
184
+ A session spanning multiple tool calls should retain previous notes and
185
+ append new entries rather than rewriting history away.
186
+
187
+ ## Notes
188
+
189
+ Every delegated agent invocation receives one unique note file in the
190
+ session root:
191
+
192
+ ```text
193
+ <agent-name>-NN.md
194
+ ```
195
+
196
+ Examples:
197
+
198
+ ```text
199
+ scout-01.md
200
+ scout-02.md
201
+ planner-01.md
202
+ ```
203
+
204
+ The ordinal is per agent name within the session and is never reused. If an
205
+ agent name contains unsafe or awkward characters, derive a safe slug for the
206
+ filename. If two note names still collide, add a deterministic suffix.
207
+
208
+ Notes should be reserved before their agent starts, especially in
209
+ parallel and chain workflows, so the path is stable regardless of completion
210
+ order.
211
+
212
+ Each note should contain enough metadata to identify its provenance:
213
+
214
+ ```markdown
215
+ ---
216
+ session: 0001-fix-oauth-login
217
+ sessionName: fix-oauth-login
218
+ agent: scout
219
+ ordinal: 1
220
+ mode: chain
221
+ status: completed
222
+ started: 2025-08-14T09:30:00Z
223
+ completed: 2025-08-14T09:32:00Z
224
+ pane: w8:pY
225
+ ---
226
+
227
+ # Scout 01
228
+
229
+ <!-- Agent output or agent-maintained report follows. -->
230
+
231
+ ...
232
+ ```
233
+
234
+ The final output, failure details, and relevant lifecycle information must be
235
+ preserved in the note even if an agent does not write its own report.
236
+
237
+ ## Agent context and ownership
238
+
239
+ The child task must include a session context block containing:
240
+
241
+ - absolute session directory;
242
+ - relative session directory from the project root;
243
+ - absolute path to `shepherd.md`;
244
+ - absolute path to the child's note;
245
+ - relative path to the child's note;
246
+ - instruction to read the fieldnotes before working;
247
+ - instruction to write detailed findings to the child's note when its role
248
+ permits writing; and
249
+ - instruction not to edit the fieldnotes or another agent's note.
250
+
251
+ Example:
252
+
253
+ ```text
254
+ Shepherd session context:
255
+ - Session: 0001-fix-oauth-login
256
+ - Session directory: /repo/.shepherd/sessions/0001-fix-oauth-login
257
+ - Session fieldnotes: /repo/.shepherd/sessions/0001-fix-oauth-login/shepherd.md
258
+ - Your note: /repo/.shepherd/sessions/0001-fix-oauth-login/scout-01.md
259
+
260
+ Read shepherd.md first. Keep your work in your assigned note. Do not edit
261
+ shepherd.md or another agent's note. Use relative Markdown links for files
262
+ inside the project or session.
263
+ ```
264
+
265
+ The context must be added without accidentally replacing the delegated task or
266
+ agent system prompt.
267
+
268
+ ### Note writing strategy
269
+
270
+ The first implementation should guarantee note persistence from the
271
+ shepherd:
272
+
273
+ 1. reserve and initialize the note before launch;
274
+ 2. run the agent;
275
+ 3. after a safe terminal result, write the final assistant output and lifecycle
276
+ metadata to the note;
277
+ 4. update the fieldnotes.
278
+
279
+ Read-only agents such as the bundled scout and planner therefore still produce
280
+ notes. They do not need generic write access merely to satisfy the
281
+ note contract.
282
+
283
+ A later implementation may add a restricted child-side note tool, but
284
+ prompt-level instructions are not a security boundary. If introduced, it must
285
+ only permit writes to the assigned note path.
286
+
287
+ If an agent writes its own note, the shepherd must define whether that
288
+ content is authoritative. The recommended rule is: preserve agent-authored
289
+ content, then add/update a clearly marked shepherd metadata and output
290
+ section rather than silently overwriting it.
291
+
292
+ ## Cross-call orchestration
293
+
294
+ A later call using the same session name should receive a concise context block
295
+ and be instructed to inspect the existing fieldnotes and relevant notes. The
296
+ shepherd may also include selected prior output in `{previous}` for chain
297
+ compatibility, but notes are the durable source of truth and should be
298
+ preferred for large reports.
299
+
300
+ Example sequence:
301
+
302
+ ```text
303
+ Call 1:
304
+ sessionName: fix-oauth-login
305
+ chain: scout → planner
306
+
307
+ Call 2:
308
+ sessionName: fix-oauth-login
309
+ agent: worker
310
+ task: Read the session fieldnotes and implement the approved plan.
311
+
312
+ Call 3:
313
+ sessionName: fix-oauth-login
314
+ agent: reviewer
315
+ task: Review the implementation using the session notes and current diff.
316
+ ```
317
+
318
+ The fieldnotes after these calls links all five notes in one session.
319
+
320
+ ## Lifecycle and Herdr safety
321
+
322
+ Note-backed delegation uses `stayOpen: false` by default. This is the
323
+ simplest and safest lifecycle: the child exits after completion, the Herdr
324
+ sentinel confirms that it has stopped writing, and only then does the parent
325
+ parse the child session and finalize the note.
326
+
327
+ `keepOpen` remains independent. With the default combination
328
+ `stayOpen: false, keepOpen: true`, the pi process exits but the Herdr tab remains
329
+ available for inspection. A caller may explicitly request `stayOpen: true` when
330
+ interactive follow-up is more important than immediate note finalization.
331
+
332
+ The current Herdr runner may keep child pi alive when `stayOpen` is enabled.
333
+ Note finalization must not read or delete a child session JSONL file while
334
+ that child can still write it.
335
+
336
+ Therefore:
337
+
338
+ - durable note metadata may be updated while the child is running, but
339
+ final child output must be captured only after a safe completion boundary;
340
+ - with the default `stayOpen: false`, wait for the process-exit sentinel before
341
+ parsing the child session and finalizing output;
342
+ - with explicit `stayOpen: true`, either use a completion snapshot guaranteed to
343
+ be immutable after signaling, or defer finalization until the child exits;
344
+ - timeout and abort paths must leave the session and note marked as such,
345
+ without deleting files still owned by a live child;
346
+ - a later call may continue a session containing timed-out or abandoned
347
+ notes.
348
+
349
+ This preserves the invariant that nothing reads a child session before the
350
+ child has exited.
351
+
352
+ ## API proposal
353
+
354
+ Add an optional parameter to delegation:
355
+
356
+ ```ts
357
+ sessionName?: string
358
+ ```
359
+
360
+ The parameter is available on:
361
+
362
+ - `shepherd` action `delegate`;
363
+ - single delegation;
364
+ - parallel delegation; and
365
+ - chain delegation.
366
+
367
+ For note-backed delegation, `stayOpen` defaults to `false`. The public
368
+ `keepOpen` option still defaults to `true`, so completed tabs remain visible
369
+ without leaving child pi processes alive. Explicit caller options continue to
370
+ win over defaults.
371
+
372
+ The result should report at least:
373
+
374
+ ```ts
375
+ {
376
+ sessionName: string;
377
+ sessionPath: string;
378
+ sessionRelativePath: string;
379
+ }
380
+ ```
381
+
382
+ The internal session context should be passed through `executeDelegation` and
383
+ `runSingleAgent` without exposing filesystem implementation details to the
384
+ agent discovery module.
385
+
386
+ A future extension may add:
387
+
388
+ ```ts
389
+ sessionId?: string
390
+ ```
391
+
392
+ but same-name continuation is the required behavior for the initial version.
393
+
394
+ ## Implementation outline
395
+
396
+ 1. Add a pure filesystem-oriented `sessions.ts` module.
397
+ 2. Implement safe name normalization, exact session lookup, atomic numbered
398
+ allocation, note reservation, and atomic fieldnotes/metadata writes.
399
+ 3. Make `stayOpen: false` the default for note-backed delegation while
400
+ keeping `keepOpen: true` as the default tab-inspection behavior.
401
+ 4. Add `sessionName` to `types.ts` and the public `shepherd` schema.
402
+ 5. Create or resolve the session at the beginning of `executeDelegation`, after
403
+ parameter validation and project-agent confirmation where appropriate.
404
+ 6. Reserve one note per planned invocation and add session context to each
405
+ child task.
406
+ 7. Update `runSingleAgent` and all single/parallel/chain paths to finalize
407
+ notes and fieldnotes entries.
408
+ 8. Preserve `{previous}` behavior for compatibility, while directing agents to
409
+ use session notes for durable context.
410
+ 9. Add filesystem-only verification covering:
411
+ - safe slugging and traversal rejection;
412
+ - same-name continuation;
413
+ - different-name collision handling;
414
+ - concurrent numbering;
415
+ - per-agent ordinals and duplicate agent names;
416
+ - relative links in the fieldnotes;
417
+ - chain and parallel registration;
418
+ - success, failure, timeout, and cancellation metadata; and
419
+ - atomic write behavior.
420
+ 10. Document the layout, continuation rule, no-global-index decision, and
421
+ lifecycle defaults in `README.md` and `PLAN.md`.
422
+
423
+ ## Risks and decisions to revisit
424
+
425
+ - If two independent callers intentionally use the same session name in one
426
+ project, they will share a session by design. Users should choose names that
427
+ represent one workstream.
428
+ - A session name reused for unrelated future work will append to old history.
429
+ The UI/result should show that an existing session was resumed.
430
+ - Agent-authored Markdown and shepherd metadata need a clear merge policy.
431
+ - `.shepherd/` version-control policy should remain an explicit project choice;
432
+ the extension should not silently add it to `.gitignore`.
433
+ - Absolute paths in `session.json` are useful locally but should be minimized or
434
+ accompanied by project-relative paths if notes are committed.
435
+ - Session fieldnotes updates from parallel completions require serialization to avoid
436
+ lost updates.