@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,49 @@
1
+ # Plan — 009 hc-runtime
2
+
3
+ ## Target
4
+
5
+ 2-runtimes-1-core, same pattern as 006 Phase 0:
6
+
7
+ ```text
8
+ src/core/ discovery, ids, config, artifact-sessions (shared, no CLI import)
9
+ src/runtimes/
10
+ runtime.ts ShepherdRuntime (unchanged)
11
+ detect.ts NEW: detectCaller() -> herdr-tui | hc-app | plain
12
+ herdr/ existing
13
+ hc/ NEW: runtime.ts + hc.ts (ownership, launch, read)
14
+ src/extension/ resolve runtime per command from (setting + detect), no schema change
15
+ ```
16
+
17
+ ## Design decisions
18
+
19
+ 1. **Setting, not tool param.** `backend: auto|herdr|hc` lives in
20
+ `src/core/config.ts` store + `/shepherd settings` UI only.
21
+ No `shepherd_*` schema, promptSnippet, or result mentions it.
22
+ 2. **Per-command resolve** (not per-session sticky):
23
+ `resolveBackend() = explicit pin if set, else detectCaller()`.
24
+ Env check is free; binary/socket probe cached ~1s with 3s timeout cap
25
+ so status-widget ticks stay cheap.
26
+ 3. **Spawn parity, impl may differ.** TUI keeps `pane split/tab create +
27
+ launchPiInPane`; hc uses `hc run --bg` + label + `hc read` tail.
28
+ Both retain: background by default, cwd preserved, temp launch dir
29
+ lifetime tied to owned terminal/pane, `shepherd_done` 1-nudge.
30
+ 4. **Introspection stays per-runtime.** `herd/agents/prune`/widget read
31
+ owned-panes OR owned-terminals summaries; IDs stay opaque in display.
32
+ 5. **No migration.** Default `auto` == current behavior when called from
33
+ TUI; app callers get local runs without config.
34
+
35
+ ## Order
36
+
37
+ Phase 0 — detect + setting + shim (zero behavior change, TUI default intact).
38
+ Phase 1 — `src/runtimes/hc/` spawn/delegate/watch/done + mapping tests.
39
+ Phase 2 — message/status parity, fieldnotes bridge check, auto-viewer rules,
40
+ docs + live proof.
41
+
42
+ ## Open questions
43
+
44
+ 1. `placement` on `hc`: ignore vs map to `hc` spaces/tabs? Proposal: ignore
45
+ for execution in Phase 1, honor for viewer in `auto` later.
46
+ 2. `read --lines` over `hc read` frames vs full view? Proposal: tail same
47
+ 120-line default, slice after.
48
+ 3. Project-forced backend? Proposal: no — same user-owned rule as
49
+ `confirmProjectAgents`; project file can suggest `auto` only.
@@ -0,0 +1,118 @@
1
+ # Spec — hc-app Runtime (Herdr TUI + hc core)
2
+
3
+ ## Status
4
+
5
+ Proposed. No behavior change yet.
6
+
7
+ ## Surface — no model-facing change
8
+
9
+ Same tools, same opaque IDs, same agent Markdown:
10
+
11
+ ```text
12
+ shepherd_spawn(agent, {cwd, label, placement}) -> agent ID
13
+ shepherd_delegate(agentID, task) -> task ID
14
+ shepherd_message(target, message, {...}) -> message ID
15
+ shepherd_watch({id}) -> completion(s)
16
+ shepherd_status(agentID) -> {proc, task, waitingOn, stale}
17
+ shepherd_close({id})
18
+ shepherd_read(agent, {lines})
19
+ child: shepherd_message(parent|peer) + shepherd_done
20
+ ```
21
+
22
+ No `backend` field on any tool schema, prompt snippet, or result.
23
+ A model must not be able to decide runtimes.
24
+
25
+ ## Backend setting (app side only)
26
+
27
+ ```jsonc
28
+ // user layer (pi-shepherd/config.json) + optional project delta
29
+ {
30
+ "backend": "auto" // | "herdr" | "hc" — default "auto"
31
+ }
32
+ ```
33
+
34
+ - `auto` (default): resolve per command from caller environment
35
+ (see Detection). Run where called from.
36
+ - `herdr`: pin to TUI runtime. Fail cleanly if `herdr` CLI/server
37
+ unreachable — do not fall back to `hc` silently.
38
+ - `hc`: pin to app runtime. Fail cleanly if `hc`/socket unreachable —
39
+ do not fall back to `herdr` silently.
40
+ - Setting lives in `/shepherd settings` UI + config files only.
41
+ `confirmProjectAgents`-style safety: project config may suggest but
42
+ must not force a runtime for everyone (user-owned precedence, same
43
+ rule as agents). Exact precedence to be fixed in plan (proposal:
44
+ explicit user pin > auto-detect; dormant project file never forces).
45
+
46
+ ## Detection — where are we?
47
+
48
+ Authoritative signals only (env + binary + socket), never labels/titles.
49
+
50
+ ```text
51
+ herdr-tui iff:
52
+ HERDR_ENV == "1" AND HERDR_PANE_ID set AND `herdr --version` ok
53
+ (+ optional: ~/.config/herdr/herdr.sock reachable)
54
+
55
+ hc-app iff:
56
+ HC_TERMINAL_ID set AND HC_TERMINAL_SOCKET exists AND `hc ls` ok
57
+ (+ optional: GIO_LAUNCHED_DESKTOP_FILE == herdr-app.desktop)
58
+
59
+ plain otherwise:
60
+ neither env set. May drive either headless server if reachable,
61
+ else error with setup hint.
62
+ ```
63
+
64
+ Rules:
65
+
66
+ - Check per command (cheap: env first, then cached binary/socket probe
67
+ with short timeout). No sticky process-global decision.
68
+ - Nested case (`HC_TERMINAL_ID=t4 parent=t1`): innermost caller wins.
69
+ If both Herdr and hc signals present, prefer the direct caller env
70
+ (`HC_*` when invoked from `hc`, `HERDR_*` when invoked from TUI pane).
71
+ - `plain` + `auto`: prefer reachable `herdr` server if up, else `hc`
72
+ socket if up, else error naming both setup hints. Never guess topology.
73
+ - Detection result is internal only. Never leak `paneId`, `t4`,
74
+ `conversationId`, socket paths, or `HERDR_*`/`HC_*` values in tool
75
+ results or widget rows — opaque IDs only.
76
+
77
+ ## Runtime interface
78
+
79
+ Reuse `src/runtimes/runtime.ts` (`ShepherdRuntime`) unchanged:
80
+
81
+ ```text
82
+ src/runtimes/
83
+ runtime.ts # unchanged 7-method contract
84
+ herdr/ # existing
85
+ hc/ # new: runtime.ts over `hc run/send/read/wait/kill`
86
+ src/core/ # shared: discovery, ids, config, artifact-sessions
87
+ src/extension/ # unchanged surface; resolves runtime per command
88
+ ```
89
+
90
+ - `spawn`: `hc run --bg pi ...` + `hc label` ownership; `placement`
91
+ may differ (TUI `pane_right/tab/workspace` vs app terminals) but
92
+ caller-visible semantics stay identical (background, `--no-focus`
93
+ equivalent, cwd preserved, inspectable).
94
+ - `delegate/message/watch/status/close/read`: map onto
95
+ `hc send/read/wait/get/kill` with same opaque-ID contract.
96
+ Raw `t4` / `w1:p1` never accepted as handles, never leaked in
97
+ `status/read/prune`.
98
+ - Ownership: new `created-terminals.json` beside `created-panes.json`.
99
+ Only close what this Shepherd created.
100
+
101
+ ## Safety
102
+
103
+ - Keep all current Herdr invariants (`--no-focus`, only-close-ours,
104
+ temp-dir lifetime, `confirmProjectAgents` user-owned).
105
+ - Mirror for `hc`: only `hc kill/rm` owned terminals; background terminals
106
+ use `keep`; never `hc server stop` from a live session.
107
+ - Cross-runtime refusal: pinned-but-unreachable backend returns a
108
+ service message + `call/return/details` (standard Shepherd error shape)
109
+ with the setup hint, not a fallback spawn.
110
+
111
+ ## Verification (deferred to tasks.md)
112
+
113
+ - Suite green on `backend: herdr` unchanged.
114
+ - New `verify-hc-matrix.mjs`: same orchestrator prompts on both runtimes;
115
+ opaque-ID contract holds; cross-spawn refusal; `expectsReply` +
116
+ `staleWaitThreshold` + `timeout` parity; fieldnotes mirror intact.
117
+ - Live: TUI spawn/read/close unchanged; app spawn/read/close from `hc`;
118
+ `auto` in each caller runs local.
@@ -0,0 +1,62 @@
1
+ # Tasks — 009 hc-runtime
2
+
3
+ Work in order. Phase 0 must stay green before Phase 1 starts.
4
+
5
+ ## Overnight run + testing (no reload)
6
+
7
+ - This runs overnight. The main Pi session cannot reload extensions,
8
+ so never rely on in-place reload for live verification.
9
+ - For live tests needing new code: `hc run --bg` a fresh herdr-core
10
+ agent (full `pi` path), then have that child call `shepherd_*`
11
+ (`spawn`/`delegate`/`watch`/`done`) to spawn agents. That yields
12
+ a fresh Pi session with updated code.
13
+ - Keep `npm test` green in the current session for unit checks; use
14
+ the fresh `hc` child only for live spawn/delegate/watch proof.
15
+
16
+ ## Phase 0 — Detect + setting, no behavior change
17
+
18
+ - [ ] **0.1 Add `src/runtimes/detect.ts`**
19
+ - Pure `detectCaller(): herdr-tui | hc-app | plain` from env + binary +
20
+ socket only. Unit-testable with injected env/exec.
21
+ - Cases: TUI (`HERDR_ENV=1` + `HERDR_PANE_ID` + `herdr --version`),
22
+ app (`HC_TERMINAL_ID` + `HC_TERMINAL_SOCKET` + `hc ls`),
23
+ plain, nested (innermost wins).
24
+ - No tool/result/README change.
25
+
26
+ - [ ] **0.2 Add `backend` setting (`auto` default)**
27
+ - Extend `src/core/config.ts` store + `/shepherd settings` UI with one
28
+ row: `backend: auto|herdr|hc`, default `auto`.
29
+ - User-owned precedence (project cannot force). No `shepherd_*` schema
30
+ change. Document: setting is app-side, model never decides.
31
+ - `resolveBackend(pin, caller)`: pin if `herdr|hc`, else caller mapping
32
+ (`herdr-tui->herdr`, `hc-app->hc`, `plain->reachable-or-error`).
33
+ - Pinned-but-unreachable fails cleanly with setup hint, no fallback.
34
+
35
+ - [ ] **0.3 Verify Phase 0**
36
+ - `npm test` green; existing `verify-*.mjs` untouched.
37
+ - Unit: detect matrix (TUI/app/plain/nested/missing-binary).
38
+ - Live: TUI caller still spawns TUI; app caller resolves `hc` (error
39
+ until Phase 1 implements it — must be clean refusal, not cross-spawn).
40
+
41
+ ## Phase 1 — hc spawn/delegate/watch/done
42
+
43
+ - [ ] **1.1 Scaffold `src/runtimes/hc/`**
44
+ - `hc.ts`: `isHcAvailable`, `hcExec`, `recordCreatedTerminal`,
45
+ `pruneStaleCreatedTerminals`, launch-file writer reuse.
46
+ - `runtime.ts`: `createHcRuntime(ctx)` implementing `ShepherdRuntime`
47
+ over `hc run/send/read/wait/kill`. No `herdr` import.
48
+
49
+ - [ ] **1.2 Wire resolver**
50
+ - Route `delegate/close` (1:1) through resolved runtime first; keep
51
+ spawn/message/status/read on concrete runtime with comment until
52
+ parity proven (same Phase-0 pattern as 006 task 0.3).
53
+ - Add `verify-hc-matrix.mjs`: same prompts both backends, opaque-ID
54
+ refusal (`t4`/`w1:p1` rejected), ownership refusal.
55
+
56
+ ## Phase 2 — Parity + docs + live
57
+
58
+ - [ ] **2.1 message/status/read parity** (`expectsReply`, `staleWaitThreshold`,
59
+ `timeout->blocked`, `read --lines` tail, `done`-nudge).
60
+ - [ ] **2.2 Fieldnotes check** (same `.shepherd/sessions/` bridge on both).
61
+ - [ ] **2.3 Docs + live proof** (README one row: night-pen style; live TUI
62
+ + app spawns, `auto` runs local, pins refuse cleanly).
@@ -0,0 +1,57 @@
1
+ # Intent — Unseen Watch Parity (herdr pane + hc)
2
+
3
+ ## Why this exists
4
+
5
+ Spec 007 gave the Shepherd an overnight guarantee: a tracked task that
6
+ settles with zero watchers attached is never silent — it surfaces at the
7
+ next `agent_before_settle` boundary, or as one coalesced idle wake.
8
+ Spec 009 added a second runtime (`hc`) beside Herdr panes behind one
9
+ Shepherd surface.
10
+
11
+ The guarantee currently only holds on one backend. The notice bridge
12
+ (`src/extension/unseen-completions.ts`) subscribes to the Herdr
13
+ `lifecycleRegistry.onTaskSettled` observer; the `hc` runtime
14
+ (`src/runtimes/hc/runtime.ts`) feeds the shared `unseenCompletionLedger`
15
+ directly at its own settle point instead of through an equivalent
16
+ observer — so an `hc` settle records an entry but never schedules the
17
+ coalesced idle wake, never tags `delegate-submission-failure`, and never
18
+ passes through the same `hadWatchers` gate the bridge relies on.
19
+
20
+ This spec closes that gap as a direct continuation of 009: unwatched-done
21
+ parity. `delegate` + no `watch` + child `shepherd_done` must still notify
22
+ the Shepherd via the settle boundary / coalesced idle wake on **both**
23
+ backends.
24
+
25
+ ## Who it serves
26
+
27
+ 1. **App user (hc)** — delegates to a sheep, keeps working, never calls
28
+ `shepherd_watch`. Must get the same "settled with no watcher attached"
29
+ notice the TUI user gets — at the boundary when busy, as one wake
30
+ when idle.
31
+ 2. **TUI user (herdr)** — must notice zero change. Parity means the hc
32
+ path converges onto the 007 contract, not that the Herdr path moves.
33
+ 3. **Maintainer** — one ledger, one bridge, one notice shape, two
34
+ settlement sources. No per-backend notice text, no per-backend
35
+ renderer, no `herdr_*` vs `hc_*` unseen vocabulary.
36
+
37
+ ## What success looks like
38
+
39
+ - Same orchestrator flow on both runtimes — `spawn -> delegate -> (no
40
+ watch) -> shepherd_done` — ends with the Shepherd notified: boundary
41
+ continuation when busy, exactly one `triggerTurn` wake when idle.
42
+ - A timeout and a `shepherd_done` racing each other settle exactly once:
43
+ the deadline wins, the loser's result is ignored, the work transcript
44
+ stays readable.
45
+ - Closing an agent with a pending watch cancels the task; no unseen
46
+ entry, no wake, no boundary continuation for it.
47
+ - The verify suite proves same-prompts-both-runtimes with no raw-id leak
48
+ (`t4`, `w1:p1`, socket paths never appear in a notice).
49
+
50
+ ## Guiding values
51
+
52
+ 1. **One contract, two sources.** 007's ledger + bridge semantics are the
53
+ contract. The hc runtime adopts them; they are not redefined.
54
+ 2. **Notify once, never interrupt.** Busy Shepherds learn at the boundary;
55
+ idle Shepherds get one wake. No mid-turn `steer`, no loops.
56
+ 3. **Boring.** No new tools, no schema change, no new settings, no new
57
+ deps. The fix is wiring, not machinery.
@@ -0,0 +1,172 @@
1
+ # Journal — 010 unseen-watch parity, Phase 2
2
+
3
+ ## Status — 2026-11-15
4
+
5
+ - **Scope: Phase 2 only** (matrix verification, docs, landing). Phase 0
6
+ (hc `onTaskSettled` hook) and Phase 1 (bridge via active runtime,
7
+ hc observer-owned record) are committed (`c3df761`, `5d18cac`) and
8
+ untouched by this phase — no `src` changes here.
9
+ - Branch: `feat/010-unseen-watch-parity`, off `main`.
10
+ - No auto-watch, no broker/tool/schema/settings/fieldnote changes, no new
11
+ dependencies. `src` unchanged; only `test/verify-unseen-completions.mjs`
12
+ (new matrix blocks), one cross-link comment in
13
+ `test/verify-hc-matrix.mjs`, one-row parity notes in `README.md` +
14
+ `docs/guides/tool-reference.md`, `tasks.md` checkboxes, and this journal.
15
+ - **Status: implemented and verified.** `unseen-completions:test` EXIT 0
16
+ (31 PASS, 8 new); `hc-matrix:test` EXIT 0 (73 PASS, behavior unchanged);
17
+ every other runnable suite EXIT 0 with zero FAIL; throwaway live smoke
18
+ ALL PASS on both backends. Two suites (`command-ux`, `session-boundary`)
19
+ fail identically on `main` (environment drift, pre-existing) — see
20
+ Residuals.
21
+
22
+ ## Decisions
23
+
24
+ - The hc matrix lives in the unseen suite because that file already owns
25
+ the fake-pi + isolated-ledger harness the spec demands; `hc-matrix`
26
+ keeps the ownership/id-refusal cases both suites rely on. The suites
27
+ cross-link by comment in both directions (unseen header/block header →
28
+ `verify-hc-matrix.mjs` pattern; hc-matrix header → unseen suite).
29
+ - hc settle paths are driven through `notifyHcTaskSettledObservers` —
30
+ the exact function Phase 0 exported "so observer parity is
31
+ unit-testable without a live terminal" — subscribed via the production
32
+ `subscribeToTaskSettlements` seam (both registries) in the bridge
33
+ block, and via direct `onTaskSettled` capture with isolated ledgers in
34
+ the matrix block. No live spawn anywhere in the committed tests.
35
+ - Same-prompts parity is asserted on normalized formatter output
36
+ (`shepherd-(task|agent)-…` → placeholder): the Herdr side settles a
37
+ real isolated `LifecycleRegistry`, the hc side fires the real observer
38
+ call with the same prompt/summary/label, and both must produce
39
+ byte-identical notices.
40
+ - Race/close need no new machinery (spec §3/§4): already-settled guards
41
+ make the second settle a no-op and `cancelled` is ledger-excluded, so
42
+ the matrix asserts the guards exist on both paths (source-text parity
43
+ check, same precedent as the hc-matrix blocked-copy check) plus
44
+ ledger-level first-wins/single-winner and
45
+ resolve-then-cancelled/clearForAgent behavior; close-result reporting
46
+ (`clearForAgent` + `clearedUnseenCompletions`) is asserted against the
47
+ shared `shepherd.ts` close branch that serves both backends.
48
+ - Docs stay one row per location, where 007 documented the notice:
49
+ README `### Delegate, then watch` paragraph + tool-reference
50
+ `shepherd_watch` table row and entry paragraph.
51
+
52
+ ## Log
53
+
54
+ - 2026-11-15: read spec/plan/tasks + Phase 0/1 diffs; confirmed no `src`
55
+ work remains for Phase 2 (observer hook, source tag, bridge seam, and
56
+ both close branches already in place).
57
+ - 2026-11-15: extended `test/verify-unseen-completions.mjs` (header
58
+ note, hc-runtime + `readFileSync` imports, two blocks: hc matrix —
59
+ same-prompts, no-id-leak, submission-failure, race, close — and hc
60
+ bridge seam — idle wake, retrieval clear, busy boundary, all through
61
+ the production subscription with isolated ledgers and injected
62
+ 15 ms coalesce).
63
+ - 2026-11-15: one-row parity notes in `README.md` (delegate-watch
64
+ paragraph) and `docs/guides/tool-reference.md` (`shepherd_watch` row
65
+ + entry paragraph); reciprocal cross-link comment in
66
+ `test/verify-hc-matrix.mjs`; checked the three Phase 2 boxes in
67
+ `tasks.md`.
68
+ - 2026-11-15: wrote throwaway `/tmp/010-phase2-smoke.mjs` (not
69
+ committed): production singletons, default 250 ms coalesce, one
70
+ cross-backend idle burst → exactly one `triggerTurn` wake naming both
71
+ tasks; retrieval clear silent; busy settles → one boundary continuation
72
+ covering both backends; close `clearForAgent` reports ids; race keeps
73
+ the deadline winner with readable transcript. ALL PASS.
74
+ - 2026-11-15: `npm test` runs the `&&` chain, which stops at the
75
+ pre-existing `command-ux` failure; ran every remaining suite
76
+ individually instead: all EXIT 0, zero FAIL (627 PASS total across
77
+ runnable suites), except the two pre-broken suites below.
78
+
79
+ ## Landing — 2026-11-15
80
+
81
+ - Evidence at handoff: `unseen-completions:test` EXIT 0, 31 PASS
82
+ (8 new Phase 2 lines); `hc-matrix:test` EXIT 0, 73 PASS; all other
83
+ runnable suites EXIT 0, zero FAIL; live smoke ALL PASS (idle
84
+ cross-backend burst → one wake; retrieval silent; busy → one boundary
85
+ continuation; close reports; race keeps winner); `hc` backend
86
+ reachable (`hc server status` ok).
87
+ - Env limits: no `herdr` binary on this machine, so pane spawn is
88
+ impossible here — Herdr proof goes through the real singleton
89
+ registry/broker path; no model-backed child spawn (cost), so hc
90
+ settles go through the real settle-path observer. Live
91
+ spawn/delegate/watch parity was proven manually in 009 1.1; this
92
+ phase proves the settle/notify seam live through production
93
+ singletons on both backends.
94
+ - Ready to merge `feat/010-unseen-watch-parity` into `main` (no commit
95
+ made by this worker; landing commit left to the session owner).
96
+
97
+ ## Residuals (pre-existing, out of scope)
98
+
99
+ - `command-ux:test` ("shepherd command registered") and
100
+ `session-boundary:test` ("parent extension registers session_start
101
+ handlers") fail identically on `main` with this worker's changes
102
+ stashed — environment drift, not Phase 2. Untouched, as required.
103
+
104
+ ## Phase 3 — deadline drains inbox before settling timeout — 2026-11-15
105
+
106
+ - Scope: 3.1 (`src/runtimes/hc/runtime.ts` delegate `setTimeout` calls
107
+ `drainBrokerInbox()` first, settles `timed_out` only if still no
108
+ result) + 3.2 (deterministic regression block in
109
+ `test/verify-unseen-completions.mjs`, no live spawn). No other behavior
110
+ change; `delegate-submission-failure` path untouched.
111
+ - Evidence: `unseen-completions:test` EXIT 0, 34 PASS (3 new Phase 3
112
+ lines: drain-order source check, done-in-inbox wins with no timeout
113
+ entry, empty-inbox timeout as unseen + late done ignored with readable
114
+ winner); `hc-matrix:test` EXIT 0; `status:test`, `stale-wait:test`
115
+ EXIT 0. Full `npm test` chain still stops at pre-existing `command-ux`
116
+ drift (unchanged).
117
+ - Landing: Phase 0 (`c3df761`), Phase 1 (`5d18cac`), Phase 2 (`f6f976b`)
118
+ boxes now checked in `tasks.md` (implementation was committed but boxes
119
+ were stale); Phase 3 boxes checked by this worker. No commit made here;
120
+ landing commit left to the session owner.
121
+
122
+ ## Follow-up — blind-drain anomaly (live 010 smoke, 2026-11-15 ~18:15–18:25)
123
+
124
+ - Symptom: hc `task_done` + `reply` sat in `parent/inbox` ~9 min across
125
+ several status/watch drains that all reported `running`; the Phase 3
126
+ deadline timer's drain then consumed both and settled `completed`.
127
+ Separately, a fallback-key broker dir (`hc-parent-<gen>`) appeared at
128
+ 18:25:11, proving at least one runtime call ran with undefined
129
+ sessionId in the same process/generation.
130
+ - TEMP-DIAG: `src/runtimes/hc/runtime.ts` gained file-flagged tracing
131
+ (`/tmp/pi-shepherd-drain-debug.on` enables, appends to
132
+ `/tmp/pi-shepherd-drain-debug.log`): broker creation (key + rootDir),
133
+ every drain (sessionId, key, rootDir, inbox count, polled kinds),
134
+ every `applyTaskDoneEnvelope` exit (settling / no-sender /
135
+ pending-requests silent drop / rejected). All `drainDebug` calls are
136
+ no-ops when the flag is absent; suites stay deterministic. REMOVE the
137
+ helper + call sites once the anomaly is explained (do not land it).
138
+
139
+ ## Diagnosis (same day) — no blind drain; two real findings
140
+
141
+ - The "blind" status/watch drains never existed: the extension routes hc
142
+ `watch` to non-blocking `hcTaskWatcherService.watch` (no drain) and hc
143
+ `status` to `describeHcStatusView` (no drain). Only `message` and the
144
+ delegate deadline timer drain. Smoke-1 therefore waited for the timer;
145
+ smoke-2 completed fast because a `message` call drained. The live log
146
+ proved it (`drain start` appears only for message/timer drains).
147
+ - Real bug, fixed: `applyMessageEnvelope` called bare `ensureBroker()`,
148
+ minting a fallback-keyed junk broker mid-drain, hijacking the module
149
+ broker (orphaning the session mailbox for later drains) and addressing
150
+ reply relays to a store the child never polls (junk dirs `AyfED1`,
151
+ `84O93R` were the evidence). Fix: thread the drain's `active` broker
152
+ through (`applyMessageEnvelope(active, envelope)`). TEMP-DIAG fully
153
+ removed; `unseen-completions`, `hc-matrix`, `messaging` suites green.
154
+ - Open design question (not fixed): should hc watch-registration and
155
+ `describeHcStatusView` drain first so they never report stale
156
+ pending/running for already-settled tasks? Check Herdr parity
157
+ (`taskWatcherService.watch` / pane status view) before deciding.
158
+
159
+ ## Verification (same day, post-reload) — hijack fix proven live
160
+
161
+ - Smoke-3 (scout, same session): spawn → delegate → watch (pending) →
162
+ done lands in new session broker `mw96y7` → `message` drains →
163
+ `completed` via watcher, inbox drained, close clean.
164
+ - Exactly ONE new broker dir (`mw96y7`, legitimate); ZERO new
165
+ `hc-parent-*` junk dirs (previously every reply-applying drain minted
166
+ one: `AyfED1`, `84O93R`). The threaded-broker fix holds.
167
+ - Herdr parity answer: pane backend polls the parent inbox on a 250ms
168
+ background timer (`lifecycle.ts:84`); hc has no equivalent — drains
169
+ happen only in `message` and the delegate deadline. So on hc,
170
+ watch/status can report stale state indefinitely with an idle parent.
171
+ Recommendation: mirror the Herdr background poll (or drain-first
172
+ watch/status) as new spec work, not in 010.
@@ -0,0 +1,74 @@
1
+ # Plan — 010 unseen-watch parity
2
+
3
+ ## Target
4
+
5
+ Converge the hc settle path onto the 007 contract with wiring only:
6
+
7
+ ```text
8
+ src/runtimes/hc/runtime.ts onTaskSettled hook + source tag; remove direct ledger write
9
+ src/extension/unseen-completions.ts subscribe via active runtime's registry (resolveBackend),
10
+ not the Herdr import
11
+ src/core/unseen-completions.ts UNCHANGED (ledger is already runtime-neutral)
12
+ test/verify-unseen-completions.mjs + hc matrix case (same-prompts, no-id-leak, race, close)
13
+ package.json / test chain UNCHANGED (suite file already wired)
14
+ docs one-row parity note where 007 documented the notice
15
+ ```
16
+
17
+ ## Design decisions
18
+
19
+ 1. **Observer, not direct write.** The hc `settleTask` (~line 812)
20
+ currently calls `unseenCompletionLedger.record(...)` inline. Replace
21
+ with an `onTaskSettled` listener set + post-fan-out invocation
22
+ mirroring `src/runtimes/herdr/orchestration.ts` (~line 380): compute
23
+ `hadWatchers` from the hc fan-out (`notifyHcTaskWatchers`), capture
24
+ the agent handle for `agent`/`label`, carry the internal `source` tag
25
+ from `settleTask` options, invoke inside `try/catch`. The bridge then
26
+ owns the only `record` call site on each path, so `scheduleIdleWake`
27
+ fires for hc settles too — that is the actual parity fix.
28
+ 2. **Subscribe through the active runtime.** The bridge currently imports
29
+ `lifecycleRegistry` from the Herdr orchestration module. Resolve the
30
+ registry per command from the same backend resolution 009 built
31
+ (`resolveBackend`: explicit pin, else `detectCaller`), subscribing to
32
+ whichever runtime is active. Session scoping stays as-is: subscribe on
33
+ `session_start` (idempotent), release on `session_shutdown`, no
34
+ subscription without a parent session.
35
+ 3. **Ledger untouched.** `record` / `pending` / `drain` / `clear` /
36
+ `clearForAgent` / `clearAll` already encode the whole policy
37
+ (`hadWatchers === false`, `cancelled` excluded,
38
+ `delegate-submission-failure` excluded, dedupe by `taskId`). Both
39
+ observers feed it; no new states, no new API.
40
+ 4. **Race and close need no new machinery.** Already-settled guards make
41
+ the second settle a no-op; `cancelled` is already ledger-excluded;
42
+ `clearForAgent` + close-result reporting already exist. The work is
43
+ asserting both backends do it, not building it.
44
+ 5. **One worker per phase.** Implementation runs strictly sequential —
45
+ one worker per phase (Phase 0, then 1, then 2). No parallel
46
+ implementation workers: both phases touch the settle/notify seam and
47
+ would conflict. This spec task is spec-only (no `src` changes); the
48
+ rule binds the later implementation.
49
+
50
+ ## Order
51
+
52
+ Phase 0 — hc observer hook + source tag (settle-path only, bridge
53
+ unwired: no behavior change, suite green).
54
+ Phase 1 — bridge subscribes via active runtime; direct hc ledger write
55
+ removed; notice parity live on both backends.
56
+ Phase 2 — matrix verification (same-prompts, no-id-leak, timeout-vs-done
57
+ race, close-cancels-watch) + docs + live proof.
58
+
59
+ ## Open questions
60
+
61
+ 1. Where does the "active runtime's registry" handle live — return the
62
+ registry from `createHcRuntime`/`createHerdrRuntime`, or expose a
63
+ `resolveRegistry()` beside `resolveBackend`? Proposal: beside
64
+ `resolveBackend`, keeping the seven `ShepherdRuntime` methods
65
+ unchanged (007 already ruled the hook is a registry capability, not a
66
+ runtime method).
67
+ 2. Does the hc delegate-failure path settle through the same `settleTask`
68
+ internal function (so the `source` option threads trivially), or does
69
+ it need a new tag site? Proposal: same function, one options argument
70
+ — verify by reading the hc `delegateAgent` failure path in Phase 0.
71
+ 3. `verify-hc-matrix.mjs` vs `verify-unseen-completions.mjs` for the new
72
+ matrix case? Proposal: unseen suite owns it (it has the fake-pi +
73
+ isolated-ledger harness); hc-matrix keeps the ownership/id-refusal
74
+ cases. Cross-link both.