@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,246 @@
1
+ #!/usr/bin/env node
2
+ // Phase 2 backend matrix (spec 009): the same prompts behave the same on
3
+ // both runtimes, raw native ids are refused as handles on both, and closing
4
+ // what we did not create is refused before any kill primitive runs.
5
+ // Phase 2 additions: non-blocking hc watchers reject like blocking watch,
6
+ // the hc status view + read-target resolution refuse raw ids, the stale
7
+ // monitor stays quiet with no waiting tasks, the timeout->blocked copy
8
+ // matches the pane backend byte-for-byte, and the fieldnotes bridge shares
9
+ // one `.shepherd/sessions` dir (temp project root, no live agent).
10
+ //
11
+ // No live spawn: every path below rejects (or proves ownership mechanics)
12
+ // before any agent boots, so this stays deterministic with or without a
13
+ // `herdr` binary. The hc ownership-primitive block runs only when `hc` is
14
+ // reachable and cleans up after itself. Live spawn/delegate/watch parity was
15
+ // proven manually in 1.1; the resolver wiring it exercises lives in
16
+ // src/extension/shepherd.ts (delegate/close routed, rest concrete).
17
+ // Cross-link (010 Phase 2): unwatched-notice parity (same-prompts,
18
+ // no-id-leak, race, close) lives in test/verify-unseen-completions.mjs;
19
+ // this suite keeps the ownership/id-refusal cases both suites rely on.
20
+ import { currentParentBroker, shutdownParentBroker } from '../src/runtimes/herdr/lifecycle.ts';
21
+ import { createHerdrRuntime } from '../src/runtimes/herdr/runtime.ts';
22
+ import {
23
+ describeHcStatusView,
24
+ hcStaleWaitMonitor,
25
+ isHcTaskId,
26
+ resolveHcAgentId,
27
+ watchHcTasks,
28
+ } from '../src/runtimes/hc/runtime.ts';
29
+ import {
30
+ isHcAvailable,
31
+ loadCreatedTerminals,
32
+ pruneStaleCreatedTerminals,
33
+ recordCreatedTerminal,
34
+ terminalExists,
35
+ } from '../src/runtimes/hc/hc.ts';
36
+ import { createHcRuntime } from '../src/runtimes/hc/runtime.ts';
37
+
38
+ let failures = 0;
39
+ function assert(ok, label) {
40
+ if (ok) console.log(`PASS ${label}`);
41
+ else {
42
+ failures++;
43
+ console.log(`FAIL ${label}`);
44
+ }
45
+ }
46
+
47
+ function codeOf(error) {
48
+ return error && typeof error.code === 'string' ? error.code : undefined;
49
+ }
50
+
51
+ async function rejectsWithCode(fn, code, label) {
52
+ try {
53
+ await fn();
54
+ } catch (error) {
55
+ assert(codeOf(error) === code, `${label} (code=${codeOf(error) ?? error?.name})`);
56
+ return;
57
+ }
58
+ assert(false, `${label} (no throw)`);
59
+ }
60
+
61
+ // A broker-capable owner identity so parent-message paths reach handle
62
+ // validation instead of failing on session resolution.
63
+ const previousOwner = process.env.PI_SHEPHERD_OWNER_SESSION;
64
+ process.env.PI_SHEPHERD_OWNER_SESSION = 'hc-matrix-test';
65
+
66
+ const herdr = createHerdrRuntime({ cwd: process.cwd() });
67
+ const hc = createHcRuntime({ cwd: process.cwd() });
68
+
69
+ try {
70
+ // ── surface: both runtimes implement the 7-method contract ──────────────
71
+ for (const method of ['spawn', 'delegate', 'message', 'watch', 'status', 'close', 'read']) {
72
+ assert(typeof herdr[method] === 'function', `pane runtime implements ${method}`);
73
+ assert(typeof hc[method] === 'function', `hc runtime implements ${method}`);
74
+ }
75
+
76
+ // ── same unknown agent name on spawn: identical discovery failure ───────
77
+ for (const [name, rt] of [['pane', herdr], ['hc', hc]]) {
78
+ try {
79
+ await rt.spawn({ name: 'no-such-agent-xyz' }, {});
80
+ assert(false, `${name} spawn unknown agent throws`);
81
+ } catch (error) {
82
+ assert(/Unknown agent/.test(String(error?.message)), `${name} spawn unknown agent throws Unknown agent`);
83
+ }
84
+ }
85
+
86
+ // ── opaque-ID refusal: raw native ids are junk on BOTH backends ─────────
87
+ // 't4' is an hc terminal address; 'w1:p1' is a pane id. Neither is ever a
88
+ // valid opaque handle, on either runtime.
89
+ for (const raw of ['t4', 'w1:p1']) {
90
+ await rejectsWithCode(() => herdr.delegate(raw, 'x', {}), 'unknown_handle', `pane delegate(${raw}) refused`);
91
+ await rejectsWithCode(() => hc.delegate(raw, 'x', {}), 'unknown_handle', `hc delegate(${raw}) refused`);
92
+ await rejectsWithCode(() => herdr.message(raw, 'hi', {}), 'invalid_target', `pane message(${raw}) refused`);
93
+ await rejectsWithCode(() => hc.message(raw, 'hi', {}), 'invalid_target', `hc message(${raw}) refused`);
94
+ await rejectsWithCode(() => herdr.status(raw), 'unknown_handle', `pane status(${raw}) refused`);
95
+ await rejectsWithCode(() => hc.status(raw), 'unknown_handle', `hc status(${raw}) refused`);
96
+ await rejectsWithCode(() => herdr.read(raw), 'unknown_handle', `pane read(${raw}) refused`);
97
+ await rejectsWithCode(() => hc.read(raw), 'unknown_handle', `hc read(${raw}) refused`);
98
+ await rejectsWithCode(() => herdr.close(raw), 'unknown_handle', `pane close(${raw}) refused`);
99
+ await rejectsWithCode(() => hc.close(raw), 'unknown_handle', `hc close(${raw}) refused`);
100
+ }
101
+
102
+ // ── unknown opaque ids: same codes both sides ───────────────────────────
103
+ const ghostAgent = 'shepherd-agent-00000000-00000000-0000-4000-8000-000000000000';
104
+ const ghostTask = 'shepherd-task-00000000-00000000-0000-4000-8000-000000000000';
105
+ for (const [name, rt] of [['pane', herdr], ['hc', hc]]) {
106
+ await rejectsWithCode(() => rt.delegate(ghostAgent, 'x', {}), 'unknown_handle', `${name} delegate unknown agent`);
107
+ await rejectsWithCode(() => rt.status(ghostAgent), 'unknown_handle', `${name} status unknown agent`);
108
+ await rejectsWithCode(() => rt.read(ghostAgent), 'unknown_handle', `${name} read unknown agent`);
109
+ await rejectsWithCode(() => rt.close(ghostAgent), 'unknown_handle', `${name} close unknown agent`);
110
+ await rejectsWithCode(() => rt.watch([ghostTask]), 'unknown_task', `${name} watch unknown task`);
111
+ }
112
+
113
+ // ── watch shape: empty and duplicate lists rejected identically ─────────
114
+ for (const [name, rt] of [['pane', herdr], ['hc', hc]]) {
115
+ await rejectsWithCode(() => rt.watch([]), 'invalid_handle', `${name} watch([]) rejected`);
116
+ // Resolution precedes dedup on both runtimes, so duplicate unknown ids
117
+ // surface unknown_task identically (same order, same outcome).
118
+ await rejectsWithCode(
119
+ () => rt.watch([ghostTask, ghostTask]),
120
+ 'unknown_task',
121
+ `${name} watch duplicate-unknown rejected`
122
+ );
123
+ }
124
+
125
+ // ── ownership refusal: close never reaches kill for unowned terminals ───
126
+ // Recording a bogus terminal address proves the registry mechanics; the
127
+ // close still refuses at handle lookup, before any `hc kill` could run.
128
+ if (isHcAvailable()) {
129
+ recordCreatedTerminal({ terminalId: 't4', name: 'matrix-bogus', cwd: '/tmp', createdAt: Date.now() });
130
+ assert(
131
+ loadCreatedTerminals().some(t => t.terminalId === 't4'),
132
+ 'hc registry records the bogus terminal'
133
+ );
134
+ await rejectsWithCode(() => hc.close('t4'), 'unknown_handle', 'hc close(t4) refused before kill');
135
+ assert(!terminalExists('t4'), 'bogus terminal does not exist');
136
+ const pruned = pruneStaleCreatedTerminals();
137
+ assert(pruned >= 1, `hc prune drops the bogus entry (pruned=${pruned})`);
138
+ assert(
139
+ !loadCreatedTerminals().some(t => t.terminalId === 't4'),
140
+ 'bogus terminal forgotten after prune'
141
+ );
142
+ } else {
143
+ console.log('INFO hc unreachable: ownership-primitive block skipped');
144
+ }
145
+ await rejectsWithCode(() => herdr.close('w1:p1'), 'unknown_handle', 'pane close(w1:p1) refused before pane close');
146
+
147
+ // ── Phase 2 parity: non-blocking hc watchers reject like blocking watch ──
148
+ await rejectsWithCode(() => watchHcTasks([]), 'invalid_handle', 'hc watchHcTasks([]) rejected');
149
+ await rejectsWithCode(
150
+ () => watchHcTasks([ghostTask, ghostTask]),
151
+ 'unknown_task',
152
+ 'hc watchHcTasks duplicate-unknown rejected as unknown_task'
153
+ );
154
+ await rejectsWithCode(
155
+ () => watchHcTasks([ghostTask]),
156
+ 'unknown_task',
157
+ 'hc watchHcTasks unknown task rejected'
158
+ );
159
+ assert(!isHcTaskId(ghostTask), 'isHcTaskId false for unknown task');
160
+ assert(!isHcTaskId('t4'), 'isHcTaskId false for raw terminal address');
161
+ assert(!isHcTaskId('w1:p1'), 'isHcTaskId false for raw pane id');
162
+
163
+ // ── Phase 2 parity: status view + read-target resolution refuse raw ids ──
164
+ await rejectsWithCode(
165
+ async () => describeHcStatusView(ghostAgent),
166
+ 'unknown_handle',
167
+ 'describeHcStatusView unknown agent refused'
168
+ );
169
+ assert(resolveHcAgentId('t4') === undefined, 'resolveHcAgentId never resolves a raw terminal address');
170
+ assert(resolveHcAgentId('w1:p1') === undefined, 'resolveHcAgentId never resolves a raw pane id');
171
+ assert(resolveHcAgentId(ghostAgent) === undefined, 'resolveHcAgentId undefined for unknown agent');
172
+
173
+ // ── Phase 2 parity: stale monitor is information-only and idle-safe ─────
174
+ // With no waiting tasks the poll resolves quietly and never notifies.
175
+ let staleNotified = 0;
176
+ hcStaleWaitMonitor.setNotifier(() => {
177
+ staleNotified++;
178
+ });
179
+ await hcStaleWaitMonitor.poll();
180
+ assert(staleNotified === 0, 'stale monitor quiet with no waiting tasks');
181
+ hcStaleWaitMonitor.setNotifier(undefined);
182
+ hcStaleWaitMonitor.shutdown();
183
+
184
+ // ── Phase 2 parity: timeout->blocked copy matches the pane backend ──────
185
+ // Both backends settle an unanswered tracked reply as `blocked` with the
186
+ // same human-readable copy (returnCode 2); the hc path builds it in
187
+ // `settleDueReplyTimeouts` + `watch`, the pane path in
188
+ // `processParentBrokerMessages`. Assert the shared prefix byte-for-byte.
189
+ {
190
+ const fs = await import('node:fs');
191
+ const hcSource = fs.readFileSync(new URL('../src/runtimes/hc/runtime.ts', import.meta.url), 'utf8');
192
+ const paneSource = fs.readFileSync(
193
+ new URL('../src/runtimes/herdr/lifecycle.ts', import.meta.url),
194
+ 'utf8'
195
+ );
196
+ const snippet = 'Timed out waiting for a reply from';
197
+ assert(hcSource.includes(snippet), 'hc runtime carries the blocked-reply copy');
198
+ assert(paneSource.includes(snippet), 'pane runtime carries the blocked-reply copy');
199
+ assert(
200
+ hcSource.includes('(message') && hcSource.includes('never answered).'),
201
+ 'hc blocked copy names the unanswered message'
202
+ );
203
+ }
204
+
205
+ // ── Phase 2 parity: fieldnotes bridge shares one sessions dir ────────────
206
+ // Both runtimes persist through `src/core/artifact-sessions.ts`, rooted at
207
+ // `<projectRoot>/.shepherd/sessions`. Prove the bridge once here (temp
208
+ // project root, no live agent): reserve -> start -> finalize lands a
209
+ // completed note under the shared directory.
210
+ {
211
+ const fs = await import('node:fs');
212
+ const os = await import('node:os');
213
+ const path = await import('node:path');
214
+ const sessions = await import('../src/core/artifact-sessions.ts');
215
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'hc-matrix-fieldnotes-'));
216
+ try {
217
+ const session = sessions.resolveOrCreateParentArtifactSession({
218
+ parentPiSessionId: 'hc-matrix-test',
219
+ projectRoot: tmp,
220
+ });
221
+ const [artifact] = sessions.reserveArtifacts(session, [
222
+ { agent: 'worker', mode: 'single', task: 'matrix probe' },
223
+ ]);
224
+ sessions.markArtifactStarted(session, artifact, { taskId: 't-probe', agentId: 'a-probe' });
225
+ sessions.finalizeArtifact(session, artifact, { status: 'completed', output: 'ok' });
226
+ const dir = path.join(tmp, '.shepherd', 'sessions');
227
+ assert(fs.existsSync(dir), 'fieldnotes sessions dir exists under project root');
228
+ assert(fs.existsSync(artifact.filePath), 'finalized artifact file exists');
229
+ const moc = fs.readFileSync(session.mocPath, 'utf8');
230
+ assert(moc.includes('completed'), 'fieldnotes index records the completed note');
231
+ } finally {
232
+ fs.rmSync(tmp, { recursive: true, force: true });
233
+ }
234
+ }
235
+ } finally {
236
+ if (previousOwner === undefined) delete process.env.PI_SHEPHERD_OWNER_SESSION;
237
+ else process.env.PI_SHEPHERD_OWNER_SESSION = previousOwner;
238
+ try {
239
+ if (currentParentBroker()) shutdownParentBroker(() => true);
240
+ } catch {
241
+ /* best effort mailbox cleanup */
242
+ }
243
+ }
244
+
245
+ if (failures) process.exit(1);
246
+ console.log('All hc-matrix assertions passed.');
@@ -0,0 +1,260 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Spec 011 verification: hc background inbox poll (+ drain-first reads).
4
+ *
5
+ * No live spawn, no wall-clock waits: the poller is driven through its
6
+ * exported seam (register/start/stop/synchronous tick), and the pump path
7
+ * is proven with real broker stores on disk (like the messaging suite) —
8
+ * a queued `task_done` for an unknown task is consumed from the inbox and
9
+ * observably dropped, which exercises the full tick → poll → apply
10
+ * pipeline. Settlement itself stays covered by 010's suites.
11
+ */
12
+ import assert from 'node:assert/strict';
13
+ import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
14
+ import { tmpdir } from 'node:os';
15
+ import * as path from 'node:path';
16
+ import {
17
+ describeHcStatusView,
18
+ drainHcInboxForSession,
19
+ hcInjectTestAgent,
20
+ hcInjectTestTask,
21
+ hcInboxPollerStateForTests,
22
+ hcRemoveTestAgent,
23
+ hcRemoveTestTask,
24
+ isHcInboxPollerRunning,
25
+ onTaskSettled as onHcTaskSettled,
26
+ pollHcInboxOnce,
27
+ registerHcPollSession,
28
+ stopHcInboxPoller,
29
+ } from '../src/runtimes/hc/runtime.ts';
30
+
31
+ const SESS_A = `hc-poll-test-a-${Date.now()}`;
32
+ const SESS_B = `hc-poll-test-b-${Date.now()}`;
33
+
34
+ function brokerDirs() {
35
+ return readdirSync(tmpdir()).filter(name => name.startsWith('pi-shepherd-broker-'));
36
+ }
37
+
38
+ function brokerDirForSession(sessionId) {
39
+ for (const name of brokerDirs()) {
40
+ try {
41
+ const manifest = JSON.parse(
42
+ readFileSync(path.join(tmpdir(), name, 'broker.json'), 'utf8')
43
+ );
44
+ if (manifest.sessionId === sessionId) return path.join(tmpdir(), name);
45
+ } catch {
46
+ /* not ours / unreadable */
47
+ }
48
+ }
49
+ return undefined;
50
+ }
51
+
52
+ function cleanupSession(sessionId) {
53
+ const dir = brokerDirForSession(sessionId);
54
+ if (dir) rmSync(dir, { recursive: true, force: true });
55
+ }
56
+
57
+ // Clean slate: no timer running in this process yet.
58
+ stopHcInboxPoller();
59
+ {
60
+ const state = hcInboxPollerStateForTests();
61
+ assert.equal(state.running, false, 'poller starts stopped');
62
+ assert.equal(isHcInboxPollerRunning(), false, 'running flag agrees');
63
+ console.log('PASS poller starts stopped');
64
+ }
65
+
66
+ // drainHcInboxForSession with no session resolves nothing and mints nothing.
67
+ {
68
+ const before = brokerDirs();
69
+ assert.equal(drainHcInboxForSession(undefined), false, 'undefined session skips');
70
+ assert.equal(drainHcInboxForSession(' '), false, 'blank session skips');
71
+ assert.deepEqual(brokerDirs(), before, 'a skipped drain mints no broker store');
72
+ console.log('PASS drain-first with no session is a no-op that mints nothing');
73
+ }
74
+
75
+ // Lifecycle: register starts (idempotent), unref'd, stop halts.
76
+ {
77
+ registerHcPollSession(SESS_A);
78
+ registerHcPollSession(SESS_A);
79
+ let state = hcInboxPollerStateForTests();
80
+ assert.equal(state.running, true, 'register starts the poller');
81
+ assert.equal(isHcInboxPollerRunning(), true, 'running flag agrees');
82
+ assert.equal(state.unrefed, true, 'the timer is unrefed and cannot hold the process open');
83
+ stopHcInboxPoller();
84
+ assert.equal(isHcInboxPollerRunning(), false, 'stop halts the poller');
85
+ console.log('PASS poller lifecycle: idempotent start, unrefed, stop halts');
86
+ }
87
+
88
+ // Quiescence: a tick with no unsettled tasks stops the timer.
89
+ {
90
+ registerHcPollSession(SESS_A);
91
+ assert.equal(isHcInboxPollerRunning(), true, 'poller running before the tick');
92
+ pollHcInboxOnce();
93
+ assert.equal(
94
+ isHcInboxPollerRunning(),
95
+ false,
96
+ 'tick with an empty task registry stops at quiescence'
97
+ );
98
+ console.log('PASS tick stops the poller at quiescence');
99
+ }
100
+
101
+ // Pump: a queued task_done is consumed and observably dropped (unknown task),
102
+ // proving the tick runs the full poll → apply pipeline.
103
+ {
104
+ registerHcPollSession(SESS_B);
105
+ assert.equal(drainHcInboxForSession(SESS_B), true, 'first drain materializes the broker');
106
+ const dir = brokerDirForSession(SESS_B);
107
+ assert.ok(dir, 'registration resolves a real session broker');
108
+ const manifest = JSON.parse(readFileSync(path.join(dir, 'broker.json'), 'utf8'));
109
+ const inbox = path.join(dir, 'parent', 'inbox');
110
+ writeFileSync(
111
+ path.join(inbox, `0000000000000001-hc-poll-ghost.json`),
112
+ JSON.stringify({
113
+ kind: 'task_done',
114
+ messageId: 'shepherd-message-hc-poll-ghost',
115
+ taskId: 'shepherd-task-hc-poll-ghost',
116
+ senderId: 'shepherd-agent-hc-poll-ghost',
117
+ targetId: manifest.parentId,
118
+ sessionId: manifest.sessionId,
119
+ brokerId: manifest.brokerId,
120
+ status: 'completed',
121
+ summary: 'ghost done',
122
+ schemaVersion: 1,
123
+ delivery: 'followUp',
124
+ createdAt: Date.now(),
125
+ }),
126
+ 'utf8'
127
+ );
128
+ pollHcInboxOnce();
129
+ assert.deepEqual(readdirSync(inbox), [], 'the tick consumed the inbox');
130
+ assert.equal(
131
+ readdirSync(path.join(dir, 'processed')).length,
132
+ 1,
133
+ 'the envelope was acknowledged to processed/'
134
+ );
135
+ assert.ok(
136
+ readdirSync(path.join(dir, 'rejected')).some(name =>
137
+ name.startsWith('task-done-dropped-')
138
+ ),
139
+ 'an unresolvable completion is observably dropped, not silently lost'
140
+ );
141
+ console.log('PASS tick pumps the drain: queued done consumed and observably applied');
142
+ }
143
+
144
+ // Latest registration wins: single session per process.
145
+ {
146
+ registerHcPollSession(SESS_A);
147
+ registerHcPollSession(SESS_B);
148
+ assert.equal(
149
+ hcInboxPollerStateForTests().session,
150
+ SESS_B,
151
+ 'latest registration wins'
152
+ );
153
+ stopHcInboxPoller();
154
+ console.log('PASS latest registration wins (single session per process)');
155
+ }
156
+
157
+ // Real settlement: a queued done for a KNOWN task settles it through the
158
+ // 010 observer path (not just a dropped diagnostic).
159
+ {
160
+ const SESS_C = `hc-poll-test-c-${Date.now()}`;
161
+ const agentId = 'shepherd-agent-hc-poll-real';
162
+ const taskId = 'shepherd-task-hc-poll-real';
163
+ hcInjectTestAgent({
164
+ handle: { id: agentId, agent: 'worker', label: 'poll-real' },
165
+ state: 'working',
166
+ activeTaskId: taskId,
167
+ });
168
+ hcInjectTestTask({
169
+ taskId,
170
+ agentId,
171
+ description: 'real settle via tick',
172
+ state: 'running',
173
+ createdAt: Date.now(),
174
+ pendingRequestIds: new Set(),
175
+ });
176
+ const seen = [];
177
+ const off = onHcTaskSettled((result, context) => seen.push({ result, context }));
178
+ registerHcPollSession(SESS_C);
179
+ assert.equal(drainHcInboxForSession(SESS_C), true, 'broker materialized for real-settle');
180
+ const dir = brokerDirForSession(SESS_C);
181
+ const manifest = JSON.parse(readFileSync(path.join(dir, 'broker.json'), 'utf8'));
182
+ writeFileSync(
183
+ path.join(dir, 'parent', 'inbox', `0000000000000003-hc-poll-real.json`),
184
+ JSON.stringify({
185
+ kind: 'task_done',
186
+ messageId: 'shepherd-message-hc-poll-real',
187
+ taskId,
188
+ senderId: agentId,
189
+ targetId: manifest.parentId,
190
+ sessionId: manifest.sessionId,
191
+ brokerId: manifest.brokerId,
192
+ status: 'completed',
193
+ summary: 'real-ok',
194
+ schemaVersion: 1,
195
+ delivery: 'followUp',
196
+ createdAt: Date.now(),
197
+ }),
198
+ 'utf8'
199
+ );
200
+ pollHcInboxOnce();
201
+ off();
202
+ assert.deepEqual(readdirSync(path.join(dir, 'parent', 'inbox')), [], 'real done consumed');
203
+ assert.equal(seen.length, 1, 'the 010 observer fired exactly once');
204
+ assert.equal(seen[0].result.status, 'completed', 'settled completed');
205
+ assert.equal(seen[0].result.text, 'real-ok', 'settlement text carried through');
206
+ assert.equal(
207
+ describeHcStatusView(agentId).task,
208
+ undefined,
209
+ 'settled task leaves the status view (agent still known)'
210
+ );
211
+ assert.equal(isHcInboxPollerRunning(), false, 'settlement restores quiescence');
212
+ hcRemoveTestTask(taskId);
213
+ hcRemoveTestAgent(agentId);
214
+ cleanupSession(SESS_C);
215
+ console.log('PASS tick settles a queued done for a known task through the observer');
216
+ }
217
+
218
+ // Keep-alive converse: an open task keeps the poller running across ticks.
219
+ {
220
+ const SESS_D = `hc-poll-test-d-${Date.now()}`;
221
+ const agentId = 'shepherd-agent-hc-poll-open';
222
+ const taskId = 'shepherd-task-hc-poll-open';
223
+ hcInjectTestAgent({
224
+ handle: { id: agentId, agent: 'worker', label: 'poll-open' },
225
+ state: 'working',
226
+ activeTaskId: taskId,
227
+ });
228
+ hcInjectTestTask({
229
+ taskId,
230
+ agentId,
231
+ description: 'open keeps poller alive',
232
+ state: 'running',
233
+ createdAt: Date.now(),
234
+ pendingRequestIds: new Set(),
235
+ });
236
+ registerHcPollSession(SESS_D);
237
+ pollHcInboxOnce();
238
+ assert.equal(
239
+ isHcInboxPollerRunning(),
240
+ true,
241
+ 'an unsettled task keeps the poller alive'
242
+ );
243
+ hcRemoveTestTask(taskId);
244
+ hcRemoveTestAgent(agentId);
245
+ pollHcInboxOnce();
246
+ assert.equal(isHcInboxPollerRunning(), false, 'removing the task restores quiescence');
247
+ cleanupSession(SESS_D);
248
+ console.log('PASS open task keeps the poller alive; removal restores quiescence');
249
+ }
250
+
251
+ // Cleanup: no timer left running, no test broker stores left behind.
252
+ stopHcInboxPoller();
253
+ cleanupSession(SESS_A);
254
+ cleanupSession(SESS_B);
255
+ assert.equal(isHcInboxPollerRunning(), false, 'no timer survives the suite');
256
+ assert.equal(brokerDirForSession(SESS_A), undefined, 'test broker A removed');
257
+ assert.equal(brokerDirForSession(SESS_B), undefined, 'test broker B removed');
258
+ console.log('PASS cleanup leaves no timer and no broker stores');
259
+
260
+ console.log('All hc-poll assertions passed.');
@@ -0,0 +1,35 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * T015 — README splits into per-host tracks on the first screen, so a user
4
+ * of either host can find their install steps without reading the other's.
5
+ */
6
+ import assert from 'node:assert/strict';
7
+ import fs from 'node:fs';
8
+ import path from 'node:path';
9
+
10
+ const readme = fs.readFileSync(path.resolve(import.meta.dirname, '../README.md'), 'utf8');
11
+ const firstScreen = readme.split('\n').slice(0, 60).join('\n');
12
+
13
+ assert.match(firstScreen, /^# Shepherd$/m, 'host-neutral title');
14
+ assert.match(firstScreen, /## Choose your host/, 'host picker is on the first screen');
15
+ const piTrack = firstScreen.indexOf('## Pi track');
16
+ const ocTrack = firstScreen.indexOf('## OpenCode track');
17
+ const sharedContent = firstScreen.indexOf('## Key Features');
18
+ assert.ok(piTrack > -1 && ocTrack > -1, 'both host tracks are on the first screen');
19
+ assert.ok(piTrack < sharedContent && ocTrack < sharedContent, 'tracks precede shared content');
20
+ assert.match(firstScreen, /\[Pi\]\(#pi-track\)/, 'Pi track is linked from the picker');
21
+ assert.match(firstScreen, /\[OpenCode\]\(#opencode-track\)/, 'OpenCode track is linked from the picker');
22
+ assert.match(firstScreen, /pi install npm:@luminascale\/shepherd/, 'Pi install command is shown');
23
+ assert.match(
24
+ firstScreen,
25
+ /"plugins": \["@luminascale\/shepherd"\]/,
26
+ 'OpenCode plugin config is shown'
27
+ );
28
+ assert.equal((readme.match(/^## Install$/gm) ?? []).length, 0, 'no duplicate Pi-only Install section');
29
+ const piTrackText = readme.slice(piTrack, ocTrack);
30
+ const ocTrackText = readme.slice(ocTrack, sharedContent);
31
+ assert.doesNotMatch(piTrackText, /You do not need to install pi/);
32
+ assert.match(ocTrackText, /You do not need to install pi/, 'OpenCode-only note stays in its track');
33
+ console.log('PASS README first screen splits into Pi and OpenCode tracks');
34
+
35
+ console.log('\nAll host-doc assertions passed.');
@@ -0,0 +1,49 @@
1
+ #!/usr/bin/env node
2
+ /** T017 — release checklist and per-host impact classification. */
3
+ import assert from 'node:assert/strict';
4
+ import fs from 'node:fs';
5
+ import path from 'node:path';
6
+ import { execFileSync } from 'node:child_process';
7
+
8
+ const repo = path.resolve(import.meta.dirname, '..');
9
+ const script = path.join(repo, 'scripts', 'host-impact.mjs');
10
+ const impact = files =>
11
+ execFileSync(process.execPath, [script, '--files', files.join(',')], {
12
+ cwd: repo,
13
+ encoding: 'utf8',
14
+ });
15
+
16
+ assert.match(
17
+ impact(['src/extension/shepherd.ts', 'index.ts', 'test/verify-parent-surface.mjs']),
18
+ /Pi-only code release — OpenCode impact must be none/
19
+ );
20
+ assert.match(
21
+ impact(['src/opencode/actions.ts', 'src/opencode/server.ts', 'test/verify-opencode-notice.mjs']),
22
+ /OpenCode-only code release — Pi impact must be none/
23
+ );
24
+ assert.match(
25
+ impact(['src/core/discovery.ts', 'package.json']),
26
+ /shared-engine release — call out impact for BOTH hosts/
27
+ );
28
+ const mixed = impact(['src/extension/shepherd.ts', 'src/opencode/actions.ts']);
29
+ assert.match(mixed, /cross-host release — call out impact for BOTH hosts/);
30
+ assert.match(impact(['docs/releasing.md', 'test/verify-cli.mjs']), /docs-and-tests-only release/);
31
+ console.log('PASS host-impact classifies Pi-only, OpenCode-only, shared, mixed, and docs-only');
32
+
33
+ const checklist = fs.readFileSync(path.join(repo, 'docs', 'releasing.md'), 'utf8');
34
+ for (const item of [
35
+ 'npm test',
36
+ 'pi-suite:test',
37
+ 'opencode-suite:test',
38
+ 'host-impact',
39
+ 'Pi impact',
40
+ 'OpenCode impact',
41
+ 'new package first',
42
+ '0.6.0',
43
+ '0.5.2',
44
+ ]) {
45
+ assert.ok(checklist.includes(item), `release checklist covers: ${item}`);
46
+ }
47
+ console.log('PASS release checklist requires both suites and explicit per-host notes');
48
+
49
+ console.log('\nAll release-process assertions passed.');