@luminascale/shepherd 0.0.0-stage → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) 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 +397 -2
  16. package/docs/README.md +26 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/installation.md +61 -0
  20. package/docs/guides/tool-reference.md +55 -0
  21. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  22. package/docs/plans/agent-labels.md +257 -0
  23. package/docs/plans/architecture.md +110 -0
  24. package/docs/plans/settings-scope.md +163 -0
  25. package/docs/plans/tool-surface-split.md +278 -0
  26. package/docs/reference/dictionary +26 -0
  27. package/docs/releasing.md +47 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  37. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  38. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  39. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  40. package/index.ts +602 -0
  41. package/package.json +112 -4
  42. package/scripts/capture-system-prompt.mjs +45 -0
  43. package/scripts/extract-pi-system-prompt.mjs +277 -0
  44. package/scripts/host-impact.mjs +74 -0
  45. package/scripts/resolve-agent.mjs +43 -0
  46. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  47. package/scripts/show-shepherd-prompt.mjs +96 -0
  48. package/scripts/verify-suites.mjs +67 -0
  49. package/specs/001-artifacts/spec.md +436 -0
  50. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  51. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  52. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  53. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  54. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  55. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  56. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  57. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  58. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  59. package/specs/005-per-workspace-settings/plan.md +230 -0
  60. package/specs/005-per-workspace-settings/spec.md +368 -0
  61. package/specs/005-per-workspace-settings/tasks.md +178 -0
  62. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  63. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  64. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  65. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  66. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  67. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  68. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  69. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  70. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  71. package/specs/008-remote-machine-sheep/intent.md +174 -0
  72. package/specs/008-remote-machine-sheep/journal.md +57 -0
  73. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  74. package/specs/009-hc-runtime/intent.md +44 -0
  75. package/specs/009-hc-runtime/plan.md +49 -0
  76. package/specs/009-hc-runtime/spec.md +118 -0
  77. package/specs/009-hc-runtime/tasks.md +62 -0
  78. package/specs/010-unseen-watch-parity/intent.md +57 -0
  79. package/specs/010-unseen-watch-parity/journal.md +172 -0
  80. package/specs/010-unseen-watch-parity/plan.md +74 -0
  81. package/specs/010-unseen-watch-parity/spec.md +191 -0
  82. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  83. package/specs/011-hc-background-poll/intent.md +57 -0
  84. package/specs/011-hc-background-poll/journal.md +95 -0
  85. package/specs/011-hc-background-poll/plan.md +87 -0
  86. package/specs/011-hc-background-poll/spec.md +141 -0
  87. package/specs/011-hc-background-poll/tasks.md +83 -0
  88. package/specs/012-steer-default/intent.md +12 -0
  89. package/specs/012-steer-default/journal.md +40 -0
  90. package/specs/012-steer-default/plan.md +7 -0
  91. package/specs/012-steer-default/spec.md +42 -0
  92. package/specs/012-steer-default/tasks.md +6 -0
  93. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  94. package/specs/013-opencode-shepherd/intent.md +59 -0
  95. package/specs/013-opencode-shepherd/plan.md +204 -0
  96. package/specs/013-opencode-shepherd/spec.md +258 -0
  97. package/specs/013-opencode-shepherd/tasks.md +263 -0
  98. package/src/core/artifact-sessions.ts +835 -0
  99. package/src/core/config.ts +329 -0
  100. package/src/core/discovery.ts +342 -0
  101. package/src/core/herdr.ts +1 -0
  102. package/src/core/host.ts +77 -0
  103. package/src/core/ids.ts +78 -0
  104. package/src/core/lifecycle.ts +1 -0
  105. package/src/core/messaging.ts +1 -0
  106. package/src/core/migration.ts +55 -0
  107. package/src/core/orchestration.ts +1 -0
  108. package/src/core/types.ts +143 -0
  109. package/src/core/unseen-completions.ts +114 -0
  110. package/src/extension/cli.ts +417 -0
  111. package/src/extension/config.ts +1 -0
  112. package/src/extension/settings-ui.ts +296 -0
  113. package/src/extension/shepherd-done.ts +768 -0
  114. package/src/extension/shepherd.ts +2548 -0
  115. package/src/extension/system-prompt.ts +38 -0
  116. package/src/extension/unseen-completions.ts +237 -0
  117. package/src/opencode/actions.ts +794 -0
  118. package/src/opencode/bridge.ts +777 -0
  119. package/src/opencode/display.ts +36 -0
  120. package/src/opencode/fieldnotes.ts +60 -0
  121. package/src/opencode/host.ts +62 -0
  122. package/src/opencode/orphans.ts +162 -0
  123. package/src/opencode/server.ts +458 -0
  124. package/src/runtimes/backend.ts +119 -0
  125. package/src/runtimes/detect.ts +102 -0
  126. package/src/runtimes/hc/hc.ts +527 -0
  127. package/src/runtimes/hc/runtime.ts +1898 -0
  128. package/src/runtimes/herdr/herdr.ts +912 -0
  129. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  130. package/src/runtimes/herdr/messaging.ts +703 -0
  131. package/src/runtimes/herdr/orchestration.ts +1583 -0
  132. package/src/runtimes/herdr/runtime.ts +224 -0
  133. package/src/runtimes/runtime.ts +133 -0
  134. package/src/runtimes/settle-observations.ts +114 -0
  135. package/test/fixtures/context-project/AGENTS.md +2 -0
  136. package/test/fixtures/home/.agents/agents/same.md +6 -0
  137. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  148. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  149. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  150. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  151. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  153. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  154. package/test/helpers/fake-clock.mjs +39 -0
  155. package/test/helpers/feature-contracts.mjs +44 -0
  156. package/test/helpers/test-utils.mjs +44 -0
  157. package/test/verify-artifact-sessions.mjs +258 -0
  158. package/test/verify-backend.mjs +297 -0
  159. package/test/verify-child-mislabel.mjs +135 -0
  160. package/test/verify-child-surface.mjs +321 -0
  161. package/test/verify-cli.mjs +197 -0
  162. package/test/verify-command-ux.mjs +100 -0
  163. package/test/verify-compat.mjs +32 -0
  164. package/test/verify-cross-host-notes.mjs +128 -0
  165. package/test/verify-delegate.mjs +161 -0
  166. package/test/verify-detect.mjs +151 -0
  167. package/test/verify-discovery.mjs +239 -0
  168. package/test/verify-done-nudge.mjs +238 -0
  169. package/test/verify-effective-prompt.mjs +98 -0
  170. package/test/verify-hc-matrix.mjs +246 -0
  171. package/test/verify-hc-poll.mjs +260 -0
  172. package/test/verify-host-docs.mjs +66 -0
  173. package/test/verify-host-impact.mjs +49 -0
  174. package/test/verify-ids.mjs +141 -0
  175. package/test/verify-launch.mjs +183 -0
  176. package/test/verify-message-routing.mjs +560 -0
  177. package/test/verify-messaging.mjs +303 -0
  178. package/test/verify-migration-notice.mjs +74 -0
  179. package/test/verify-multi-wait.mjs +42 -0
  180. package/test/verify-opencode-display.mjs +47 -0
  181. package/test/verify-opencode-fieldnotes.mjs +121 -0
  182. package/test/verify-opencode-notice.mjs +77 -0
  183. package/test/verify-opencode-nudge.mjs +116 -0
  184. package/test/verify-opencode-orphans.mjs +160 -0
  185. package/test/verify-opencode-surface.mjs +107 -0
  186. package/test/verify-packaging.mjs +82 -0
  187. package/test/verify-parent-surface.mjs +118 -0
  188. package/test/verify-phase0.mjs +95 -0
  189. package/test/verify-registry.mjs +124 -0
  190. package/test/verify-rename-migration.mjs +111 -0
  191. package/test/verify-rendering.mjs +379 -0
  192. package/test/verify-session-boundary.mjs +146 -0
  193. package/test/verify-settings.mjs +260 -0
  194. package/test/verify-stale-wait.mjs +339 -0
  195. package/test/verify-status-widget.mjs +377 -0
  196. package/test/verify-status.mjs +172 -0
  197. package/test/verify-task-completion.mjs +156 -0
  198. package/test/verify-task-failures.mjs +201 -0
  199. package/test/verify-task-mislabel.mjs +143 -0
  200. package/test/verify-task-registry.mjs +194 -0
  201. package/test/verify-task-watchers.mjs +217 -0
  202. package/test/verify-tool-schemas.mjs +120 -0
  203. package/test/verify-unseen-completions.mjs +1211 -0
  204. package/test/verify-watchers.mjs +181 -0
@@ -0,0 +1,147 @@
1
+ # Tasks: Unwatched completion notice
2
+
3
+ Work in order. A task is done only when its implementation + verification
4
+ are complete. This spec is `007-unwatched-completion-notice`
5
+ (`spec.md` contract, `plan.md` design). Related: issue #15.
6
+
7
+ ## Phase 1 — Detection + ledger (core)
8
+
9
+ - [x] **1.1 Add `src/core/unseen-completions.ts`**
10
+ - `UnseenCompletionLedger` keyed by `taskId`, entries are the structural
11
+ `UnseenSettlement` (result fields + optional `agent`/`label`),
12
+ insertion order; a queue of un-noticed settlements.
13
+ - `record(result, { hadWatchers, agent?, label?, source? })` adds only
14
+ when `hadWatchers === false`, `result.status !== "cancelled"`,
15
+ `source !== "delegate-submission-failure"`, and no entry exists;
16
+ returns whether a new entry was added.
17
+ - `pending()`, `drain(ids)`, `clear(ids): string[]`,
18
+ `clearForAgent(agentId): string[]`, `clearAll()`.
19
+ - Pure module: no `@earendil-works/*`, `src/runtimes/`, or
20
+ `src/extension/` imports; export the class and a
21
+ `unseenCompletionLedger` singleton (mirroring `taskWatcherService`).
22
+
23
+ - [x] **1.2 Add the settlement observer to the task registry**
24
+ - `onTaskSettled(listener): () => void` in
25
+ `src/runtimes/herdr/orchestration.ts`; listener receives
26
+ `(result, { hadWatchers, agent?, label?, source? })`, with `result`
27
+ passed as a shallow copy.
28
+ - `hadWatchers` is true only when at least one watcher callback actually
29
+ ran for the settlement (set inside the existing fan-out); capture the
30
+ agent handle for `agent`/`label` in the same place.
31
+ - `settleTask` takes an optional internal options argument carrying
32
+ `source`; `src/runtimes/herdr/lifecycle.ts` `delegateAgent` failure path
33
+ passes `source: "delegate-submission-failure"`.
34
+ - Listeners run after the fan-out, inside `try/catch`; observer failure
35
+ cannot affect settlement; no listener = identical behavior.
36
+ - Fires only on an actual transition into a terminal state; legacy
37
+ prompt settlements are not observed.
38
+ - Document the hook in the code as part of the runtime contract so the
39
+ durable runtime (spec 006 Phase 1+) implements it identically.
40
+
41
+ - [x] **1.3 Core cases in `test/verify-unseen-completions.mjs`**
42
+ - Create the suite file with ledger + observer cases first (run it
43
+ directly; chain wiring happens in 3.1).
44
+ - Ledger: cancelled exclusion, had-watchers exclusion,
45
+ delegate-submission-failure exclusion, dedupe, insertion order, drain,
46
+ `clear`/`clearForAgent` returning ids, `clearAll`.
47
+ - Observer: settle with watcher → `hadWatchers: true`; without → `false`
48
+ plus `agent`/`label`; `source` passthrough; listener throw does not
49
+ break `settleTask`; unsubscribe stops delivery.
50
+
51
+ ## Phase 2 — Notice delivery (extension)
52
+
53
+ - [x] **2.1 Session-scoped bridge + activity tracking + idle wake**
54
+ - New `src/extension/unseen-completions.ts`,
55
+ `configureUnseenCompletionBridge(pi, { coalesceMs?, ledger? })`.
56
+ - Subscribe `lifecycleRegistry.onTaskSettled` on `session_start`
57
+ (idempotent), release on `session_shutdown`; no subscription without a
58
+ parent session.
59
+ - `session_start`/`agent_settled` → idle; `agent_start` → busy; transition
60
+ to idle re-checks pending entries (aborted/errored runs still get one
61
+ later wake); prefer `ctx.isIdle()` when the captured lifecycle context
62
+ exposes it.
63
+ - `record()` while idle schedules one debounced flush
64
+ (`UNSEEN_NOTICE_COALESCE_MS = 250`); a burst sends exactly one
65
+ `pi.sendMessage(notice, { triggerTurn: true })` and drains after the
66
+ call returns.
67
+ - Timer firing while busy is a no-op; flush no-ops without a
68
+ `pi.sendMessage` function; synchronous send failure leaves entries
69
+ pending (no unbounded retry).
70
+
71
+ - [x] **2.2 Boundary continuation**
72
+ - `pi.on("agent_before_settle", event)`: only when
73
+ `event.outcome === "completed"` and pending entries exist — build one
74
+ `custom_message` entry, drain those ids, return
75
+ `{ entries: [entry], continue: true }`. No pre-entry
76
+ `event.context.canContinue` check: pi commits the drafts first and then
77
+ decides, so the pre-entry snapshot is not authoritative (#16).
78
+ - Aborted/errored outcomes return nothing; entries stay pending.
79
+ - Loop guard: drained entries never re-notify; a second boundary with no
80
+ new entries returns `undefined`.
81
+
82
+ - [x] **2.3 Notice content + renderer**
83
+ - One formatter (exported for tests) producing the spec's text: header,
84
+ `- <taskId> (<agent>[, "label"]): <status> — <summary|error>` lines,
85
+ and `Full results: shepherd_watch({ id: [ "id", ... ] })`.
86
+ - `details: { taskIds, settlements }` (not `completions`, which collides
87
+ with the generic collapsed formatter); export
88
+ `renderShepherdNotification` from `src/extension/shepherd.ts` and
89
+ register `shepherd.task.unseen` with it plus the notice formatter.
90
+
91
+ - [x] **2.4 Clearing wiring**
92
+ - `src/extension/shepherd.ts` `watch` action:
93
+ `unseenCompletionLedger.clear(registration.taskIds)` after
94
+ `taskWatcherService.watch(taskIds)` — the authoritative retrieval
95
+ clear. Do not add clearing to the watcher notifier (late watch
96
+ deliveries never reach it).
97
+ - `close` action: `clearForAgent(handle.id)` after a successful
98
+ `runtime.close`; report dropped task ids in the tool result when any.
99
+ - `session_shutdown` clears timers, observer subscription, and the
100
+ ledger; `session_start` clears stale entries before going idle.
101
+
102
+ - [x] **2.5 Wire the bridge in `index.ts`**
103
+ - Call `configureUnseenCompletionBridge(pi)` after the
104
+ `PI_SHEPHERD_SESSION` guard and `registerShepherdTools(pi)`
105
+ (`index.ts` ~447). Not inside `registerShepherdTools`: six suites pass
106
+ fake pi objects without `on` and with renderer allow-lists there.
107
+ - No tool schema, prompt, settings, or message-delivery changes for
108
+ watchers.
109
+
110
+ ## Phase 3 — Verification, docs, landing
111
+
112
+ - [x] **3.1 Finish `test/verify-unseen-completions.mjs` + wiring**
113
+ - Add bridge cases with a fake pi surface (capture `on`,
114
+ `registerMessageRenderer`, `sendMessage` like
115
+ `test/verify-parent-surface.mjs`): idle burst → exactly one
116
+ `triggerTurn` notice and no duplicates; busy settle → one boundary
117
+ result with `continue: true`; second boundary → `undefined`; `aborted`
118
+ outcome → none; completed boundary with `canContinue: false` →
119
+ continues; late `watch` clears; close clears and reports; renderer
120
+ registered; missing `sendMessage` never throws; `session_shutdown`
121
+ unsubscribes.
122
+ - Inject small `coalesceMs` and an isolated ledger for determinism.
123
+ - Register `unseen-completions:test` in `package.json` and append it to
124
+ the `test` chain.
125
+
126
+ - [x] **3.2 Full suite untouched and green**
127
+ - `npm test` with `PI_*`/`HERDR_*` unset: all existing suites + the new
128
+ script pass; no existing test file modified.
129
+
130
+ - [x] **3.3 Docs**
131
+ - README `### Delegate, then watch`: unwatched settlements surface at the
132
+ next settle boundary, or as one wake when the Shepherd is idle; the
133
+ notice names `shepherd_watch` for retrieval.
134
+ - `docs/guides/tool-reference.md`: same note on the `shepherd_watch`
135
+ entry; reiterate that `shepherd_watch` retrieves already-settled tasks
136
+ synchronously.
137
+ - Fix the pre-existing "delivered as follow-ups" wording for
138
+ `shepherd_watch` (`docs/guides/tool-reference.md` and the tool
139
+ description in `src/extension/shepherd.ts` ~1570) to match the actual
140
+ `steer` delivery.
141
+
142
+ - [x] **3.4 Live smoke + journal**
143
+ - Throwaway script (not committed): delegate to a real agent with **no**
144
+ watch; the boundary notice appears with the retrieval command; the
145
+ result is retrievable; no duplicate notice follows.
146
+ - Record scope, evidence, and the landing note in `journal.md` before
147
+ merging; note the branch name (`feat/007-unwatched-completion-notice`).
@@ -0,0 +1,174 @@
1
+ # Intent — Sheep on another machine (remote Herdr)
2
+
3
+ ## Why this exists
4
+
5
+ Herdr stopped being a single-machine tool before pi-shepherd noticed. The
6
+ CLI now exposes saved SSH profiles (`herdr machine add|list|status`) and a
7
+ machine-scoped command form (`herdr --machine <label-or-id> <command>`), so
8
+ a pane, a tab, a workspace, and an agent can all live on a machine other
9
+ than the one the Shepherd runs on. This box already has two profiles
10
+ configured.
11
+
12
+ pi-shepherd is now the only part of the stack that assumes one computer:
13
+ `pane split --cwd "$PWD"`, a local broker directory, local absolute launch
14
+ files, a local pane registry. Everything a user actually wants from two
15
+ machines — "put the heavy build on the desktop", "run the overnight suite
16
+ where the repo is", "keep my laptop cool while the GPU box works" — is
17
+ already possible by hand, and is abandoned the moment you want a shepherd
18
+ watching.
19
+
20
+ This spec exists to make machine placement an attribute of a sheep instead
21
+ of a fork in the mental model.
22
+
23
+ ## What already holds — do not rebuild it
24
+
25
+ - **Herdr owns the wire.** Machine profiles, SSH credentials, session
26
+ names, and reconnect behavior are Herdr's job. We address a machine by
27
+ its Herdr profile label or id, never by a raw `ssh` target of our own.
28
+ - **The runtime contract is already backend-neutral.** `src/runtimes/runtime.ts`
29
+ exists precisely so a second substrate can sit under the same opaque,
30
+ session-scoped ids (`specs/006-dual-runtime-herdr-durable`).
31
+ - **Four operations are cross-machine for free** once the `--machine` prefix
32
+ exists: spawn placement, `status`, `read`, and `close`. So is the status
33
+ widget's notion of agent state (`herdr --machine m agent list`).
34
+ - **The envelope layer is transport-shaped, not filesystem-shaped.**
35
+ `src/runtimes/herdr/messaging.ts` keeps envelopes self-describing
36
+ (schema version, session, broker, message, sender, target), authenticates
37
+ children with a token, publishes atomically, records acknowledgements,
38
+ dead-letters malformed mail, and requires idempotent handlers. At-least-once
39
+ delivery over an unreliable link is therefore an existing property, not a
40
+ new problem.
41
+
42
+ ## The one thing that is not free
43
+
44
+ The broker is a **local filesystem** with a 250 ms child-side inbox poll,
45
+ and the launch path writes **local absolute paths** into the child (task
46
+ file, system prompt file, session file, and the `-e` path of the
47
+ `shepherd-done` sidecar). A remote pane can read none of them.
48
+
49
+ That single fact decides the whole shape of this work: pane control goes
50
+ over Herdr's existing SSH channel, but **coordination needs its own
51
+ transport**, and the transport is the only genuinely new subsystem here.
52
+
53
+ ## Direction we intend (not a design lock)
54
+
55
+ An **SSH relay in the direction we already have** — parent → remote —
56
+ layered beneath the existing envelope code. The contract, and every check
57
+ that proves it, is in [prerequisites.md](prerequisites.md).
58
+
59
+ - Each side keeps a normal, local broker. Envelopes are the wire format;
60
+ the relay only moves them, so envelope semantics are implemented once.
61
+ - The parent drives the loop per machine: push unsent mail into the remote
62
+ inbox, pull new mail from the remote outbox, acknowledge what was
63
+ delivered. The child's existing 250 ms inbox poll stays local and never
64
+ touches the network.
65
+ - **The sheep machine never needs SSH to the shepherd.** No reverse
66
+ credential, no listener on the parent, no tunnel to supervise. A
67
+ parent-opened `ssh -N -R` tunnel or a `restrict`ed key is an opt-in
68
+ latency optimisation, not a prerequisite.
69
+ - **Launch assets travel as content**, written to a remote path the parent
70
+ chooses. Choosing that path is what makes the remote mailbox addressable
71
+ at all.
72
+ - **Install method is not part of the identity.** The remote instance
73
+ self-reports through a manifest (package version, protocol version,
74
+ capabilities, sidecar path, agent dir), so npm, git, a dev clone, `-e`,
75
+ and Nix-store paths all resolve the same way.
76
+ - **Prerequisite, not optional:** the remote machine has `pi` plus the
77
+ `shepherd-done` sidecar. "A tracked task settles only through an explicit
78
+ child `shepherd_done`" is load-bearing; without the sidecar a remote
79
+ sheep's task can only ever time out.
80
+ - **Herdr as a nudge, never as the channel.** `herdr --machine m pane
81
+ send-keys` can tell a remote child "mail is waiting, poll now". It types
82
+ into a TUI, so it must never carry the message itself.
83
+
84
+ ## Phasing
85
+
86
+ 1. **Placement without coordination.** Machine inventory surfaced next to
87
+ `herd`; `machine add` runs the preflight and records a verified machine;
88
+ `machine` accepted as a spawn attribute; `status`/`read`/`close` working
89
+ cross-machine; `delegate` and `message` refused with a clear, specific
90
+ error. The registry key becomes `(machine, agentDir, paneId)` first.
91
+ 2. **Coordination.** Parent-driven SSH relay under the existing envelope
92
+ layer, gated by the wire handshake in
93
+ [prerequisites.md](prerequisites.md); `delegate`/`message`/`watch` reach
94
+ parity for remote sheep.
95
+ 3. **Comfort.** Optional reverse tunnel or wake nudge, multi-machine widget
96
+ polling, and an explicit decision about fieldnotes for remote sheep.
97
+
98
+ ## Who it serves
99
+
100
+ 1. **Laptop orchestrator, desktop worker.** The Shepherd stays where the
101
+ human is; the heavy sheep live where the CPU is.
102
+ 2. **Long-running remote work.** The suite runs where the repo and its
103
+ secrets already are, and the answer comes back to the same result blocks.
104
+ 3. **Maintainer (us).** One tool surface. `machine` is a spawn attribute,
105
+ not a second universe of `remote_*` tools, and machine support costs
106
+ nothing when it is unused.
107
+
108
+ ## What success looks like
109
+
110
+ - Adding a machine is one line the user already has in Herdr, then
111
+ `/shepherd spawn worker --machine eos-ext` behaves like any other spawn:
112
+ same opaque id, same `call:`/`return:`/`details:` result, same lifecycle.
113
+ - `shepherd herd` shows which machine each sheep is on, and `status`,
114
+ `read`, and `close` behave identically for local and remote sheep.
115
+ - A remote sheep asks the Shepherd a question mid-task and receives a
116
+ correlated reply; `shepherd_done` remains the only terminal outcome.
117
+ - Losing the SSH link turns into a visible terminal failure — never a
118
+ silent hang, and never a fabricated completion.
119
+ - A local-only user notices nothing: no new dependency, no new config, no
120
+ SSH key required to run pi-shepherd as it runs today.
121
+
122
+ ## Guiding values
123
+
124
+ 1. **Herdr owns machines.** Profiles, credentials, and session naming stay
125
+ in Herdr. We consume its inventory; we do not grow a parallel SSH config.
126
+ 2. **One surface, one id space.** Machine is an attribute of spawn. Opaque
127
+ ids stay opaque. A pane id from another machine is never more valid as a
128
+ handle than a local one.
129
+ 3. **Fail loud, fail closed.** An unreachable machine is a terminal
130
+ outcome, not a pending one.
131
+ 4. **Local by default.** No behavior change, no new dependency, no new
132
+ credential for the single-machine install.
133
+
134
+ ## Deliberate temptations to resist
135
+
136
+ - **Shared mount (sshfs/NFS) as "the cheap way."** It preserves the 250 ms
137
+ poll unchanged, and in exchange the remote host can read and rewrite the
138
+ broker directory and its tokens, and a stalled mount blocks the parent
139
+ poll instead of failing it.
140
+ - **The child's TUI as the message channel.** Lossy, unaddressable, no
141
+ metadata, and it collides with approval prompts.
142
+ - **Adding the reverse SSH direction by default.** It buys latency the
143
+ parent-driven pull loop already provides, and costs a credential on the
144
+ orchestrating machine.
145
+ - **Guessing remote install paths**, or letting an npm-shaped layout become
146
+ part of the identity.
147
+ - **Trusting the SSH key alone** to authorize an agent id.
148
+ - **Silently syncing agent definitions or fieldnotes** to remote machines.
149
+ Each is a trust decision about which repo content may define what a sheep
150
+ does, and remote repo content feeding a locally user-owned gate is a real
151
+ regression, not a convenience.
152
+ - **250 ms polling over SSH** fanned out across every remote sheep.
153
+ - **Reading agent state as completion.** `idle`/`done` from a remote list is
154
+ visibility, not a result.
155
+
156
+ ## Open questions
157
+
158
+ Transport direction, version skew, and install resolution are specified in
159
+ [prerequisites.md](prerequisites.md). What remains genuinely open:
160
+
161
+ - Per-machine default working directory. Herdr profiles deliberately carry
162
+ no cwd, so this must be ours, and validated on the far side (preflight
163
+ P8).
164
+ - Model inheritance when the remote machine lacks the parent's provider.
165
+ - Clock skew against envelope `deadlineAt` and `completedAt`.
166
+ - Fieldnotes for remote sheep: shared, mirrored, or explicitly unavailable.
167
+ - What a repo-controlled remote `.shepherd/config.json` is allowed to
168
+ influence given the project-agent gate is user-owned and local.
169
+ - Ownership and pruning when a machine is powered off at prune time.
170
+
171
+ ## When we are done
172
+
173
+ We can delete this file's doubts: placement stopped being a decision about
174
+ which tool the user reaches for, and became one flag on the same sheep.
@@ -0,0 +1,57 @@
1
+ # Journal — 008 sheep on another machine (remote Herdr)
2
+
3
+ ## Status — 2026-10-22
4
+
5
+ - **Scope: specification only.** No code, no settings, no tool-surface
6
+ change. `specs/008-remote-machine-sheep/` holds `intent.md` and
7
+ `prerequisites.md`; there is no `spec.md`, `plan.md`, or `tasks.md` yet.
8
+ - Nothing is implemented: no `machine` spawn attribute, no relay, no
9
+ preflight, no instance manifest, no registry key change.
10
+ - Landed on `main` as documentation, not on a feature branch.
11
+ - **Exit condition for this stage:** intent (why, who, success, values,
12
+ temptations) and the remote contract (transport direction, version skew,
13
+ install resolution, preflight, rejected alternatives) are written down and
14
+ mutually consistent.
15
+
16
+ ## Decisions
17
+
18
+ - Transport is **parent → remote push/pull**, not child → parent. Herdr's
19
+ `machine add` already establishes that direction, so the sheep machine
20
+ never needs SSH to the shepherd: no reverse credential, no listener on the
21
+ orchestrator, no tunnel to supervise. A parent-opened `ssh -N -R` tunnel or
22
+ a `restrict`ed key is an opt-in latency optimisation, never a prerequisite.
23
+ - Launch assets (script, task, system prompt, session) travel as **content**
24
+ to a **parent-chosen** remote path. Choosing that path is what makes the
25
+ remote mailbox addressable at all.
26
+ - The child is launched with the **remote's own** sidecar path
27
+ (`-e <remoteSidecarPath>`) — not the parent's absolute path, and not the
28
+ remote's auto-loaded package. This keeps the child surface identical to
29
+ local: sidecar only, so `shepherd_message` + `shepherd_done`, rather than
30
+ silently granting remote sheep the full `spawn`/`delegate`/`close` surface.
31
+ - **Package version is informational; the wire protocol gates.** Envelopes
32
+ already carry `schemaVersion: 1` and reject anything else, and today a
33
+ mismatch dead-letters the envelope so the task hangs to its timeout.
34
+ Mismatch must be refused at `delegate`, with a capability list alongside the
35
+ protocol version.
36
+ - **Install method is not part of the identity.** The extension self-reports
37
+ through `$PI_CODING_AGENT_DIR/pi-shepherd/instance.json`, so npm, git, a dev
38
+ clone, `-e`, and Nix-store paths resolve the same way. Addressing becomes
39
+ `(machine, agentDir)`; the ownership key becomes
40
+ `(machine, agentDir, paneId)`.
41
+ - Provisioning mirrors `herdr machine add`: probe, print the exact install
42
+ line, require interactive approval, round-trip the mailbox, record
43
+ `verifiedAt`. No silent remote install, no silent agent or fieldnotes sync.
44
+
45
+ ## Deliberately not decided
46
+
47
+ Per-machine default cwd policy, remote model inheritance when the machine
48
+ lacks the parent's provider, clock skew against envelope `deadlineAt` /
49
+ `completedAt`, fieldnotes for remote sheep, what a repo-controlled remote
50
+ `.shepherd/config.json` may influence, and pruning while a machine is powered
51
+ off. These stay in `intent.md` until there is code to argue with.
52
+
53
+ ## Next
54
+
55
+ `spec.md` for the public surface (`machine` spawn attribute, `herd` and
56
+ `machine status` output, refusal errors), then `plan.md`/`tasks.md` for phase 1
57
+ — inventory, preflight, and the registry key — before any relay work starts.
@@ -0,0 +1,219 @@
1
+ # Prerequisites — what a sheep machine must provide
2
+
3
+ Companion to [intent.md](intent.md). The intent says a sheep may live on
4
+ another machine; this file fixes the **contract** that makes that safe: what
5
+ the remote side must offer, what pi-shepherd refuses to require, and how each
6
+ claim is *verified* rather than assumed.
7
+
8
+ Four questions drove this file, and each has a settled answer:
9
+
10
+ 1. What if the sheep machine cannot reach the shepherd over SSH?
11
+ 2. What if the pi-shepherd versions differ?
12
+ 3. What if it is installed differently (npm, git, clone, `-e`, Nix)?
13
+ 4. How do we prove any of the above before a task is delegated?
14
+
15
+ The governing rule: **a claim that cannot be round-tripped is not a
16
+ precondition, it is a hope.** Every item below ends in an observable check
17
+ with a specific failure message.
18
+
19
+ ---
20
+
21
+ ## 1. Transport direction — the sheep never needs SSH to the shepherd
22
+
23
+ Herdr's `machine add` already establishes exactly one direction: **parent →
24
+ remote** (that is how pane, agent, and workspace commands reach the remote
25
+ server). So do not add the opposite direction. Invert the relay.
26
+
27
+ - Both brokers stay local to their own machine. Nothing is shared, nothing is
28
+ mounted.
29
+ - The parent drives one loop per machine that owns live sheep:
30
+ - **push** unsent envelopes into the remote inbox,
31
+ - **pull** new envelopes from the remote outbox,
32
+ - **ack** by moving/removing the delivered file.
33
+ - The child's 250 ms inbox poll (`src/extension/shepherd-done.ts`) stays local
34
+ and unchanged. The child never touches the network. This is the property
35
+ that makes the design cheap: one implementation of envelope semantics, two
36
+ transports.
37
+ - **No reverse credential**, no listener on the parent, no
38
+ `authorized_keys` edit on the parent, no tunnel lifecycle to supervise.
39
+
40
+ Latency budget: a child's question reaches the shepherd within one parent
41
+ poll interval (~1 s per machine); the child receives mail within ~250 ms of a
42
+ push. That is adequate for ask-and-wait work and unacceptable for
43
+ real-time steering, which is why the reverse direction is a **latency
44
+ optimisation, not a requirement**: a parent-opened `ssh -N -R` tunnel, or an
45
+ opt-in `restrict`ed key with a forced command pinned to one agent id. Both
46
+ stay off by default and are visible in `machine status` when enabled.
47
+
48
+ Scaling note: N machines × 1 poll each needs `ControlMaster`/`ControlPersist`
49
+ and a poll that only runs for machines with live sheep. Unreachable machines
50
+ must **stop** being polled (and surface as unreachable), never retry silently
51
+ forever.
52
+
53
+ ## 2. Launch assets travel as content, not as paths
54
+
55
+ Today `writePiLaunchFiles` writes `launch-*.sh`, `task-*.md`, `sysprompt-*.md`
56
+ and a session file into a local `mkdtemp`, then passes absolute local paths,
57
+ including `-e <parent>/src/extension/shepherd-done.ts`. A remote pane can read
58
+ none of that. Two consequences:
59
+
60
+ - Script, task, and system prompt must be **uploaded as bytes** over the same
61
+ ssh channel and written to a remote path the **parent chooses**. Choosing
62
+ the path is what makes the mailbox addressable at all: the parent knows the
63
+ remote `PI_SHEPHERD_BROKER_DIR` because it invented it.
64
+ - The `-e` argument must be the **remote's own** sidecar path, never the
65
+ parent's (see §4). This is the single change that keeps a remote child's
66
+ capability surface identical to a local child's: sidecar only, so
67
+ `shepherd_message` + `shepherd_done` and nothing else. Relying instead on
68
+ the remote's auto-loaded package would silently give every remote sheep the
69
+ full shepherd surface (`spawn`/`delegate`/`close`) — a capability
70
+ asymmetry nobody asked for.
71
+
72
+ Transport mechanics wanted: pure POSIX shell over `ssh` to the profile's
73
+ `target`, no remote helper binary and no build step —
74
+ `cat > …/.tmp.$$ && mv` for atomic publish, length-prefixed or NUL-framed
75
+ batches for pull. Envelope sizes already bounded by `maxMessageBytes`, and
76
+ handlers are already idempotent, so a duplicated batch is safe.
77
+
78
+ ## 3. Version skew — protocol gates, package version does not
79
+
80
+ Two versions exist and only one may gate:
81
+
82
+ - **Package version** (`@luminascale/pi-shepherd` 0.5.0) — informational.
83
+ - **Wire protocol** — already implicit: envelopes carry `schemaVersion: 1`,
84
+ and `src/runtimes/herdr/messaging.ts` rejects anything else.
85
+
86
+ Today's mismatch failure mode is the worst one available: an invalid envelope
87
+ is moved to `rejected/`, the child never learns, and the task hangs until
88
+ timeout. Therefore:
89
+
90
+ - Handshake before work: `protocolVersion` plus a **capability list**
91
+ (`mailPull`, `ackByMarker`, `steer`, …). A scalar breaks on the first
92
+ optional feature; a list does not.
93
+ - Accept N/N-1 and refuse the rest, at `delegate` time, with an actionable
94
+ remedy — never at completion.
95
+ - **Treat the child as the weak side.** An ancient remote sidecar must be able
96
+ to answer "I am protocol 0"; silence is a failed preflight, not a pending
97
+ task.
98
+ - What actually has to move together, and therefore belongs under the protocol
99
+ number: envelope shape, ack semantics, the child tool names
100
+ (`shepherd_message`, `shepherd_done`), the `PI_SHEPHERD_*` environment
101
+ contract, and the sidecar load path. Cosmetic releases must not bump it.
102
+ - Locally, version lockstep is free (`-e <parent's own path>`). Cross-machine
103
+ drift is a **new class of bug**, so `verify-compat.mjs` (which checks the
104
+ *surface*) needs a sibling that checks the *wire*: parent-v1 ↔ child-v2
105
+ fixtures, both directions.
106
+
107
+ ## 4. Install resolution — ask the machine, never compute a path
108
+
109
+ No path guessable from the parent works: npm lands "under the Pi npm
110
+ directory", git clones reconcile to a ref, a dev clone lives in
111
+ `~/.pi/agent/extensions/pi-shepherd`, `-e` is a one-off, and `PI_PACKAGE_DIR`
112
+ exists precisely because Nix/Guix store paths are arbitrary. The package has
113
+ no `bin`, so `which pi-shepherd` is not an option either.
114
+
115
+ Instead, the extension knows its own root (`import.meta.url`) and its agent
116
+ dir (`PI_CODING_AGENT_DIR`), so it writes an **instance manifest** at load:
117
+
118
+ ```json
119
+ {
120
+ "packageVersion": "0.5.0",
121
+ "protocolVersion": 1,
122
+ "capabilities": ["mailPull", "ackByMarker"],
123
+ "piVersion": "1.4.0",
124
+ "extensionRoot": "/…/pi-shepherd",
125
+ "sidecarPath": "/…/pi-shepherd/src/extension/shepherd-done.ts",
126
+ "agentDir": "/home/u/.pi/agent",
127
+ "pid": 1234,
128
+ "startedAt": 0
129
+ }
130
+ ```
131
+
132
+ Stored at `$PI_CODING_AGENT_DIR/pi-shepherd/instance.json`. One read-only
133
+ `ssh target cat …` then answers *installed? which version? where?* identically
134
+ for npm, git, clone, `-e`, and Nix. **Install method stops being part of the
135
+ identity.**
136
+
137
+ Two consequences:
138
+
139
+ - **Addressing is `(machine, agentDir)`**, not `machine`. One host can carry
140
+ two installs (npm copy plus a dev clone) or two agent dirs, and those are
141
+ distinct shepherds. The ownership registry key must become
142
+ `(machine, agentDir, paneId)` before any of this lands; today `CreatedPane`
143
+ is keyed by a bare `paneId`, which collides across machines because pane ids
144
+ (`w1:p1`) are per-session-per-machine.
145
+ - A **stale manifest** is normal (last shutdown leaves it behind), so treat it
146
+ as a hint plus a liveness check, not as truth: `pid` + `startedAt` let the
147
+ probe distinguish "installed, idle" from "installed, running".
148
+
149
+ ## 5. Provisioning — approved once, verified every time
150
+
151
+ Mirror the model Herdr already uses for itself: `herdr machine add` prepares
152
+ the remote installation and *missing or incompatible installations require
153
+ approval in an interactive terminal.*
154
+
155
+ `shepherd machine add <herdr-profile>` should:
156
+
157
+ 1. Probe (§6). Print exactly what is missing and the exact fix, e.g.
158
+ `pi install npm:@luminascale/pi-shepherd@0.5.0`.
159
+ 2. Offer to run it; never run it silently. A remote pi package is code
160
+ execution in the user's remote shell, and remote sheep already execute
161
+ remote repo content.
162
+ 3. Round-trip the mailbox and only then record
163
+ `{machine, agentDir, protocolVersion, sidecarPath, cwd, verifiedAt}`.
164
+ 4. Re-verify on `machine status`, and re-probe at `spawn` when `verifiedAt` is
165
+ stale.
166
+
167
+ Never auto-sync agent definitions or fieldnotes. Each is a trust decision
168
+ about which repo content may define what a sheep does.
169
+
170
+ ## 6. Preflight checklist
171
+
172
+ Cheap, ordered, each step with a specific remedy. Blocking steps must block
173
+ `delegate`; advisory steps only warn.
174
+
175
+ | # | Check | How | Failure means |
176
+ |---|---|---|---|
177
+ | P1 | Machine known and enabled | `herdr machine list --json` → `enabled: true` | "run `herdr machine add <target>`" |
178
+ | P2 | SSH reachable parent → remote | one `ssh <target> true` | "machine unreachable; nothing was spawned" |
179
+ | P3 | Remote `pi` present and new enough | `pi --version` vs minimum | "remote pi too old for `-e` TypeScript sidecar" |
180
+ | P4 | pi-shepherd installed remotely | read `instance.json` | "install `@luminascale/pi-shepherd@<v>` on `<machine>`" |
181
+ | P5 | Protocol compatible | manifest `protocolVersion` ∈ window | "machine speaks protocol 2, this shepherd 1" |
182
+ | P6 | Sidecar readable | `ssh <target> test -r <sidecarPath>` | "install incomplete; reinstall the package" |
183
+ | P7 | Mailbox round trip | push envelope, pull it back, ack | "no working mail route; using tunnel or refusing `delegate`" |
184
+ | P8 | cwd exists remotely | `ssh <target> test -d <cwd>` | "per-machine cwd `<dir>` does not exist" |
185
+ | P9 | Model/provider available | advisory | warning only; herd records the substitution |
186
+
187
+ P4/P5/P6 replace what would otherwise be a **30 s `herdr agent start` detect
188
+ timeout**: without them a missing remote surface shows up as an opaque agent
189
+ start failure, which is exactly the diagnosis-free outcome this list exists to
190
+ prevent.
191
+
192
+ ## 7. Rejected alternatives
193
+
194
+ - **Shared mount (sshfs/NFS) at identical paths.** Preserves the 250 ms poll
195
+ with zero new transport code, but lets the remote host read and rewrite the
196
+ broker directory and its tokens, and a stalled mount blocks the parent poll
197
+ instead of failing it.
198
+ - **Reverse SSH as the default.** Requires a credential on the *orchestrator*
199
+ that a remote compromise can use, to buy latency the pull loop already
200
+ delivers.
201
+ - **Bundling/copying the sidecar as a standalone file.** It imports
202
+ `../runtimes/herdr/messaging.ts` and `./system-prompt.ts`, and the repo has
203
+ no build step (AGENTS.md). Requiring the package is cheaper than inventing a
204
+ bundler.
205
+ - **Path discovery by guessing** (`node_modules`, `which`, `~/.pi/agent/extensions`).
206
+ Wrong for at least two supported install methods, silently wrong when two
207
+ installs coexist.
208
+ - **`herdr pane run` / `send-keys` as the message channel.** Types into a TUI:
209
+ lossy, unaddressable, collides with approval prompts. Wake signal only.
210
+ - **Silent remote install or silent agent/fieldnotes sync.**
211
+
212
+ ## 8. Still owned by intent.md
213
+
214
+ These are not settled here and must not be smuggled in by an implementation
215
+ detail: per-machine default cwd policy, model inheritance when the remote
216
+ lacks the parent's provider, clock skew against envelope `deadlineAt` /
217
+ `completedAt`, the fieldnotes decision for remote sheep, what a repo-controlled
218
+ remote `.shepherd/config.json` may influence, and pruning while a machine is
219
+ powered off.
@@ -0,0 +1,44 @@
1
+ # Intent — hc-app Runtime (Herdr TUI + hc core)
2
+
3
+ ## Why this exists
4
+
5
+ pi-shepherd is Herdr-TUI-native today (`herdr` CLI, panes/tabs/workspaces).
6
+ The Herdr app (`hc` / herdr-core terminals) is now available in the same
7
+ sessions. Users run Shepherd from either place and expect sheep to run
8
+ where they are, not cross-spawned into the other UI.
9
+
10
+ This spec adds a second runtime (`hc`) beside `herdr` behind one Shepherd
11
+ surface, with per-command auto-detect and `auto` as default.
12
+
13
+ This spec is independent from `006-dual-runtime-herdr-durable` (paused).
14
+ Same 2-runtimes-1-core pattern, different second runtime.
15
+
16
+ ## Who it serves
17
+
18
+ 1. **TUI user** — runs in `herdr` terminal, sheep appear as panes/tabs.
19
+ Must notice zero change by default.
20
+ 2. **App user** — runs in `hc` terminal (`HC_TERMINAL_ID`, `hc ls`), sheep
21
+ appear as `hc` terminals. Must get same `spawn -> delegate -> watch ->
22
+ done` flow.
23
+ 3. **Maintainer** — one tool surface, one agent format, two executors.
24
+ No `herdr_*` vs `hc_*` tool fork.
25
+
26
+ ## What success looks like
27
+
28
+ - Same orchestrator prompt runs unchanged in TUI and in app.
29
+ - Default setting `backend: auto` means: every command runs where it was
30
+ called from, unless the settings UI explicitly pins `herdr` or `hc`.
31
+ - Explicit pin is respected but fails cleanly with a hint when that
32
+ runtime is unreachable (no silent cross-spawn).
33
+ - The model never chooses a runtime. No `backend` param on any
34
+ `shepherd_*` tool. Backend lives only in settings (app side).
35
+ - `shepherd.md` + per-agent fieldnotes stay the shared memory on both.
36
+
37
+ ## Guiding values
38
+
39
+ 1. **Same shepherd, different field.** Tool names, opaque IDs, agent
40
+ Markdown, handoff habits do not fork.
41
+ 2. **Auto by default.** Detect per command, run local.
42
+ 3. **No magic / no cross-spawn.** Never spawn a TUI pane from the app
43
+ (or vice versa) unless explicitly pinned *and* reachable.
44
+ 4. **Boring.** No new deps, no migration, default stays working.