@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.
- package/.agents/agents/README.md +12 -0
- package/.agents/agents/planner.md +38 -0
- package/.agents/agents/reviewer.md +38 -0
- package/.agents/agents/scout.md +43 -0
- package/.agents/agents/worker.md +33 -0
- package/.agents/skills/smoke-test/SKILL.md +155 -0
- package/.agents/skills/smoke-test/references/forensics.md +46 -0
- package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
- package/.github/workflows/publish.yml +77 -0
- package/.pi/prompts/release.md +21 -0
- package/.prettierrc +10 -0
- package/AGENTS.md +88 -0
- package/CONTRIBUTING.md +177 -0
- package/LICENSE +201 -0
- package/README.md +424 -2
- package/docs/README.md +25 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -0
- package/docs/guides/tool-reference.md +55 -0
- package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
- package/docs/plans/agent-labels.md +257 -0
- package/docs/plans/architecture.md +110 -0
- package/docs/plans/settings-scope.md +163 -0
- package/docs/plans/tool-surface-split.md +278 -0
- package/docs/reference/dictionary +26 -0
- package/docs/releasing.md +47 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
- package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
- package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
- package/index.ts +599 -0
- package/package.json +112 -4
- package/scripts/capture-system-prompt.mjs +45 -0
- package/scripts/extract-pi-system-prompt.mjs +277 -0
- package/scripts/host-impact.mjs +74 -0
- package/scripts/resolve-agent.mjs +43 -0
- package/scripts/show-shepherd-orchestrator.mjs +58 -0
- package/scripts/show-shepherd-prompt.mjs +96 -0
- package/scripts/verify-suites.mjs +67 -0
- package/specs/001-artifacts/spec.md +436 -0
- package/specs/002-simplify-agent-orchestration/plan.md +287 -0
- package/specs/002-simplify-agent-orchestration/spec.md +323 -0
- package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
- package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
- package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
- package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
- package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
- package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
- package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
- package/specs/005-per-workspace-settings/plan.md +230 -0
- package/specs/005-per-workspace-settings/spec.md +368 -0
- package/specs/005-per-workspace-settings/tasks.md +178 -0
- package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
- package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
- package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
- package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
- package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
- package/specs/007-unwatched-completion-notice/journal.md +145 -0
- package/specs/007-unwatched-completion-notice/plan.md +186 -0
- package/specs/007-unwatched-completion-notice/spec.md +284 -0
- package/specs/007-unwatched-completion-notice/tasks.md +147 -0
- package/specs/008-remote-machine-sheep/intent.md +174 -0
- package/specs/008-remote-machine-sheep/journal.md +57 -0
- package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
- package/specs/009-hc-runtime/intent.md +44 -0
- package/specs/009-hc-runtime/plan.md +49 -0
- package/specs/009-hc-runtime/spec.md +118 -0
- package/specs/009-hc-runtime/tasks.md +62 -0
- package/specs/010-unseen-watch-parity/intent.md +57 -0
- package/specs/010-unseen-watch-parity/journal.md +172 -0
- package/specs/010-unseen-watch-parity/plan.md +74 -0
- package/specs/010-unseen-watch-parity/spec.md +191 -0
- package/specs/010-unseen-watch-parity/tasks.md +119 -0
- package/specs/011-hc-background-poll/intent.md +57 -0
- package/specs/011-hc-background-poll/journal.md +95 -0
- package/specs/011-hc-background-poll/plan.md +87 -0
- package/specs/011-hc-background-poll/spec.md +141 -0
- package/specs/011-hc-background-poll/tasks.md +83 -0
- package/specs/012-steer-default/intent.md +12 -0
- package/specs/012-steer-default/journal.md +40 -0
- package/specs/012-steer-default/plan.md +7 -0
- package/specs/012-steer-default/spec.md +42 -0
- package/specs/012-steer-default/tasks.md +6 -0
- package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
- package/specs/013-opencode-shepherd/intent.md +59 -0
- package/specs/013-opencode-shepherd/plan.md +204 -0
- package/specs/013-opencode-shepherd/spec.md +258 -0
- package/specs/013-opencode-shepherd/tasks.md +259 -0
- package/src/core/artifact-sessions.ts +835 -0
- package/src/core/config.ts +329 -0
- package/src/core/discovery.ts +342 -0
- package/src/core/herdr.ts +1 -0
- package/src/core/host.ts +77 -0
- package/src/core/ids.ts +78 -0
- package/src/core/lifecycle.ts +1 -0
- package/src/core/messaging.ts +1 -0
- package/src/core/migration.ts +55 -0
- package/src/core/orchestration.ts +1 -0
- package/src/core/types.ts +143 -0
- package/src/core/unseen-completions.ts +114 -0
- package/src/extension/cli.ts +417 -0
- package/src/extension/config.ts +1 -0
- package/src/extension/settings-ui.ts +296 -0
- package/src/extension/shepherd-done.ts +768 -0
- package/src/extension/shepherd.ts +2548 -0
- package/src/extension/system-prompt.ts +38 -0
- package/src/extension/unseen-completions.ts +237 -0
- package/src/opencode/actions.ts +794 -0
- package/src/opencode/bridge.ts +777 -0
- package/src/opencode/display.ts +36 -0
- package/src/opencode/fieldnotes.ts +60 -0
- package/src/opencode/host.ts +62 -0
- package/src/opencode/orphans.ts +162 -0
- package/src/opencode/server.ts +458 -0
- package/src/runtimes/backend.ts +119 -0
- package/src/runtimes/detect.ts +102 -0
- package/src/runtimes/hc/hc.ts +527 -0
- package/src/runtimes/hc/runtime.ts +1898 -0
- package/src/runtimes/herdr/herdr.ts +912 -0
- package/src/runtimes/herdr/lifecycle.ts +1712 -0
- package/src/runtimes/herdr/messaging.ts +703 -0
- package/src/runtimes/herdr/orchestration.ts +1583 -0
- package/src/runtimes/herdr/runtime.ts +224 -0
- package/src/runtimes/runtime.ts +133 -0
- package/src/runtimes/settle-observations.ts +114 -0
- package/test/fixtures/context-project/AGENTS.md +2 -0
- package/test/fixtures/home/.agents/agents/same.md +6 -0
- package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
- package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
- package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
- package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
- package/test/fixtures/proj/.pi/agents/same.md +6 -0
- package/test/helpers/fake-clock.mjs +39 -0
- package/test/helpers/feature-contracts.mjs +44 -0
- package/test/helpers/test-utils.mjs +44 -0
- package/test/verify-artifact-sessions.mjs +258 -0
- package/test/verify-backend.mjs +297 -0
- package/test/verify-child-mislabel.mjs +135 -0
- package/test/verify-child-surface.mjs +321 -0
- package/test/verify-cli.mjs +197 -0
- package/test/verify-command-ux.mjs +100 -0
- package/test/verify-compat.mjs +32 -0
- package/test/verify-cross-host-notes.mjs +128 -0
- package/test/verify-delegate.mjs +161 -0
- package/test/verify-detect.mjs +151 -0
- package/test/verify-discovery.mjs +239 -0
- package/test/verify-done-nudge.mjs +238 -0
- package/test/verify-effective-prompt.mjs +98 -0
- package/test/verify-hc-matrix.mjs +246 -0
- package/test/verify-hc-poll.mjs +260 -0
- package/test/verify-host-docs.mjs +35 -0
- package/test/verify-host-impact.mjs +49 -0
- package/test/verify-ids.mjs +141 -0
- package/test/verify-launch.mjs +183 -0
- package/test/verify-message-routing.mjs +560 -0
- package/test/verify-messaging.mjs +303 -0
- package/test/verify-migration-notice.mjs +69 -0
- package/test/verify-multi-wait.mjs +42 -0
- package/test/verify-opencode-display.mjs +47 -0
- package/test/verify-opencode-fieldnotes.mjs +121 -0
- package/test/verify-opencode-notice.mjs +77 -0
- package/test/verify-opencode-nudge.mjs +116 -0
- package/test/verify-opencode-orphans.mjs +160 -0
- package/test/verify-opencode-surface.mjs +107 -0
- package/test/verify-packaging.mjs +82 -0
- package/test/verify-parent-surface.mjs +118 -0
- package/test/verify-phase0.mjs +95 -0
- package/test/verify-registry.mjs +124 -0
- package/test/verify-rename-migration.mjs +111 -0
- package/test/verify-rendering.mjs +379 -0
- package/test/verify-session-boundary.mjs +146 -0
- package/test/verify-settings.mjs +260 -0
- package/test/verify-stale-wait.mjs +339 -0
- package/test/verify-status-widget.mjs +377 -0
- package/test/verify-status.mjs +172 -0
- package/test/verify-task-completion.mjs +156 -0
- package/test/verify-task-failures.mjs +201 -0
- package/test/verify-task-mislabel.mjs +143 -0
- package/test/verify-task-registry.mjs +194 -0
- package/test/verify-task-watchers.mjs +217 -0
- package/test/verify-tool-schemas.mjs +120 -0
- package/test/verify-unseen-completions.mjs +1211 -0
- 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.
|