@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,259 @@
|
|
|
1
|
+
# Tasks — Shepherd for OpenCode
|
|
2
|
+
|
|
3
|
+
`specs/013-opencode-shepherd` · draft · spec: `spec.md` · plan: `plan.md`
|
|
4
|
+
|
|
5
|
+
## Phase 1 — Engine decoupling (US5)
|
|
6
|
+
|
|
7
|
+
**Goal**: shared engine imports nothing host-specific; Pi behaves exactly
|
|
8
|
+
as before.
|
|
9
|
+
**Checkpoint**: full existing `verify-*` suites green, zero Pi behavior change.
|
|
10
|
+
|
|
11
|
+
- [x] T001 [US5] Inject agent/config directories and frontmatter parsing into `src/core/discovery.ts` and `src/core/config.ts` (no `@earendil-works` imports left in shared engine).
|
|
12
|
+
- [x] T002 [US5] Parameterize the launch-file builder (`src/runtimes/herdr/herdr.ts`) by child binary, child entry, and env-capability prefix; Pi passes today's values.
|
|
13
|
+
- [x] T003 [US5] Run all `verify-*` suites plus manual Pi spawn → delegate → watch → close; confirm green and unchanged.
|
|
14
|
+
|
|
15
|
+
## Phase 2 — OpenCode spawn and inspect (US1)
|
|
16
|
+
|
|
17
|
+
**Goal**: an OpenCode user can herd visible sheep.
|
|
18
|
+
**Checkpoint**: spawn → status → read → close works from OpenCode; unknown names and unreachable Herdr fail cleanly.
|
|
19
|
+
|
|
20
|
+
- [x] T004 [US1] OpenCode server-plugin skeleton with tool surface for `spawn`, `herd`/`agents`, `status`, `read`, `close` routed through the shared runtime resolver.
|
|
21
|
+
- [x] T005 [US1] Child boot via interactive `opencode` in pane/terminal using the parameterized builder (T002); readiness/tail reuse as-is.
|
|
22
|
+
- [x] T006 [P] [US1] Human command surface mirroring Pi's (`agents`, `herd`, `spawn`, `status`, `read`).
|
|
23
|
+
- [x] T007 [US1] Acceptance: unknown agent name, unreachable Herdr, and duplicate-label spawn all produce their specified errors.
|
|
24
|
+
|
|
25
|
+
## Phase 3 — Tracked work and messaging (US2, US3)
|
|
26
|
+
|
|
27
|
+
**Goal**: the full delegate → watch → done loop plus mid-task questions work from OpenCode.
|
|
28
|
+
**Checkpoint**: delegate while doing other work, receive completion; question → reply → resume completes.
|
|
29
|
+
|
|
30
|
+
- [x] T008 [US2] `delegate` + `watch` tools with watcher/notifier bridges and exactly-once delivery (settled results retrievable, late watchers served synchronously).
|
|
31
|
+
- [x] T009 [US2] OpenCode child `shepherd_done` tool publishing the shared `task_done` envelope (task inference, mismatch rejection, broker-unavailable error).
|
|
32
|
+
- [x] T010 [US3] Parent/peer `shepherd_message` on both sides with `expectsReply` waiting semantics, reply correlation, and the bounded done-nudge + stall escalation.
|
|
33
|
+
- [x] T011 [US2] Acceptance remainder: peer reply → resume → done end-to-end without reloads; done-nudge fires for a forgetful sheep; unknown-task done/message errors; missed deadline settles with explanation.
|
|
34
|
+
- Live 2026-11-18: A and B PASS (B after the sheep/parent-classification fix), C PASS for `shepherd_message` (the sheep-only `shepherd_done` gate is a correct refusal, not the bad-id error — see journal).
|
|
35
|
+
- Coverage check: missed deadline is engine-level shared with OpenCode (`verify-unseen-completions.mjs`); done-nudge and sheep-context unknown-task had no OpenCode coverage, so `test/verify-opencode-nudge.mjs` was added (both PASS). Full suite: 645 PASS. The handoff is complete; see the T011 journal below.
|
|
36
|
+
- The "live re-verify pending" wording in the older bullets below is superseded by journal entries 10–13 — both fixes were live-confirmed. Those bullets are kept only as a chronological record.
|
|
37
|
+
- Mechanism proven pre-restart (rose→jack reply resolved the wait; done fired the watcher). Full peer-`expectsReply` re-run pending quota reset.
|
|
38
|
+
- Post-restart "successes" were INVALID: the bench deleted the dev loader during cache-busting, so later tool output was model improvisation (t28 re-ran adapter logic via shell). Verify tool presence + side-effect artifacts (terminals, broker dirs, registry), never prose alone. Requires: loader file present, fresh server, trivial tool call first, no touches mid-test, fresh TUI sessions (TUIs hold stale catalogs across restarts).
|
|
39
|
+
- **Live T011 run, 2026-11-18 (after display fix):** sanity `shepherd agents` via tool returned 4 agents; `/shepherd agents`/`spawn` command output renders in full with no turn. **Test A PASS** — handA (`shepherd-agent-e221ed63-0ca40db9-d4b5-474a-9b36-0eb1b658c0b6`) completed `shepherd-task-e221ed63-90ac8f1e-ea03-472d-964d-331c07aabbe7`; watcher text: "Replied HAND and marked the delegated task complete." **Test B core loop completed but with two findings:** handB (`shepherd-agent-e221ed63-dea0af1a-a7f8-4232-91a9-9eb37f37bb56`) answered "My label is handB"; handA forwarded it and called `shepherd_done` completed on `shepherd-task-e221ed63-11c1e389-af86-4b61-898e-8d4ddb0c435a`. (1) handB could NOT reply via the `shepherd_message` tool: verbatim — "I'll deliver the correlated reply directly through the broker files (the tool's parent-form path can't address a peer in another session)" and "The correlated parent-form call was rejected because the peer lives in a different broker session, so I delivered the reply through the shared broker (reply envelope + parent replyReceived mirror) and relayed the answer text to handA's terminal." This is the known multi-parent broker multiplexing limit (Later), now blocking the documented peer path. (2) The watcher completion for task `11c1e389` did NOT arrive in the parent session; it appeared in **handB's** pane, while the parent received only handA's forwarded `shepherd_message` (`shepherd-message-e029df62-9911-491f-9d3a-c669d5f62044`, replyTo `shepherd-message-c607d4bd-85b7-4b6f-a6cc-1717ab660001`). **Fixed (code complete, live re-verify pending):** `src/opencode/bridge.ts` now refuses to register a sheep session as a task parent in `noteTaskParent`, refuses to notify sheep sessions in `promptParent`, and retries a transient `session.prompt` failure up to 3 times instead of silently dropping it. Regression: `test/verify-opencode-notice.mjs`. Also: the first handA id (`shepherd-agent-e221ed63-2ef15b1c-...`) was orphaned by the OpenCode server restart (in-memory registry reset; see Later reload-resilience item) — fresh spawn was required.
|
|
40
|
+
- **Finding (human T011 sanity, 2026-11-18) — FIXED, live re-verify pending:** the human `/shepherd` command listed the 4 agents correctly, but also started an assistant turn. Owner reported the invocation as `/shepherd agent`; the displayed header was `[shepherd agents]`. Root cause: `src/opencode/server.ts` command handler delivered every result via `ctx.session.prompt({ sessionID, text: ... })`; `session.prompt` posts a user message and wakes the model, so the command's own output re-entered the model and started a turn. Fix: command output now goes through `src/opencode/display.ts` → `ctx.session.prompt({ sessionID, text, resume: false })`. OpenCode's session layer skips `execution.wake()` when `resume: false`, so the result renders as a full normal message with no assistant turn. Rejected alternatives: `noReply` (v1 only — absent from the installed v2.3.0 prompt schema) and `session.synthetic` (the TUI renders synthetic messages as a single-line truncated notice using `description ?? text`, so a multi-line agent list collapsed to a bare `◈shepherd` label). Parent-session notices (`bridge.ts`) still use `session.prompt` without `resume: false` intentionally. Regression covered by `test/verify-opencode-display.mjs` (unit + source guard). Live confirmation is part of resuming the T011 handoff with a fresh server/TUI.
|
|
41
|
+
|
|
42
|
+
## Phase 4 — Shared fieldnotes (US4)
|
|
43
|
+
|
|
44
|
+
**Goal**: notes flow across delegations and across hosts.
|
|
45
|
+
**Checkpoint**: Pi sheep reads OpenCode sheep's notes and vice versa.
|
|
46
|
+
|
|
47
|
+
- [x] T012 [US4] Parent artifact-session resolution in the OpenCode adapter onto the same shared layout Pi uses.
|
|
48
|
+
- Added `src/opencode/fieldnotes.ts`: resolves/creates the parent fieldnotes
|
|
49
|
+
session with the OpenCode session id as the opaque parent identity and the
|
|
50
|
+
session cwd as the project root, using the shared engine resolver — no
|
|
51
|
+
layout duplication and no Pi adapter import. The fieldnotes setting is
|
|
52
|
+
snapshotted per `(session id, cwd)` like Pi's session-scoped setting.
|
|
53
|
+
- `spawnSheep` resolves once and threads the session into both hc and Herdr
|
|
54
|
+
runtime contexts (so the agent record and later delegates reserve notes);
|
|
55
|
+
`delegateSheep` re-resolves so a task always reserves its note. Spawn
|
|
56
|
+
results now print `fieldnote: <relative path>` when enabled.
|
|
57
|
+
- Regression: `test/verify-opencode-fieldnotes.mjs` — layout creation/reuse,
|
|
58
|
+
identity+root separation, Pi↔OpenCode resolution of the same session and
|
|
59
|
+
shared notes, disabled/session-scoped gate, and spawn/delegate wiring.
|
|
60
|
+
Full suite: 650 PASS (exit 0).
|
|
61
|
+
- [x] T013 [US4] Acceptance: sequential delegations across hosts share notes; disabled-notes mode stays off everywhere.
|
|
62
|
+
- Filesystem acceptance via `test/verify-cross-host-notes.mjs`: one opaque
|
|
63
|
+
parent identity + one project root yields exactly one
|
|
64
|
+
`.shepherd/sessions/NNNN-*` directory across sequential Pi → OpenCode and
|
|
65
|
+
OpenCode → Pi delegations, with two/three distinct finalized notes, one
|
|
66
|
+
MOC linking them, metadata reload, and no global index (spec 003 non-goal).
|
|
67
|
+
Both per-session setting gates honor `fieldnotes: false` and stay off
|
|
68
|
+
across a mid-session config flip; new sessions observe the change.
|
|
69
|
+
Full suite: 653 PASS (exit 0).
|
|
70
|
+
- Scope: the handoff is verified at the resolver/gate + artifact layer, not
|
|
71
|
+
with two live host TUIs; cross-host sharing requires both hosts to present
|
|
72
|
+
the same opaque parent identity for a project. A live two-host walkthrough
|
|
73
|
+
remains optional (see "Later").
|
|
74
|
+
|
|
75
|
+
## Phase 5 — One package, verified twice (US5, US6)
|
|
76
|
+
|
|
77
|
+
**Goal**: single installable package, per-host docs, both suites gating every change.
|
|
78
|
+
**Checkpoint**: fresh installs in each host (following only that host's docs) both herd working sheep; both suites green.
|
|
79
|
+
|
|
80
|
+
- [x] T014 [P] [US6] Manifest carries both entries (Pi extension + OpenCode plugin); install verified fresh in each host with no steps from the other host.
|
|
81
|
+
- `package.json` now declares `pi.extensions: ["./index.ts"]` and an
|
|
82
|
+
`exports` map whose root resolves to `./src/opencode/server.ts` (the
|
|
83
|
+
`Plugin.define` default export OpenCode loads via `plugins` in
|
|
84
|
+
`opencode.json`).
|
|
85
|
+
- `test/verify-packaging.mjs` packs the tarball, asserts both entry files
|
|
86
|
+
and the shared engine are shipped, installs it into an isolated consumer,
|
|
87
|
+
and checks bare `@luminascale/pi-shepherd` resolves to the OpenCode plugin
|
|
88
|
+
while the installed manifest still declares the Pi entry. Full suite:
|
|
89
|
+
657 PASS (exit 0).
|
|
90
|
+
- [x] T015 [P] [US6] README splits into per-host tracks on the first screen.
|
|
91
|
+
- New title/host-neutral intro, a "Choose your host" picker linking to
|
|
92
|
+
"Pi track" and "OpenCode track" before shared content. Each track has its
|
|
93
|
+
own install/verify steps and host-specific behavior (Pi settings menu vs
|
|
94
|
+
OpenCode file-based config and display-only command output).
|
|
95
|
+
- `test/verify-host-docs.mjs` guards the first-screen split and the OpenCode
|
|
96
|
+
`plugins` config snippet. Full suite: 657 PASS (exit 0).
|
|
97
|
+
- [x] T016 [US5] Mirrored OpenCode verification harness covering FR-001–FR-004; both harnesses run on every change.
|
|
98
|
+
- `scripts/verify-suites.mjs` derives the Pi (36 scripts) and OpenCode
|
|
99
|
+
(11 scripts) suites from `package.json`; `npm test` chains both, and a new
|
|
100
|
+
`*:test` script cannot silently escape them.
|
|
101
|
+
- `test/verify-opencode-surface.mjs` loads the real plugin module (module-load
|
|
102
|
+
smoke test) and drives `setup` with a fake host, asserting the full tool
|
|
103
|
+
family, visible-pane launch overrides, child-only completion, and
|
|
104
|
+
watcher/notice isolation (FR-001–FR-004). This absorbs the harness-hardening
|
|
105
|
+
"Later" item. Full suite: 661 PASS (exit 0).
|
|
106
|
+
- [x] T017 [US5] Release checklist: per-host impact notes; Pi-only change ships with zero OpenCode-side edits (and vice versa).
|
|
107
|
+
- `docs/releasing.md` requires both suites green, explicit per-host impact
|
|
108
|
+
lines, and the T018-before-T019 release order including the `npm deprecate`
|
|
109
|
+
pointer.
|
|
110
|
+
- `scripts/host-impact.mjs` classifies a git range (or `--files`) into
|
|
111
|
+
Pi-only / OpenCode-only / shared / docs and prints the verdict;
|
|
112
|
+
`test/verify-host-impact.mjs` covers every verdict plus the checklist.
|
|
113
|
+
- [x] T018 [US5] Farewell release on the old name: one-time migration notice (marker file; human sessions only; never in child sheep panes), README banner, final old-name publish plus `npm deprecate` with pointer to the new name. The old name gets its final notice-bearing release (`0.5.2`); the new package (`0.6.0`) is published first so the pointer is never a 404. See the revised ordering in `plan.md` and `docs/releasing.md`.
|
|
114
|
+
- `src/core/migration.ts` emits a one-time, display-only notice gated by a
|
|
115
|
+
per-host marker (`<agentDir>/pi-shepherd/migration-notice.json`). Child
|
|
116
|
+
processes (`PI_SHEPHERD_SESSION` / `SHEPHERD_TASK_ID`) never see or consume
|
|
117
|
+
it. Wired into Pi `session_start` and the OpenCode command output path;
|
|
118
|
+
README banner and the deprecated-publish/deprecate ordering added.
|
|
119
|
+
- `test/verify-migration-notice.mjs` covers once-only, per-host markers,
|
|
120
|
+
child suppression, and both host entry points.
|
|
121
|
+
- Operator note: the actual last old-name publish + `npm deprecate` remain a
|
|
122
|
+
release action documented in `docs/releasing.md`; this commit carries the
|
|
123
|
+
code/docs that must ship in it.
|
|
124
|
+
- [x] T019 [US6] Rename package to `@luminascale/shepherd` (manifest + URLs; FR-013); verify old-install → remove → new-install keeps settings and herd (SC-005).
|
|
125
|
+
- Manifest name is now `@luminascale/shepherd`; README install commands and
|
|
126
|
+
packaging tests updated. Repository URLs stay on the `pi-shepherd` repo,
|
|
127
|
+
which is unchanged. All functional identifiers stay frozen: `shepherd_*`
|
|
128
|
+
tool names, `SHEPHERD_`/`PI_SHEPHERD_` env prefixes, `pi-shepherd` user data
|
|
129
|
+
dir, and `.shepherd/config.json`.
|
|
130
|
+
- `test/verify-rename-migration.mjs` simulates old-install → remove →
|
|
131
|
+
new-install with isolated HOME and asserts settings and the created-pane
|
|
132
|
+
registry are read intact from the frozen paths. Full suite: 670 PASS
|
|
133
|
+
(pi 36 + opencode 11 scripts).
|
|
134
|
+
|
|
135
|
+
## Later
|
|
136
|
+
|
|
137
|
+
- [x] Watcher completion notices must reach only human parent sessions, never a sheep pane, and must survive a transient parent-busy failure (found in live T011, 2026-11-18). `src/opencode/bridge.ts`: `noteTaskParent` and `promptParent` both reject sheep sessions; `promptParent` retries up to 3 times with backoff and logs on exhaustion instead of silently dropping. Regression: `test/verify-opencode-notice.mjs`. **Live-verified 2026-11-18:** completion notice landed in the parent session.
|
|
138
|
+
- [x] Reload resilience — **implemented the "document orphan-reap" option** (2026-11-18). Full rehydration would require restoring opaque-id tokens, broker singletons, task deadlines, reply correlation, watcher queues, and HC generation ids across the shared engine; the supported one-parent-per-process boundary makes that a redesign. Instead, `src/opencode/orphans.ts` detects live owned panes/terminals that have no in-memory `SheepRecord` after a reload, prunes confirmed-gone entries, and emits one display-only notice per distinct orphan set (marker: `orphan-notices.json` in the host data dir; native ids never leak). The `shepherd` tool gained `action: "reap"`, which closes only transports still recorded in the ownership registries for the calling session, then clears their entries and launch dirs. Regression: `test/verify-opencode-orphans.mjs` (fake Herdr/hc, isolated HOME) covers detection, one-time notice, new-orphan notice, reap, launch-dir cleanup, and cross-session protection. **Scope:** tracked tasks/watchers do not survive a restart; orphans are reported and reaped, not reattached. README documents the behavior.
|
|
139
|
+
- [x] Multi-parent broker multiplexing — **re-evaluated 2026-11-18, closed as a
|
|
140
|
+
documented non-issue for supported flows.** The broker caches are
|
|
141
|
+
process-singletons keyed by the parent session id (Herdr
|
|
142
|
+
`ensureParentBroker`, hc `ensureBroker`), and a session switch creates a
|
|
143
|
+
new broker rootDir. Interleaving two parent sessions in one server
|
|
144
|
+
process can strand the other session's envelopes, but the whole engine
|
|
145
|
+
— not just the brokers — is one-parent-per-process: `beginSession`
|
|
146
|
+
clears watchers and retires opaque ids, the Herdr drain timer and hc
|
|
147
|
+
poller each track one key, and hc ids carry a process-wide
|
|
148
|
+
`generationId`. None of the micro-fixes work in isolation: removing the
|
|
149
|
+
cache would mint a fresh empty mailbox per call, keying by root path is
|
|
150
|
+
impossible before `createParentBroker` generates it, and a per-session
|
|
151
|
+
broker map alone would still lose watchers and one-sided drains. Sheep
|
|
152
|
+
of different parents cannot collide at the broker layer — unique
|
|
153
|
+
rootDirs, broker ids, and capability validation reject cross-parent
|
|
154
|
+
addressing. All supported flows (one parent, many sheep, peer replies,
|
|
155
|
+
done-nudge, watcher notices) are covered and live-verified. If
|
|
156
|
+
multi-parent concurrency becomes a requirement, it is a separate spec
|
|
157
|
+
covering broker maps, deterministic roots, session-keyed registries and
|
|
158
|
+
watchers, per-session timers, and capability survival — not a broker
|
|
159
|
+
patch.
|
|
160
|
+
- [x] Sheep sessions that call a parent-only tool before binding must not be permanently misclassified as parents (found in live T011 re-run, 2026-11-18: verbatim from handB — "this session was not bound as a delegated sheep session, so the tool fell back to the parent form and returned Unknown child target"). `src/opencode/bridge.ts`: `markParentSession` no-ops for known sheep, `isParentSession` returns false for known sheep, `bindChildSession` clears stale parent marks. Regression in `test/verify-opencode-notice.mjs`. **Live-verified 2026-11-18:** handB replied via `shepherd_message` (zero shell calls), handA called `shepherd_done` completed, watcher completion reached the parent.
|
|
161
|
+
- [ ] Optional live T013 walkthrough — **blocked on a product decision, not
|
|
162
|
+
on test infrastructure.** Cross-host sharing requires both hosts to
|
|
163
|
+
present the same opaque parent identity; Pi uses its session id and
|
|
164
|
+
OpenCode uses its session id, and neither public tool surface exposes an
|
|
165
|
+
identity override. `test/verify-cross-host-notes.mjs` proves the shared
|
|
166
|
+
layout works when the identity matches, but there is currently no
|
|
167
|
+
supported way to arrange that in two live host sessions. Enabling this
|
|
168
|
+
walkthrough needs a new, explicitly designed cross-host binding key
|
|
169
|
+
(on both adapters, without regressing Pi) — budget it as a separate
|
|
170
|
+
feature rather than forcing it into this handoff. Tracked as
|
|
171
|
+
[GH #19](https://github.com/MikkelKappelPersson/shepherd/issues/19).
|
|
172
|
+
- [x] Verification-harness hardening (folded into T016 + contributor notes): the OpenCode suite loads `src/opencode/server.ts` for real via `verify-opencode-surface.mjs` (a bad import can no longer sit unnoticed), and `npm test` gates both suites. The live-testing rules remain in force for human handoffs: after every adapter change reload, confirm NO "failed to load plugin" lines, run one trivial tool call, then test; never touch plugin files mid-test; never delete the dev loader without restoring it; distrust model self-reports of tool presence and assert on artifacts.
|
|
173
|
+
- [ ] Native OpenCode session runtime (no Herdr dependency) — separate effort; Path A deliberately first.
|
|
174
|
+
- [ ] OpenCode settings UI — only if the file-config default (plan Q2) proves insufficient.
|
|
175
|
+
- [x] `/shepherd` command output must not start an agent turn (found during T011 sanity, 2026-11-18). Fixed via `ctx.session.prompt({ ..., resume: false })` in `src/opencode/display.ts`; unit + source-guard regression in `test/verify-opencode-display.mjs`. **Live-verified 2026-11-18:** command output rendered in full with no assistant turn (T011 journal entry 10).
|
|
176
|
+
|
|
177
|
+
## T011 live-attempt journal (2026-11-18)
|
|
178
|
+
|
|
179
|
+
Chronological record of what was tried and what happened, so a later reader
|
|
180
|
+
does not repeat a dead end.
|
|
181
|
+
|
|
182
|
+
1. **Pi-driven bench sessions (before this day)** — `hc send` into TUIs.
|
|
183
|
+
Failed: stale tool catalogs across restarts, 100K+ token confused contexts,
|
|
184
|
+
one session faked tool results by re-running adapter code via shell.
|
|
185
|
+
Conclusion: human-driven fresh TUI only.
|
|
186
|
+
2. **Human sanity `/shepherd agent`** — listed 4 agents but started an
|
|
187
|
+
assistant turn. Root cause: command output delivered via `session.prompt`.
|
|
188
|
+
3. **Fix attempt A — `session.synthetic(..., resume: false)`** — no turn, but
|
|
189
|
+
the TUI rendered only a `◈shepherd` label (synthetic notices use
|
|
190
|
+
`description ?? text`, single-line, truncated). Abandoned.
|
|
191
|
+
4. **Fix attempt B — `session.prompt(..., resume: false)`** — full multi-line
|
|
192
|
+
output renders, no turn. Rejected `noReply` (v1-only, absent from v2.3.0
|
|
193
|
+
prompt schema). Works. Side observation: "OpenCode thinks it's working"
|
|
194
|
+
likely the busy indicator from the assistant's own reply; no pending inbox
|
|
195
|
+
rows found. Left as-is.
|
|
196
|
+
5. **Test A (after restart)** — first handA id was orphaned by the OpenCode
|
|
197
|
+
restart (in-memory registry reset). Fresh spawn, delegate, watch → PASS.
|
|
198
|
+
6. **Test B first run** — core loop completed (handB answered "My label is
|
|
199
|
+
handB"; handA called `shepherd_done`) but handB could not use
|
|
200
|
+
`shepherd_message` for the peer reply and improvised via broker files;
|
|
201
|
+
the watcher completion appeared in handB's pane, not the parent. Initially
|
|
202
|
+
attributed to multi-parent broker multiplexing.
|
|
203
|
+
7. **Fix — watcher-notice routing** — `noteTaskParent`/`promptParent` reject
|
|
204
|
+
sheep sessions; `promptParent` retries up to 3 times. Code + unit test
|
|
205
|
+
green, but not yet observable in a live run (see 9).
|
|
206
|
+
8. **Test B re-run (fresh plugin + herdr)** — handB again failed to reply via
|
|
207
|
+
`shepherd_message`, this time with a precise error: "this session was not
|
|
208
|
+
bound as a delegated sheep session, so the tool fell back to the parent
|
|
209
|
+
form and returned Unknown child target." handA stayed `waiting`, so the
|
|
210
|
+
task never settled and the watcher-notice fix could not be exercised.
|
|
211
|
+
Root cause identified: a child that called a parent-only tool before its
|
|
212
|
+
lazy session binding was permanently marked as a parent by
|
|
213
|
+
`markParentSession`; `sheepMessage` then rejected it.
|
|
214
|
+
9. **Fix — sheep/parent classification** — `markParentSession` no-ops for
|
|
215
|
+
known sheep, `isParentSession` excludes known sheep, `bindChildSession`
|
|
216
|
+
clears stale parent marks. Regression in `test/verify-opencode-notice.mjs`;
|
|
217
|
+
full suite green.
|
|
218
|
+
10. **Test B re-run after reload (SUCCESS)** — handB replied via
|
|
219
|
+
`shepherd_message` only (session export shows zero shell calls), handA
|
|
220
|
+
called `shepherd_done` completed, and the `shepherd_watcher completion`
|
|
221
|
+
notice landed in the parent session with the answer. Both fixes verified
|
|
222
|
+
live. The answer was `opencode` (the child agent's display name), which
|
|
223
|
+
the handoff explicitly accepts.
|
|
224
|
+
11. **Close-out + Test C** — both Test B sheep were closed via
|
|
225
|
+
`shepherd_close` and all Herdr sheep terminals confirmed gone; the stale
|
|
226
|
+
`created-terminals.json` bookkeeping was cleared to `[]`. Test C results:
|
|
227
|
+
- `shepherd_done({ taskId: "shepherd-task-0000-0000", status: "completed" })`
|
|
228
|
+
from the human parent returned verbatim:
|
|
229
|
+
`shepherd_done is a sheep-only tool: only the delegated sheep session may complete its task.`
|
|
230
|
+
Correct refusal, but NOT the handoff's expected "unknown" error naming
|
|
231
|
+
the bad id — that path is unreachable from a parent session, so the
|
|
232
|
+
unknown-task error needs a sheep-context call to be exercised. No crash
|
|
233
|
+
or hang.
|
|
234
|
+
- `shepherd_message({ target: "shepherd-agent-0000-0000", message: "hi" })`
|
|
235
|
+
returned verbatim: `Unknown agent id "shepherd-agent-0000-0000".
|
|
236
|
+
Lifecycle ids are scoped to this Shepherd; use the id from the latest
|
|
237
|
+
shepherd_spawn result, not an agent name, label, or pane id.` PASS.
|
|
238
|
+
12. **Coverage check + close** — existing suites cover missed deadline at the
|
|
239
|
+
shared engine level (`verify-unseen-completions.mjs`), but nothing covered
|
|
240
|
+
the OpenCode done-nudge path (`src/opencode/bridge.ts` event handler) or
|
|
241
|
+
the OpenCode sheep-context `sheepDone()` unknown-task error. Added
|
|
242
|
+
`test/verify-opencode-nudge.mjs`: fake Herdr + queued
|
|
243
|
+
`session.execution.succeeded` events assert the nudge names the task, is
|
|
244
|
+
delivered once, then escalates to the parent; a direct `sheepDone` call
|
|
245
|
+
with `shepherd-task-0000-0000` asserts the unknown-task error names the
|
|
246
|
+
bad id. Both PASS; full suite 645 PASS (exit 0). T011 ticked.
|
|
247
|
+
13. **Outcome** — all three code fixes (command display, notice routing,
|
|
248
|
+
sheep/parent classification) are live-verified; the handoff's Tests A/B/C
|
|
249
|
+
are complete. Outstanding non-blocking items remain in "Later": reload
|
|
250
|
+
resilience, multi-parent broker multiplexing (narrowed), harness
|
|
251
|
+
hardening, Phase 4/5 tasks.
|
|
252
|
+
|
|
253
|
+
## Notes
|
|
254
|
+
|
|
255
|
+
- `[P]` = parallel: different files, no dependency.
|
|
256
|
+
- `[US1]` = user story from `spec.md`; every task has one.
|
|
257
|
+
- Keep task ids stable; add new ones, do not renumber.
|
|
258
|
+
- Change code and spec together; update the plan if behavior changes.
|
|
259
|
+
- Tick a task only when its verification passes.
|