@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,12 @@
1
+ # Bundled agents (shared scope)
2
+
3
+ Built-in specialized agents (the sheep of the herd) shipped with pi-shepherd, in the **cross-tool /
4
+ Claude-format location** (`.agents/agents`). You can reuse the same agent files
5
+ across VS Code (`.github/agents` / `.claude/agents`) and pi.
6
+
7
+ Uses the **standard VS Code custom-agent syntax** (YAML frontmatter + Markdown
8
+ body). These are the **lowest-precedence base set** — user/project agents
9
+ override a built-in with the same name.
10
+
11
+ The same durable, no-fuss agents ship in `.pi/agents/` too; the two dirs
12
+ together form pi-shepherd's bundled defaults.
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: planner
3
+ description: Creates concrete implementation plans from context and requirements
4
+ tools: read, grep, find, ls
5
+ model: null
6
+ thinking: default
7
+ ---
8
+
9
+ You are a planning specialist. You receive context (possibly from a scout) and
10
+ requirements, then produce a clean, concrete implementation plan.
11
+
12
+ You must NOT make any changes. Only read, analyze, and plan.
13
+
14
+ Input you'll receive:
15
+ - Context/findings from a scout agent (or the task itself)
16
+ - Original query or requirements
17
+
18
+ Output format:
19
+
20
+ ## Goal
21
+ One sentence summary of what needs to be done.
22
+
23
+ ## Plan
24
+ Numbered steps, each small and actionable:
25
+ 1. Step one — specific file/function to modify
26
+ 2. Step two — what to add/change
27
+
28
+ ## Files to Modify
29
+ - `path/to/file.ts` — what changes
30
+ - `path/to/other.ts` — what changes
31
+
32
+ ## New Files (if any)
33
+ - `path/to/new.ts` — purpose
34
+
35
+ ## Risks
36
+ Anything to watch out for.
37
+
38
+ Keep the plan concrete. A worker agent will execute it.
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: reviewer
3
+ description: Code review specialist for quality and security analysis
4
+ tools: read, grep, find, ls, bash
5
+ model: null
6
+ thinking: default
7
+ ---
8
+
9
+ You are a senior code reviewer. Analyze code for quality, security, and
10
+ maintainability.
11
+
12
+ Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT
13
+ modify files or run builds. Assume tool permissions are not perfectly
14
+ enforceable; keep all bash usage strictly read-only.
15
+
16
+ Strategy:
17
+ 1. Run `git diff` to see recent changes (if applicable).
18
+ 2. Read the modified files.
19
+ 3. Check for bugs, security issues, code smells.
20
+
21
+ Output format:
22
+
23
+ ## Files Reviewed
24
+ - `path/to/file.ts` (lines X-Y)
25
+
26
+ ## Critical (must fix)
27
+ - `file.ts:42` - Issue description
28
+
29
+ ## Warnings (should fix)
30
+ - `file.ts:100` - Issue description
31
+
32
+ ## Suggestions (consider)
33
+ - `file.ts:150` - Improvement idea
34
+
35
+ ## Summary
36
+ Overall assessment in 2-3 sentences.
37
+
38
+ Be specific with file paths and line numbers.
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: scout
3
+ description: Fast codebase recon that returns compressed context for handoff
4
+ tools: read, grep, find, ls
5
+ model: null
6
+ thinking: default
7
+ ---
8
+
9
+ You are a scout. Quickly investigate a codebase and return structured findings
10
+ that another agent can use without re-reading everything.
11
+
12
+ Your output may be passed to an agent who has NOT seen the files you explored,
13
+ so make it self-contained: exact paths, line ranges, key code, and how the
14
+ pieces connect.
15
+
16
+ Thoroughness (infer from the task, default medium):
17
+ - Quick: targeted lookups, key files only
18
+ - Medium: follow imports, read critical sections
19
+ - Thorough: trace dependencies, check tests/types
20
+
21
+ Strategy:
22
+ 1. grep/find to locate relevant code.
23
+ 2. Read key sections (not entire files).
24
+ 3. Identify types, interfaces, key functions.
25
+ 4. Note dependencies between files.
26
+
27
+ Use only read-only tools. Do not modify anything.
28
+
29
+ Output format:
30
+
31
+ ## Files Retrieved
32
+ List with exact line ranges:
33
+ 1. `path/to/file.ts` (lines 10-50) - Description of what's here
34
+ 2. `path/to/other.ts` (lines 100-150) - Description
35
+
36
+ ## Key Code
37
+ Critical types, interfaces, or functions (actual code, snippets).
38
+
39
+ ## Architecture
40
+ Brief explanation of how the pieces connect.
41
+
42
+ ## Start Here
43
+ Which file to look at first and why.
@@ -0,0 +1,33 @@
1
+ ---
2
+ name: worker
3
+ description: General-purpose agent with full capabilities, isolated context
4
+ tools: read, write, edit, bash
5
+ model: null
6
+ thinking: default
7
+ ---
8
+
9
+ You are a worker agent with full capabilities. You operate in an isolated
10
+ context window to handle delegated tasks without polluting the main
11
+ conversation.
12
+
13
+ Work autonomously to complete the assigned task. Use all available tools as
14
+ needed.
15
+
16
+ Output format when finished:
17
+
18
+ ## Completed
19
+
20
+ What was done.
21
+
22
+ ## Files Changed
23
+
24
+ - `path/to/file.ts` - what changed
25
+
26
+ ## Notes (if any)
27
+
28
+ Anything the main agent should know.
29
+
30
+ If handing off to another agent (e.g. reviewer), include:
31
+
32
+ - Exact file paths changed
33
+ - Key functions/types touched (short list)
@@ -0,0 +1,155 @@
1
+ ---
2
+ name: smoke-test
3
+ description: Live smoke-test Shepherd sheep on hc or herdr backends (spawn/delegate/watch/status/close, completion timing, broker forensics). Use when asked to smoke-test Shepherd, verify completions arrive, or check for junk broker stores.
4
+ ---
5
+
6
+ # Smoke test
7
+
8
+ Live proof that delegated work settles and the parent hears about it.
9
+ Deterministic suites (`npm test`) are the pre-gate — run them first.
10
+ Smokes are the live complement, not a replacement.
11
+
12
+ What's in this skill:
13
+
14
+ - **Track A — Shepherd-driven smoke** (below): the spawn → delegate →
15
+ watch → status → close sequence, same on both backends, with
16
+ message-free and idle-wake variants.
17
+ - **Track B — direct-runtime poll probe** (below): `scripts/live-smoke-poll.mjs`,
18
+ runnable headless via `npm run smoke:poll` (hc only, ~3–4 min).
19
+ - **`references/forensics.md`**: broker before/after snapshots, junk-store
20
+ checks, timing interpretation, herdr pane notes.
21
+ - **Track C — messaging smoke** (below): parent→child→parent
22
+ `expectsReply` round trip, then peer→peer ping/pong between two
23
+ sheep with the parent out of the middle.
24
+ - **Backend differences table** (bottom): hc vs herdr at a glance.
25
+
26
+ ## Track A — Shepherd-driven smoke (both backends)
27
+
28
+ Same tool-call sequence on either backend; only the setup differs.
29
+
30
+ **Setup.** hc: default when called from an hc app session. herdr: run
31
+ from inside a herdr pane, or pin `backend: "herdr"` in user config and
32
+ reload. Confirm which backend you are on before starting.
33
+
34
+ **Steps.**
35
+
36
+ 1. Snapshot broker state (see `references/forensics.md`).
37
+ 2. `shepherd_spawn` a `scout` (quick recon) or `worker` (timed sleep).
38
+ 3. `shepherd_delegate` a short task with an explicit timeout.
39
+ 4. `shepherd_watch` immediately — expect `pending` (registration is
40
+ non-blocking and returns at once).
41
+ 5. Wait out the work (sleep in bash; ~90 s for a small recon).
42
+ 6. `shepherd_status` — expect fresh state; on current code the status
43
+ view drains first, so this is a live read, not a stale one.
44
+ 7. `shepherd_close` the sheep. Always close — never leave sheep running
45
+ past the smoke.
46
+ 8. Diff broker state against the snapshot: exactly the expected stores,
47
+ zero junk (forensics reference).
48
+
49
+ **Variants.**
50
+
51
+ - *Message-free (poll proof):* send no `shepherd_message` for the whole
52
+ run. Completion must still arrive promptly — on hc that means the
53
+ 250 ms background poll settled it, not the far-away delegate
54
+ deadline. If completion takes ~deadline instead of ~seconds, the poll
55
+ is broken.
56
+ - *Idle wake (unseen path):* delegate with NO watcher, end your turn.
57
+ The completion must reopen your turn as a coalesced unseen notice
58
+ naming the `shepherd_watch` retrieval call. Then watch (returns
59
+ completed synchronously) and close.
60
+
61
+ **Pass criteria.** Spawn/delegate/watch/status/close all succeed;
62
+ completion arrives in seconds-to-minutes (bounded by the work, never
63
+ by the deadline); no `hc-parent-*` junk stores; sheep closed.
64
+
65
+ ## Track B — direct-runtime poll probe (hc only)
66
+
67
+ `scripts/live-smoke-poll.mjs` delegates with a 30-minute deadline and
68
+ then observes *only* through drain-free reads (status view + inbox dir
69
+ stats — no watch, no message, no status calls). Any prompt settlement
70
+ is therefore the background poll, unconfounded. Run from the repo
71
+ root; takes ~3–4 minutes (live `hc run --bg` child).
72
+
73
+ ```sh
74
+ node --experimental-strip-types --disable-warning=ExperimentalWarning \
75
+ .agents/skills/smoke-test/scripts/live-smoke-poll.mjs
76
+ ```
77
+
78
+ It asserts: poller running while work is open, done arrives, settle
79
+ lag after arrival is poll-bounded (< 10 s, not deadline-bound), no
80
+ junk stores, close clean.
81
+
82
+ ## Track C — messaging smoke (both backends)
83
+
84
+ Covers what Tracks A/B don't: a real parent→child request with a
85
+ correlated reply, and a real peer→peer exchange with the parent out
86
+ of the middle. Needs real children (wakes + broker relay are the
87
+ point), so this is Shepherd-driven only — no script version. ~5 min.
88
+
89
+ Wake semantics to rely on: a message with `expectsReply` and any
90
+ message with `replyTo` wake a waiting agent automatically; a plain
91
+ `followUp` with neither only queues. So every leg that must wake
92
+ someone is a request or a reply, never a bare follow-up. A child
93
+ that has nothing to do yet ends its turn WITHOUT `shepherd_done`
94
+ and lets the incoming message wake it.
95
+
96
+ **C1 — parent→child→parent round trip.**
97
+
98
+ 1. Snapshot broker state; `shepherd_spawn` one `worker`.
99
+ 2. `shepherd_delegate` a stand-by task with NO time limit in the
100
+ text ("wait as long as it takes; never give up") — first-wins
101
+ settlement means a premature give-up `done` poisons the task
102
+ (observed live: a give-up `failed` won over the correct reply
103
+ that arrived 9 s later). The delegate `timeout` is the backstop.
104
+ Task: stand by, reply via `shepherd_message` (`replyTo` the
105
+ request, text = the code word), then `shepherd_done`.
106
+ 3. `shepherd_message` to the exact agent id with
107
+ `expectsReply: true` (plus the task id; `delivery: "steer"` is now
108
+ the default and may be omitted),
109
+ text "request: report code word `mango-<pid>`". Steer, not
110
+ followUp — a followUp to an idle child sat queued for minutes
111
+ (observed live). The request wakes the child; the task waits.
112
+ 4. Expect the reply notification naming the request, then the
113
+ `shepherd_done` completion via watch. Assert the code word matches
114
+ in both the reply and the done summary.
115
+ 5. `shepherd_close`; diff broker state (no junk).
116
+
117
+ Budget minutes, not seconds: child boot plus the idle-wake leg
118
+ dominates on hc. Consumed envelopes land in broker-root
119
+ `processed/`, not `parent/processed/` — look there for forensics.
120
+
121
+ **C2 — peer→peer ping/pong.**
122
+
123
+ 1. `shepherd_spawn` two `worker`s, A and B. Nonce `ping-<pid>`.
124
+ 2. Delegate to B with NO time limit in the text (same first-wins
125
+ reason as C1): "Stand by. When a message from a peer arrives,
126
+ reply to the sender via `shepherd_message` (set `replyTo`, text
127
+ `pong-<pid>`), then `shepherd_done` with the RECEIVED text as
128
+ summary." Timeout 10. B ends its turn waiting.
129
+ 3. Delegate to A, embedding B's exact agent id: "Send
130
+ `ping-<pid>` to agent <B-id> via `shepherd_message` with
131
+ `expectsReply: true`. Then end your turn WITHOUT `shepherd_done`
132
+ and wait — no time limit, never give up. When the reply arrives,
133
+ `shepherd_done` with the reply text as summary." Timeout 10.
134
+ 4. Watch both tasks (expect pending, then both completed — order:
135
+ B first, then A).
136
+ 5. Assert A's done summary is `pong-<pid>` and B's is `ping-<pid>`:
137
+ the full round trip went through the broker relay with no parent
138
+ involvement. Close both; diff broker state (no junk).
139
+
140
+ **Pass criteria.** C1: reply notification + done, code word intact
141
+ both ways. C2: crossed summaries exact, both sheep closed, no junk.
142
+ Timeouts must never fire — a timeout means a wake or relay failed.
143
+
144
+ ## Backend differences
145
+
146
+ | | hc | herdr |
147
+ |---|---|---|
148
+ | Parent drain trigger | 250 ms background poll + drain-first watch/status/deadline | 250 ms `parentBrokerTimer` + drain on tool calls |
149
+ | Completion store | `/tmp/pi-shepherd-broker-*/` session dirs | pane-scoped inbox dirs (no `/tmp` session brokers) |
150
+ | Junk signature | `hc-parent-*` session ids | raw pane-id bypasses of the ownership registry |
151
+ | Settled task in status view | disappears (view carries unsettled tasks only) | check `describeH...StatusView` equivalent |
152
+
153
+ The status-view-clears-on-settle rule (hc) is a classic false alarm:
154
+ a delegated task vanishing from the view while the agent is still
155
+ known MEANS settled, not lost.
@@ -0,0 +1,46 @@
1
+ # Smoke forensics
2
+
3
+ ## hc: before/after snapshot
4
+
5
+ ```sh
6
+ for d in /tmp/pi-shepherd-broker-*/; do
7
+ s=$(python3 -c "import json;print(json.load(open('$d/broker.json'))['sessionId'])" 2>/dev/null)
8
+ echo "$s $d"
9
+ done | sort > /tmp/smoke-before.txt
10
+ # ... run the smoke ...
11
+ # ... same loop to /tmp/smoke-after.txt, then:
12
+ comm -13 /tmp/smoke-before.txt /tmp/smoke-after.txt # new dirs: expect only the session broker
13
+ ```
14
+
15
+ Reload nuance: each process lifetime mints one broker dir per
16
+ session, so a reload between snapshots legitimately shows one new
17
+ session dir (same sessionId, new brokerId; the old dir is inert —
18
+ no process or timer references it). Take both snapshots within one
19
+ process lifetime, and expect exactly one live store.
20
+
21
+ ## hc: junk check
22
+
23
+ Any new dir whose `broker.json` sessionId starts with `hc-parent-`
24
+ is a fallback-keyed junk store minted by a bare `ensureBroker()` on a
25
+ path that should have threaded the drain's session-keyed broker.
26
+ Zero is the only passing number.
27
+
28
+ ## Timing interpretation
29
+
30
+ - Settle lag after the done lands in `parent/inbox` (or moves to
31
+ `parent/processed/`): **< 10 s** means a live drain path consumed it
32
+ (background tick or tool-call drain). Near the delegate deadline
33
+ means only the deadline drain fired — the prompt paths are broken.
34
+ - Caveat: the 250 ms tick consumes inbox files fast, so inbox
35
+ *presence* polls can miss arrivals entirely. Detect arrival via new
36
+ files in `parent/processed/` (they persist), not via inbox
37
+ non-emptiness.
38
+ - Status-view caveat: the view carries unsettled tasks only. Task gone
39
+ + agent known = settled.
40
+
41
+ ## herdr
42
+
43
+ No `/tmp` session brokers. Forensics are pane-scoped inbox dirs (see
44
+ `src/runtimes/herdr/messaging.ts` `inboxPath`) plus the owned-pane
45
+ registry (`created-panes.json`). Raw pane ids must never bypass the
46
+ ownership check on close.
@@ -0,0 +1,130 @@
1
+ #!/usr/bin/env node
2
+ // Live poll probe (Track B of the smoke-test skill): delegate with NO watch, NO message, NO status
3
+ // calls. The only settlement trigger is the 250 ms background poll.
4
+ // Observes via describeHcStatusView (pure map read, no drain) and direct
5
+ // inbox directory stats (fs reads, not drains).
6
+ import * as fs from 'node:fs';
7
+ import * as os from 'node:os';
8
+ import * as path from 'node:path';
9
+ import { fileURLToPath } from 'node:url';
10
+ // Skill-bundled probe: resolve the repo root from this file's location
11
+ // (scripts/ -> smoke-test/ -> skills/ -> .agents/ -> root).
12
+ const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
13
+ const REPO_SRC = path.join(repoRoot, 'src') + '/';
14
+
15
+ const SESSION = `hc-011-smoke-${process.pid}`;
16
+ process.env.PI_SHEPHERD_OWNER_SESSION = SESSION;
17
+
18
+ const failures = [];
19
+ const ok = (cond, label) => {
20
+ console.log(`${cond ? 'PASS' : 'FAIL'} ${label}`);
21
+ if (!cond) failures.push(label);
22
+ };
23
+
24
+ const {
25
+ createHcRuntime,
26
+ describeHcStatusView,
27
+ isHcInboxPollerRunning,
28
+ } = await import(`${REPO_SRC}runtimes/hc/runtime.ts`);
29
+ const sessions = await import(`${REPO_SRC}core/artifact-sessions.ts`);
30
+
31
+ const sleep = ms => new Promise(r => setTimeout(r, ms));
32
+
33
+ function sessionBrokerDir(sessionId) {
34
+ for (const name of fs.readdirSync(os.tmpdir())) {
35
+ if (!name.startsWith('pi-shepherd-broker-')) continue;
36
+ try {
37
+ const man = JSON.parse(fs.readFileSync(path.join(os.tmpdir(), name, 'broker.json'), 'utf8'));
38
+ if (man.sessionId === sessionId) return path.join(os.tmpdir(), name);
39
+ } catch {}
40
+ }
41
+ return undefined;
42
+ }
43
+ const junkBefore = new Set(
44
+ fs.readdirSync(os.tmpdir()).filter(n => n.startsWith('pi-shepherd-broker-'))
45
+ );
46
+
47
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'hc-011-smoke-'));
48
+ const artifactSession = sessions.resolveOrCreateParentArtifactSession({
49
+ parentPiSessionId: SESSION,
50
+ projectRoot: tmp,
51
+ });
52
+ const rt = createHcRuntime({ cwd: tmp, artifactSession });
53
+
54
+ const agentId = await rt.spawn({ name: 'worker' }, { cwd: tmp, label: '011-smoke' });
55
+ ok(agentId.startsWith('shepherd-agent-'), `spawn (${agentId})`);
56
+
57
+ // High deadline so the Phase-3 deadline drain CANNOT confound: any prompt
58
+ // settlement must come from the background poll.
59
+ const taskId = await rt.delegate(
60
+ agentId,
61
+ 'Do nothing else. Immediately call shepherd_done with status completed and summary hc-011-smoke-ok.',
62
+ { timeoutMin: 30 }
63
+ );
64
+ ok(taskId.startsWith('shepherd-task-'), `delegate (${taskId})`);
65
+ ok(isHcInboxPollerRunning(), 'background poller is running while work is open');
66
+
67
+ const dir = sessionBrokerDir(SESSION);
68
+ ok(!!dir, 'session broker exists');
69
+ const inbox = path.join(dir, 'parent', 'inbox');
70
+ const processedDir = path.join(dir, 'parent', 'processed');
71
+ const processedBase = new Set(fs.readdirSync(path.join(dir, 'processed')));
72
+
73
+ // Wait for the done to ARRIVE (new file in processed/ — the tick consumes
74
+ // the inbox within 250 ms, so inbox polling alone can miss it), then
75
+ // measure settle lag with drain-free reads only.
76
+ let arrivedAt = 0;
77
+ for (let i = 0; i < 240 && !arrivedAt; i++) {
78
+ const fresh = fs.readdirSync(path.join(dir, 'processed')).filter(f => !processedBase.has(f));
79
+ if (fresh.length > 0 || fs.readdirSync(inbox).length > 0) arrivedAt = Date.now();
80
+ else await sleep(500);
81
+ }
82
+ ok(arrivedAt > 0, 'task_done arrived in the parent inbox');
83
+ let settledAt = 0;
84
+ let state = '';
85
+ // NOTE: the status view only carries *unsettled* tasks (runtime.ts: the
86
+ // task view is built only when `!open.result`), so a delegated task
87
+ // disappearing from the view while the agent is still known MEANS settled.
88
+ for (let i = 0; i < 120 && !settledAt; i++) {
89
+ let view;
90
+ try {
91
+ view = describeHcStatusView(agentId);
92
+ } catch {
93
+ view = undefined;
94
+ }
95
+ if (!view) {
96
+ state = '(agent unknown)';
97
+ } else if (!view.task) {
98
+ state = 'completed (task settled, view cleared)';
99
+ settledAt = Date.now();
100
+ } else {
101
+ state = view.task.state;
102
+ }
103
+ if (!settledAt) await sleep(250);
104
+ }
105
+ const lag = settledAt - arrivedAt;
106
+ ok(settledAt > 0, `settled with no watch/message/status (state=${state})`);
107
+ ok(lag < 10000, `settle lag after arrival is poll-bounded, not deadline-bound (${lag}ms)`);
108
+ ok(isHcInboxPollerRunning() === false || true, 'poller state noted (quiescence stops it eventually)');
109
+
110
+ await rt.close(agentId);
111
+ ok(true, 'close owned terminal');
112
+
113
+ // No junk fallback-keyed broker dirs minted during the run.
114
+ const junkAfter = fs
115
+ .readdirSync(os.tmpdir())
116
+ .filter(n => n.startsWith('pi-shepherd-broker-') && !junkBefore.has(n));
117
+ let junkSessions = [];
118
+ for (const n of junkAfter) {
119
+ try {
120
+ junkSessions.push(JSON.parse(fs.readFileSync(path.join(os.tmpdir(), n, 'broker.json'), 'utf8')).sessionId);
121
+ } catch {}
122
+ }
123
+ ok(!junkSessions.some(s => String(s).startsWith('hc-parent-')), `no junk hc-parent-* stores (${JSON.stringify(junkSessions)})`);
124
+
125
+ fs.rmSync(tmp, { recursive: true, force: true });
126
+ if (failures.length) {
127
+ console.log('FAILURES:', failures);
128
+ process.exit(1);
129
+ }
130
+ console.log('011 live smoke passed.');
@@ -0,0 +1,77 @@
1
+ name: Publish package
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ # Trusted publishing uses GitHub's OIDC token instead of an npm token.
8
+ permissions:
9
+ contents: read
10
+ id-token: write
11
+
12
+ concurrency:
13
+ group: publish-${{ github.event.release.tag_name }}
14
+ cancel-in-progress: false
15
+
16
+ jobs:
17
+ publish:
18
+ name: Publish ${{ github.event.release.tag_name }} to npm
19
+ runs-on: ubuntu-latest
20
+
21
+ steps:
22
+ - name: Check out released tag
23
+ uses: actions/checkout@v6
24
+ with:
25
+ ref: ${{ github.event.release.tag_name }}
26
+ fetch-depth: 1
27
+
28
+ - name: Set up Node.js
29
+ uses: actions/setup-node@v6
30
+ with:
31
+ node-version: 24.x
32
+ registry-url: https://registry.npmjs.org
33
+ cache: npm
34
+
35
+ - name: Verify tag matches package version
36
+ id: package
37
+ env:
38
+ RELEASE_TAG: ${{ github.event.release.tag_name }}
39
+ run: |
40
+ node <<'NODE'
41
+ const fs = require('node:fs');
42
+ const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
43
+ const tag = process.env.RELEASE_TAG;
44
+ const expectedTag = `v${packageJson.version}`;
45
+ if (tag !== expectedTag) {
46
+ console.error(`Release tag ${tag} does not match package version ${packageJson.version} (expected ${expectedTag})`);
47
+ process.exit(1);
48
+ }
49
+ console.log(`Publishing ${packageJson.name}@${packageJson.version}`);
50
+ fs.appendFileSync(process.env.GITHUB_OUTPUT, `name=${packageJson.name}\nversion=${packageJson.version}\n`);
51
+ NODE
52
+
53
+ # npm versions are immutable. This makes the workflow safe to rerun and
54
+ # also lets the first release be bootstrapped manually before OIDC is
55
+ # configured for the newly-created npm package.
56
+ - name: Check whether this version is already published
57
+ id: npm
58
+ env:
59
+ PACKAGE_NAME: ${{ steps.package.outputs.name }}
60
+ PACKAGE_VERSION: ${{ steps.package.outputs.version }}
61
+ run: |
62
+ if npm view "${PACKAGE_NAME}@${PACKAGE_VERSION}" version --registry=https://registry.npmjs.org >/dev/null 2>&1; then
63
+ echo "published=true" >> "$GITHUB_OUTPUT"
64
+ echo "${PACKAGE_NAME}@${PACKAGE_VERSION} is already published; skipping npm publish."
65
+ else
66
+ echo "published=false" >> "$GITHUB_OUTPUT"
67
+ fi
68
+
69
+ - name: Install dependencies
70
+ run: npm ci
71
+
72
+ - name: Run tests
73
+ run: npm test
74
+
75
+ - name: Publish to npm
76
+ if: steps.npm.outputs.published != 'true'
77
+ run: npm publish --access public --provenance
@@ -0,0 +1,21 @@
1
+ ---
2
+ description: "Cut the next pi-shepherd release: verify, bump the package version, commit, tag, and push"
3
+ argument-hint: "[version] [bump-level: patch|minor|major]"
4
+ ---
5
+ Cut the next release of this repository following the established v0.1.x pattern.
6
+
7
+ Version to bump to: ${1:-next patch} (if this is a word like "patch"/"minor"/"major", bump that digit of the current version in package.json; if it is a concrete value like "0.1.5", use it verbatim).
8
+ Note for the release summary: ${2:-(none given)}
9
+
10
+ Steps (do them in order, and stop with a clear report if any step fails):
11
+
12
+ 1. Check state: run `git status --short` and `git log --oneline -5` — make sure the fix/feature work is already committed and the tree is clean. If there is uncommitted work, summarize it and ask before committing; do not silently swallow changes.
13
+ 2. Verify: run `npm test` and require a clean pass. If tests fail, stop and report — do not release a failing build.
14
+ 3. Determine the next version from `package.json` (the current published version field), applying the bump requested above.
15
+ 4. Bump the package: run `npm version <next> --no-git-tag-version` so BOTH `package.json` and `package-lock.json` are updated consistently (the lockfile can drift; `npm version` fixes that). Show the version diff before committing.
16
+ 5. Commit the bump with the repo's conventional message: `Bump version to <next>`.
17
+ 6. Create the release tag on that commit, annotated, matching the v0.1.3 style: `git tag -a v<next> -m "Bump version to <next>"`.
18
+ 7. Push the branch and the tag: `git push` then `git push origin v<next>`.
19
+ 8. Report: show `git log --oneline` of the new tag and the range since the previous tag (e.g. `git log --oneline v<prev>..v<next>`) so the user can see exactly what the release contains.
20
+
21
+ Never force-push, never delete or move an existing tag, and never run `npm publish` unless the user explicitly asks for it.
package/.prettierrc ADDED
@@ -0,0 +1,10 @@
1
+ {
2
+ "semi": true,
3
+ "singleQuote": true,
4
+ "tabWidth": 2,
5
+ "trailingComma": "es5",
6
+ "printWidth": 100,
7
+ "bracketSpacing": true,
8
+ "arrowParens": "avoid",
9
+ "endOfLine": "lf"
10
+ }