@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,115 @@
|
|
|
1
|
+
# Phase 0 Baseline
|
|
2
|
+
|
|
3
|
+
This baseline was captured before implementing the tracked-task and messaging
|
|
4
|
+
runtime. It records the current behavior that Phase 1+ work must preserve or
|
|
5
|
+
replace explicitly.
|
|
6
|
+
|
|
7
|
+
## Repository and test baseline
|
|
8
|
+
|
|
9
|
+
- Branch: `feat/005-agent-messaging-and-task-lifecycle`
|
|
10
|
+
- Package version: `0.1.7`
|
|
11
|
+
- Runtime: TypeScript executed directly by Node; no build step.
|
|
12
|
+
- Full baseline command: `npm test`
|
|
13
|
+
- Baseline result: all existing test commands passed.
|
|
14
|
+
|
|
15
|
+
The baseline suite currently covers:
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
schemas
|
|
19
|
+
CLI behavior
|
|
20
|
+
parent surface
|
|
21
|
+
status widget
|
|
22
|
+
command UX
|
|
23
|
+
discovery
|
|
24
|
+
launch argument construction
|
|
25
|
+
effective prompts
|
|
26
|
+
registry behavior
|
|
27
|
+
multi-wait behavior
|
|
28
|
+
prompt watchers
|
|
29
|
+
artifact sessions
|
|
30
|
+
settings
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Phase 0 adds `phase0:test` to this suite for reusable fixtures and lifecycle
|
|
34
|
+
boundary assertions.
|
|
35
|
+
|
|
36
|
+
## Current parent tool surface
|
|
37
|
+
|
|
38
|
+
`registerShepherdTools()` currently registers eight parent tools, in this order:
|
|
39
|
+
|
|
40
|
+
```text
|
|
41
|
+
shepherd
|
|
42
|
+
shepherd_spawn
|
|
43
|
+
shepherd_prompt
|
|
44
|
+
shepherd_wait
|
|
45
|
+
shepherd_watch
|
|
46
|
+
shepherd_status
|
|
47
|
+
shepherd_close
|
|
48
|
+
shepherd_read
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The parent also registers the `/shepherd` command. Parent registration is
|
|
52
|
+
skipped when `PI_SHEPHERD_SESSION` is present, so launched children do not
|
|
53
|
+
inherit the parent Shepherd tools or command.
|
|
54
|
+
|
|
55
|
+
## Current child surface
|
|
56
|
+
|
|
57
|
+
Launched children receive `src/extension/shepherd-done.ts` as their Shepherd
|
|
58
|
+
extension. The current child extension:
|
|
59
|
+
|
|
60
|
+
- applies the delegated system-prompt replacement and Pi-documentation
|
|
61
|
+
filtering;
|
|
62
|
+
- observes `agent_end`;
|
|
63
|
+
- writes a `<session>.exit` completion sidecar for normal assistant turns;
|
|
64
|
+
- reports provider errors through that sidecar; and
|
|
65
|
+
- shuts down one-shot children after a normal turn unless stay-open behavior is
|
|
66
|
+
enabled.
|
|
67
|
+
|
|
68
|
+
It does not currently expose `shepherd_message` or `shepherd_done`.
|
|
69
|
+
|
|
70
|
+
## Current lifecycle behavior
|
|
71
|
+
|
|
72
|
+
The current registry contains opaque session-scoped agent and prompt IDs. It
|
|
73
|
+
supports one unresolved prompt per agent and prompt watchers.
|
|
74
|
+
|
|
75
|
+
The current prompt watcher polls Herdr and may settle a prompt from:
|
|
76
|
+
|
|
77
|
+
- a new completion sidecar;
|
|
78
|
+
- a detected provider error; or
|
|
79
|
+
- a post-submission Herdr state transition to `idle`, `done`, or `blocked`.
|
|
80
|
+
|
|
81
|
+
That behavior is retained as legacy prompt behavior during Phase 0. It must not
|
|
82
|
+
be copied into the future tracked-task path. In particular:
|
|
83
|
+
|
|
84
|
+
```text
|
|
85
|
+
agent process becomes idle != delegated task completed
|
|
86
|
+
agent_end != delegated task completed
|
|
87
|
+
agent_settled != delegated task completed
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The new task path will require `shepherd_done` or an explicit failure,
|
|
91
|
+
cancellation, or timeout event.
|
|
92
|
+
|
|
93
|
+
## Current artifact behavior
|
|
94
|
+
|
|
95
|
+
When fieldnotes are enabled, a prompt can reserve an artifact from the parent
|
|
96
|
+
Shepherd session. The artifact is started before prompt submission and
|
|
97
|
+
finalized when the prompt settles. The future implementation must move this
|
|
98
|
+
association to delegated task records and keep task artifacts open while a task
|
|
99
|
+
is waiting.
|
|
100
|
+
|
|
101
|
+
## Phase 0 guardrails added
|
|
102
|
+
|
|
103
|
+
- `test/helpers/test-utils.mjs` provides isolated temporary directories,
|
|
104
|
+
stable fake parent/child identities, and microtask flushing.
|
|
105
|
+
- `test/helpers/fake-clock.mjs` provides a manual clock and a scoped
|
|
106
|
+
`Date.now()` override for legacy code that cannot yet receive an injected
|
|
107
|
+
clock.
|
|
108
|
+
- `test/helpers/feature-contracts.mjs` centralizes planned tool, surface, and
|
|
109
|
+
task-state contracts for later phase tests without registering future tools.
|
|
110
|
+
- `test/verify-phase0.mjs` verifies fixture behavior and that changing an
|
|
111
|
+
agent's observed state to idle does not settle an open registry record.
|
|
112
|
+
- `src/core/orchestration.ts` documents that observed agent state and explicit
|
|
113
|
+
lifecycle settlement are separate concerns.
|
|
114
|
+
- `src/core/lifecycle.ts` documents that idle/done inference is legacy prompt
|
|
115
|
+
behavior and is not valid for tracked tasks.
|
|
@@ -0,0 +1,564 @@
|
|
|
1
|
+
# Handoff: Asynchronous Shepherd Tasks and Agent Messaging
|
|
2
|
+
|
|
3
|
+
## Session state
|
|
4
|
+
|
|
5
|
+
- Branch: `feat/005-agent-messaging-and-task-lifecycle`
|
|
6
|
+
- Repository: `MikkelKappelPersson/shepherd`
|
|
7
|
+
- Current HEAD: tip of the feature branch — `b2c3b59` plus the Phase 5 failure-test commit and this handoff update (hashes shift when this doc changes; use `git log --oneline`)
|
|
8
|
+
- Working tree: contains the Phase 11 launch-tool fix, verification updates, and documentation/checklist edits
|
|
9
|
+
- Last full verification: `npm test` passed with zero failures
|
|
10
|
+
|
|
11
|
+
This handoff is for continuing implementation on another computer. Start by
|
|
12
|
+
checking out the branch and reading this file, `spec.md`, `plan.md`, and
|
|
13
|
+
`tasks.md` in this directory.
|
|
14
|
+
|
|
15
|
+
## Completed work
|
|
16
|
+
|
|
17
|
+
### Phase 0 — Baseline and guardrails
|
|
18
|
+
|
|
19
|
+
Completed and committed in `a0dab9f`.
|
|
20
|
+
|
|
21
|
+
Added:
|
|
22
|
+
|
|
23
|
+
- `baseline.md`
|
|
24
|
+
- Reusable temporary-directory and fake-identity helpers
|
|
25
|
+
- Manual/scoped clock helpers
|
|
26
|
+
- Centralized future tool/surface/task-state contracts
|
|
27
|
+
- Explicit-settlement guardrail tests
|
|
28
|
+
- Phase 0 test command in `package.json`
|
|
29
|
+
|
|
30
|
+
The baseline confirms that the current legacy prompt path uses sidecars and
|
|
31
|
+
Herdr state observations, while the new task path must not infer completion
|
|
32
|
+
from those events.
|
|
33
|
+
|
|
34
|
+
### Phase 1 — Task registry and task state
|
|
35
|
+
|
|
36
|
+
Completed and committed in `ae68588`.
|
|
37
|
+
|
|
38
|
+
Implemented in `src/core/orchestration.ts`:
|
|
39
|
+
|
|
40
|
+
- Session-scoped opaque task IDs
|
|
41
|
+
- `TaskRecord`, `TaskResult`, and settlement types
|
|
42
|
+
- `created`, `running`, `waiting`, `completed`, `blocked`, `failed`,
|
|
43
|
+
`cancelled`, and `timed_out` states
|
|
44
|
+
- One active tracked task per agent
|
|
45
|
+
- Pending request tracking
|
|
46
|
+
- Waiting timestamps
|
|
47
|
+
- Task deadlines and timeout timers
|
|
48
|
+
- Stale-notification metadata
|
|
49
|
+
- Artifact association fields and settlement callbacks
|
|
50
|
+
- Ownership validation
|
|
51
|
+
- Idempotent terminal settlement
|
|
52
|
+
- Cancellation and task snapshots
|
|
53
|
+
|
|
54
|
+
Tests are in `test/verify-task-registry.mjs`.
|
|
55
|
+
|
|
56
|
+
### Phase 2 — Parent-owned mailbox transport
|
|
57
|
+
|
|
58
|
+
Completed and committed in `e48666d`.
|
|
59
|
+
|
|
60
|
+
Implemented in `src/core/messaging.ts`:
|
|
61
|
+
|
|
62
|
+
- Protected session mailbox directories
|
|
63
|
+
- Parent and per-child inboxes
|
|
64
|
+
- Atomic JSON envelope publication
|
|
65
|
+
- Envelope validation
|
|
66
|
+
- Parent/child/peer routing
|
|
67
|
+
- Child capabilities
|
|
68
|
+
- Session, broker, sender, and target validation
|
|
69
|
+
- Duplicate acknowledgement markers
|
|
70
|
+
- Malformed-envelope quarantine
|
|
71
|
+
- Queue-depth, byte-size, and content-length limits
|
|
72
|
+
- Processed/rejected message retention
|
|
73
|
+
- Cleanup protection until children are gone
|
|
74
|
+
|
|
75
|
+
Tests are in `test/verify-messaging.mjs`.
|
|
76
|
+
|
|
77
|
+
### Phase 3 — Child-side Shepherd surface
|
|
78
|
+
|
|
79
|
+
Completed and committed in `44b5ae8`.
|
|
80
|
+
|
|
81
|
+
Extended `src/extension/shepherd-done.ts` with:
|
|
82
|
+
|
|
83
|
+
- Child `shepherd_message` tool
|
|
84
|
+
- Child `shepherd_done` tool
|
|
85
|
+
- Broker capability loading from environment
|
|
86
|
+
- Child inbox polling
|
|
87
|
+
- `followUp` and `steer` delivery through `pi.sendUserMessage`
|
|
88
|
+
- Correlated sender/message/task/thread/reply metadata
|
|
89
|
+
- Runtime diagnostics for failed local delivery
|
|
90
|
+
- Explicit task-done envelopes
|
|
91
|
+
- Tracked-task protection against normal `agent_end` completion
|
|
92
|
+
|
|
93
|
+
Extended `src/core/herdr.ts` with launch-time broker and task environment
|
|
94
|
+
wiring plus task instructions explaining explicit completion and replies.
|
|
95
|
+
|
|
96
|
+
Tests are in `test/verify-child-surface.mjs`; launch coverage is in
|
|
97
|
+
`test/verify-launch.mjs`.
|
|
98
|
+
|
|
99
|
+
### Phase 4 — Tracked delegation
|
|
100
|
+
|
|
101
|
+
Implemented and committed in `b2c3b59`.
|
|
102
|
+
|
|
103
|
+
Implemented:
|
|
104
|
+
|
|
105
|
+
- Parent `shepherd_delegate` tool
|
|
106
|
+
- `LifecycleDelegateParams`
|
|
107
|
+
- Parent broker creation and lazy monitor lifecycle
|
|
108
|
+
- Pre-launch opaque agent ID reservation
|
|
109
|
+
- Child capability registration during agent startup
|
|
110
|
+
- `delegateAgent()` in `src/core/lifecycle.ts`
|
|
111
|
+
- Non-blocking task-envelope submission
|
|
112
|
+
- Task artifact reservation/start/finalization callback
|
|
113
|
+
- Publication failure rollback
|
|
114
|
+
- Closed-agent and active-task checks
|
|
115
|
+
- Updated parent tool schema/surface tests
|
|
116
|
+
|
|
117
|
+
The delegation path is:
|
|
118
|
+
|
|
119
|
+
```text
|
|
120
|
+
shepherd_spawn
|
|
121
|
+
-> parent broker registers child capability
|
|
122
|
+
-> child starts with broker/task environment
|
|
123
|
+
shepherd_delegate
|
|
124
|
+
-> task record is reserved
|
|
125
|
+
-> task envelope is queued to the child inbox
|
|
126
|
+
-> task transitions to running
|
|
127
|
+
-> delegate returns taskId without waiting
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
The old `shepherd_prompt` path remains separate and is still legacy behavior.
|
|
131
|
+
Its compatibility mapping to task IDs is deliberately deferred.
|
|
132
|
+
|
|
133
|
+
### Phase 5 — Explicit completion and failures
|
|
134
|
+
|
|
135
|
+
Complete.
|
|
136
|
+
|
|
137
|
+
Implemented in `b2c3b59` and the task-failure tests:
|
|
138
|
+
|
|
139
|
+
- Parent broker polling via `processParentBrokerMessages()`
|
|
140
|
+
- `task_done` envelope consumption
|
|
141
|
+
- Child ownership validation
|
|
142
|
+
- Unknown/foreign task rejection
|
|
143
|
+
- Rejection of successful completion while required requests are pending
|
|
144
|
+
- Explicit completion summary/timestamp persistence
|
|
145
|
+
- Idempotent task settlement
|
|
146
|
+
- Task artifact finalization callback
|
|
147
|
+
- Task deadline timeout settlement
|
|
148
|
+
- Pane disappearance failure detection
|
|
149
|
+
- Provider-error detection from pane output
|
|
150
|
+
- Close-to-task-cancellation behavior
|
|
151
|
+
- Normal tracked-task `agent_end` no longer claims success
|
|
152
|
+
- Task ID inclusion in retained sidecars
|
|
153
|
+
|
|
154
|
+
Tests:
|
|
155
|
+
|
|
156
|
+
- `test/verify-task-completion.mjs`: owning-child completion, foreign-child
|
|
157
|
+
rejection, duplicate completion, pending-request rejection, blocked
|
|
158
|
+
completion, idle-child + explicit completion, and no-premature-completion
|
|
159
|
+
from `agent_end`/`agent_settled`/idle state.
|
|
160
|
+
- `test/verify-task-failures.mjs`: provider-error failure, unexpected pane
|
|
161
|
+
exit failure, close-to-cancellation, and deadline timeout. Uses a
|
|
162
|
+
Node-script fake `herdr` on PATH backed by a JSON state file so `pane
|
|
163
|
+
list`, `pane close`, and `agent read` observations are deterministic.
|
|
164
|
+
|
|
165
|
+
Deferred (tracked in `tasks.md`):
|
|
166
|
+
|
|
167
|
+
- Preserve useful child output in failure results (completion-diagnostics
|
|
168
|
+
follow-up).
|
|
169
|
+
- Preserve runtime observations for status output (Phase 9).
|
|
170
|
+
|
|
171
|
+
### Phase 6 — Asynchronous message routing
|
|
172
|
+
|
|
173
|
+
Complete.
|
|
174
|
+
|
|
175
|
+
Implemented:
|
|
176
|
+
|
|
177
|
+
- Parent `shepherd_message` tool (`src/extension/shepherd.ts`, schema in
|
|
178
|
+
`src/core/types.ts`) with flat root object: `target` + `message` required;
|
|
179
|
+
`taskId`, `threadId`, `replyTo`, `expectsReply`, `delivery` optional.
|
|
180
|
+
- `sendParentMessage()` and the parent message notifier/bridge in
|
|
181
|
+
`src/core/lifecycle.ts`; child message delivery via
|
|
182
|
+
`configureParentMessageNotifications()` and `sendUserMessage` delivery in
|
|
183
|
+
`src/extension/shepherd.ts` / `shepherd-done.ts`. Child requests and replies
|
|
184
|
+
wake the parent at the next safe turn boundary; ordinary child messages are
|
|
185
|
+
queued passively.
|
|
186
|
+
- Task registry request/reply correlation in `src/core/orchestration.ts`
|
|
187
|
+
(`openPendingRequest`, `resolveReplyForTask`, `clearPendingReply`) with a
|
|
188
|
+
single outstanding request per task.
|
|
189
|
+
- Child-side `runtime` request-open mirror and reply routing through the
|
|
190
|
+
parent broker, so a busy peer's queued question keeps the sender task in
|
|
191
|
+
the `waiting` state and a matching reply returns it to `running`.
|
|
192
|
+
- Reply deadline tracking and `blocked` settlement on timeout.
|
|
193
|
+
- Provenance preserved via `originSenderId` on the relayed reply.
|
|
194
|
+
- Delivery failure diagnostic surfaced to the parent for failed local
|
|
195
|
+
`sendUserMessage`.
|
|
196
|
+
|
|
197
|
+
Tests: `test/verify-message-routing.mjs` (parent/child, busy/idle recipient,
|
|
198
|
+
request creation and timeout, valid/invalid/duplicate/origin-preserving
|
|
199
|
+
replies, delivery failures, unknown/closed targets, task ownership check).
|
|
200
|
+
|
|
201
|
+
See `phase6-notes.md` in this directory for the routing and correlation
|
|
202
|
+
decisions.
|
|
203
|
+
|
|
204
|
+
### Phase 7 — Task-aware `shepherd_watch`
|
|
205
|
+
|
|
206
|
+
Complete.
|
|
207
|
+
|
|
208
|
+
Implemented:
|
|
209
|
+
|
|
210
|
+
- `LifecycleRegistry.watchTasks()` (plus the task side of `settleTask`
|
|
211
|
+
settlement) in `src/core/orchestration.ts`: one-shot, synchronous,
|
|
212
|
+
exactly-once per task, driven directly from settlement — no polling.
|
|
213
|
+
`settleTask` is the single authoritative hook, so `waiting`, `idle`,
|
|
214
|
+
`agent_end`, and `agent_settled` can never fire a task watcher.
|
|
215
|
+
- `TaskWatcherService` in `src/core/lifecycle.ts`: coalescing, ordered
|
|
216
|
+
delivery with `unref()`'d flush timers and `shutdown()`.
|
|
217
|
+
- `shepherd_watch` now accepts task ids (primary) and legacy prompt ids
|
|
218
|
+
(compat, routed to the existing prompt watcher); agent ids and pane ids
|
|
219
|
+
are rejected with a clear error; a call cannot mix both kinds.
|
|
220
|
+
- Parent `shepherd.task.completion` message + bridge that sends a
|
|
221
|
+
follow-up with `triggerTurn: true` keyed by task id.
|
|
222
|
+
|
|
223
|
+
Tests: `test/verify-task-watchers.mjs` (non-blocking registration, no
|
|
224
|
+
completion from `waiting`, terminal-only settlement across completed/failed/
|
|
225
|
+
blocked/cancelled/timed_out, coalesced input order, independent watchers,
|
|
226
|
+
rejections, bridge delivery and shutdown suppression).
|
|
227
|
+
|
|
228
|
+
See `phase7-notes.md` in this directory for the design decisions.
|
|
229
|
+
|
|
230
|
+
### Phase 8 — Stale-wait monitoring
|
|
231
|
+
|
|
232
|
+
Complete.
|
|
233
|
+
|
|
234
|
+
Implemented:
|
|
235
|
+
|
|
236
|
+
- `staleWaitThreshold` setting in `src/extension/config.ts` (minutes, default
|
|
237
|
+
`5`; `0` disables reminders; invalid values fall back to the default).
|
|
238
|
+
Wired into `OVERRIDABLE_FIELDS` so it participates in user + project layer
|
|
239
|
+
resolution, the `/shepherd settings` menu (`src/extension/settings-ui.ts`
|
|
240
|
+
adds a `Stale wait reminder` row with an `off` option), and the README
|
|
241
|
+
settings table plus a short stale-wait explanation.
|
|
242
|
+
- `LifecycleRegistry.markStaleNotified(taskId)` (orchestration) stamps the
|
|
243
|
+
episode with a wall-clock time so the monitor issues at most one reminder
|
|
244
|
+
per episode. `staleNotifiedAt` is cleared by `setTaskRunning`,
|
|
245
|
+
`resolvePendingRequest`, `resolveReplyForTask`, and `settleTask` — a reply
|
|
246
|
+
(or any terminal event) resets the state, a re-entry into `waiting` later
|
|
247
|
+
can produce a new reminder.
|
|
248
|
+
- `StaleWaitMonitor` (lifecycle.ts) + the `staleWaitMonitor` singleton and
|
|
249
|
+
`configureStaleWaitNotifications()` / `shutdownStaleWaitMonitor()`. The
|
|
250
|
+
monitor only starts when a task opens a pending reply
|
|
251
|
+
(`sendParentMessage` and the child `runtime` mirror call
|
|
252
|
+
`staleWaitMonitor.kick()`), polls at 1s (unref'd), inspects *task* state
|
|
253
|
+
(not raw agent state), and emits at most one notification per episode with
|
|
254
|
+
full context (task, owner, description, question, pending request id,
|
|
255
|
+
target, target state, elapsed wait, threshold).
|
|
256
|
+
- The parent bridge (`configureStaleWaitBridge` in
|
|
257
|
+
`src/extension/shepherd.ts`) registers a `shepherd.stale.wait` custom
|
|
258
|
+
message renderer and delivers via `sendMessage` with
|
|
259
|
+
`deliverAs: 'followUp'` and **no** turn trigger, so the idle parent sees
|
|
260
|
+
the nudge without being forced to act; the parent only wakes on a real
|
|
261
|
+
`shepherd_watch` completion or on a user interaction.
|
|
262
|
+
- `index.ts` toggles `setStaleWaitSessionActive` on session
|
|
263
|
+
start/shutdown and calls `shutdownStaleWaitMonitor()` on shutdown so the
|
|
264
|
+
timer is released with the session.
|
|
265
|
+
- Reply deadline (already present, Phase 6) settles a task as `blocked` if
|
|
266
|
+
the reply never arrives; the stale reminder is strictly informational and
|
|
267
|
+
never changes task state.
|
|
268
|
+
|
|
269
|
+
Tests: `test/verify-stale-wait.mjs` (threshold crossing, one notification per
|
|
270
|
+
episode, content coverage, reset after a reply, completed + idle (no task)
|
|
271
|
+
agents stay quiet, stale-wait does not settle a task, monitor starts/stops
|
|
272
|
+
with the waiting set, disabled threshold, and bridge delivery + shutdown
|
|
273
|
+
suppression).
|
|
274
|
+
|
|
275
|
+
See `phase8-notes.md` in this directory for the design decisions.
|
|
276
|
+
|
|
277
|
+
### Phase 9 — Status and TUI integration
|
|
278
|
+
|
|
279
|
+
Complete.
|
|
280
|
+
|
|
281
|
+
Implemented:
|
|
282
|
+
|
|
283
|
+
- `AgentStatus` in `src/core/orchestration.ts` now carries a `task` view
|
|
284
|
+
(`id`, `state`, `waitingSince`/`waitingMs`, `pendingRequestMessageId`,
|
|
285
|
+
`waitingRecipient`, `stale`) computed by a new
|
|
286
|
+
`LifecycleRegistry.taskStatusForAgent()`; process state and task state stay
|
|
287
|
+
independent (an idle process owns the waiting task; a completed task leaves
|
|
288
|
+
the process `done` with no `task` field).
|
|
289
|
+
- `src/extension/shepherd.ts` `status` action exposes a compact public task
|
|
290
|
+
view (`waitingMs`, `pendingRequest` (renamed from the long field),
|
|
291
|
+
`waitingOn`, `stale`) and names both process and task state in the summary
|
|
292
|
+
text. Herdr pane ids remain internal diagnostics (not part of the public
|
|
293
|
+
`status` result).
|
|
294
|
+
- `src/core/herdr.ts` adds `activeTasksByPane()` (in-memory registry only,
|
|
295
|
+
safe for every snapshot tick) and `workingOrWaitingSubagents()`: an owned
|
|
296
|
+
pane is listed when the process is not idle **or** it still owns an open
|
|
297
|
+
tracked task, so an idle child parked on a required reply is never filtered
|
|
298
|
+
out as "done". `workingSubagents()` remains as a working-only projection.
|
|
299
|
+
- The status widget in `index.ts` now renders task state distinctly: the
|
|
300
|
+
header counts `N working · N waiting`, rows show the **task** state while a
|
|
301
|
+
task is open (a working process with a waiting task renders `waiting`),
|
|
302
|
+
and waiting rows append ` ⏳<m>m ←<recipient>` (elapsed wait + who is
|
|
303
|
+
expected to answer). A stale episode renders as `waiting (stale)`. Pane and
|
|
304
|
+
task ids are not painted into rows.
|
|
305
|
+
- README: "Reading status" section documents independent process/task state,
|
|
306
|
+
the task fields, and the widget's idle-but-waiting projection.
|
|
307
|
+
|
|
308
|
+
Tests: `test/verify-status.mjs` (process/task independence for idle+waiting,
|
|
309
|
+
working+running, and no-task agents; reply clears waiting/stale; completion
|
|
310
|
+
removes the task view; doAction public mapping keeps opaque ids and never
|
|
311
|
+
leaks pane data). `test/verify-status-widget.mjs` now covers the idle process
|
|
312
|
+
with a waiting (stale) task, working process with a running task, completed
|
|
313
|
+
task removal, session ownership filtering, and phase-1/2 glyph/width checks
|
|
314
|
+
across three snapshot phases.
|
|
315
|
+
|
|
316
|
+
See `phase9-notes.md` in this directory for the design decisions.
|
|
317
|
+
|
|
318
|
+
"
|
|
319
|
+
### Phase 10 — Compatibility decisions
|
|
320
|
+
|
|
321
|
+
Decisions (spec "Compatibility" section):
|
|
322
|
+
|
|
323
|
+
- `shepherd_prompt`: **retained as a deprecated compatibility path**, not
|
|
324
|
+
removed. Rationale: removing it would break every transcript and prompt
|
|
325
|
+
template that still references it during migration, and its one-prompt-per-
|
|
326
|
+
turn semantics remain correct for fire-and-forget one-turn messages. The tool
|
|
327
|
+
label, description, promptSnippet, and parameter descriptions now say it is
|
|
328
|
+
deprecated and name the migration target (`shepherd_delegate` +
|
|
329
|
+
`shepherd_watch`), so the model migrates instead of defaulting to it. Its
|
|
330
|
+
completion semantics remain one-child-turn-completion; that is documented,
|
|
331
|
+
not silently changed, so it cannot be mistaken for task tracking.
|
|
332
|
+
- `shepherd_wait`: **hard-removed from the model-facing surface.** Its blocking
|
|
333
|
+
behavior obscured intermediate `waiting` state and encouraged the Shepherd
|
|
334
|
+
to remain visibly working while it waited. Use `shepherd_watch` for
|
|
335
|
+
non-blocking terminal notifications and `shepherd_status` for intermediate
|
|
336
|
+
task state. The legacy prompt path is observed through `shepherd_watch`.
|
|
337
|
+
- `shepherd_watch`, `shepherd_delegate`, `shepherd_message`, `shepherd_done`:
|
|
338
|
+
unchanged (already documented in phases 6–8).
|
|
339
|
+
|
|
340
|
+
## Important current architecture
|
|
341
|
+
|
|
342
|
+
### Parent task completion
|
|
343
|
+
|
|
344
|
+
`ensureParentBroker()` in `src/core/lifecycle.ts` lazily creates a parent broker
|
|
345
|
+
and starts a 250ms unref'd monitor. The monitor calls
|
|
346
|
+
`processParentBrokerMessages()`.
|
|
347
|
+
|
|
348
|
+
The parent currently handles these inbox events:
|
|
349
|
+
|
|
350
|
+
- `task_done`: validates and settles the task
|
|
351
|
+
- `message` / `reply`: routed to the parent Pi session as a custom Shepherd message (followUp). Requests with `expectsReply` and replies trigger a parent turn at the next safe boundary; ordinary messages remain passive. A `reply` also resolves the matching pending request on the sender's task and is relayed back to the asker's child inbox
|
|
352
|
+
- `runtime` with `requestOpen`: opens the task's pending request (task → waiting) so a busy recipient's queued question keeps the sender task open
|
|
353
|
+
- Pane disappearance, provider error, and reply-deadline expiry settle tasks as failed / failed / blocked
|
|
354
|
+
|
|
355
|
+
### Child task completion
|
|
356
|
+
|
|
357
|
+
The child extension receives `PI_SHEPHERD_TASK_ID`. A normal assistant turn
|
|
358
|
+
ending while this variable is present does not write a successful completion
|
|
359
|
+
sidecar and does not shut down the child. The child must call `shepherd_done`.
|
|
360
|
+
|
|
361
|
+
Provider errors still write a sidecar and may be detected by the parent runtime
|
|
362
|
+
monitor.
|
|
363
|
+
|
|
364
|
+
### Task state invariant
|
|
365
|
+
|
|
366
|
+
Do not weaken this invariant:
|
|
367
|
+
|
|
368
|
+
```text
|
|
369
|
+
Pi turn ends -> runtime observation only
|
|
370
|
+
agent_end -> runtime observation only
|
|
371
|
+
agent_settled -> runtime observation only
|
|
372
|
+
Herdr idle -> runtime observation only
|
|
373
|
+
shepherd_done -> normal task completion
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
An idle child may own a `waiting` task.
|
|
377
|
+
|
|
378
|
+
### Transport behavior
|
|
379
|
+
|
|
380
|
+
The filesystem broker uses:
|
|
381
|
+
|
|
382
|
+
```text
|
|
383
|
+
<broker>/broker.json
|
|
384
|
+
<broker>/parent/inbox/*.json
|
|
385
|
+
<broker>/agents/<hashed-agent-id>/manifest.json
|
|
386
|
+
<broker>/agents/<hashed-agent-id>/inbox/*.json
|
|
387
|
+
<broker>/processed/*
|
|
388
|
+
<broker>/rejected/*
|
|
389
|
+
<broker>/acks/*
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
`pollParentInbox()` and `pollChildInbox()` move consumed files to processed
|
|
393
|
+
storage and create acknowledgement markers. Child and parent runtime adapters
|
|
394
|
+
are responsible for making handler operations idempotent.
|
|
395
|
+
|
|
396
|
+
## Remaining work
|
|
397
|
+
|
|
398
|
+
Consult `tasks.md` for the authoritative checkbox state. Phases 5, 6, 7, 8, 9, and 10
|
|
399
|
+
are complete. Phase 11 (full verification and release readiness) is in progress:
|
|
400
|
+
|
|
401
|
+
### Phase 11 status (as of this update)
|
|
402
|
+
|
|
403
|
+
- Automated verification: all 15 items done — `npm test` passes cleanly.
|
|
404
|
+
- Live Herdr matrix started. Verified live: Herdr session attach, persistent
|
|
405
|
+
spawn, non-blocking delegation, status during `running`, close of an
|
|
406
|
+
agent with an open task (task settles `cancelled`, artifact finalized,
|
|
407
|
+
exactly one watcher notification), temporary launch-dir cleanup after pane
|
|
408
|
+
confirmation.
|
|
409
|
+
- **Live bug found and fixed:** `writePiLaunchFiles` passed agent-defined
|
|
410
|
+
`tools:` frontmatter straight to `--tools`, which is a full allowlist — so
|
|
411
|
+
children of agents like bundled `scout` (`read,grep,find,ls`) lost the
|
|
412
|
+
child-surface tools `shepherd_message` and `shepherd_done` and could not
|
|
413
|
+
message peers or complete tasks. Fix: `CHILD_SURFACE_TOOLS` is always
|
|
414
|
+
appended to the launch `--tools` list. `test/verify-launch.mjs` asserts the
|
|
415
|
+
allowlist now contains `read,shepherd_message,shepherd_done`.
|
|
416
|
+
- The fix is on disk; a RUNNING Shepherd parent only picks it up on extension
|
|
417
|
+
reload (sessions load TS at startup). Live spawns from a pre-reload parent
|
|
418
|
+
still launch children without the child tools.
|
|
419
|
+
- Completed live matrix items: canonical wait/reply/done flow with stale-wait
|
|
420
|
+
notification, status during `waiting` and after completion, busy-planner
|
|
421
|
+
interleaving, both planner/scout closure directions, task timeout, provider
|
|
422
|
+
model-error observation, pane ownership rejection, temporary-resource cleanup,
|
|
423
|
+
and parent shutdown. After the parent was quit and resumed, the persistent
|
|
424
|
+
survivor remained visible and idle; the previous opaque lifecycle handle was
|
|
425
|
+
rejected by the resumed parent.
|
|
426
|
+
|
|
427
|
+
## Live-matrix findings (Phase 11)
|
|
428
|
+
|
|
429
|
+
1. **`--tools` allowlist stripped child tools (fixed).** See "Live bug found and
|
|
430
|
+
fixed" above. `CHILD_SURFACE_TOOLS` is now always appended to the launch
|
|
431
|
+
`--tools` list; live launch scripts confirmed to carry
|
|
432
|
+
`read,grep,find,ls,shepherd_message,shepherd_done`.
|
|
433
|
+
2. **Child peer addressing requires the opaque agent id.** A child cannot
|
|
434
|
+
address a sibling by display name (`target "planner"` →
|
|
435
|
+
`invalid_target: Unknown child target "planner"`). Peer routing resolves
|
|
436
|
+
only the hashed broker manifest directory for a registered agent id. The
|
|
437
|
+
parent must supply the peer's opaque id in the task text. This is per the
|
|
438
|
+
spec (parent-mediated peer delivery, opaque ids), but is a documentation/
|
|
439
|
+
discovery gap — a child has no way to enumerate sibling ids. Candidate for
|
|
440
|
+
a follow-up (e.g. a parent-injected roster or a peer listing for the child
|
|
441
|
+
surface).
|
|
442
|
+
3. **`task_done` cannot succeed while a tracked reply is pending.** If a task
|
|
443
|
+
is `waiting` on an outstanding request (`pendingReplyMessageId` set), a
|
|
444
|
+
`shepherd_done` with `completed` is ignored (task stays waiting) until the
|
|
445
|
+
matching reply arrives or the task is settled via `blocked`/`failed`.
|
|
446
|
+
The reply's `replyTo` must equal the pending message id exactly.
|
|
447
|
+
|
|
448
|
+
Phase 11 live verification is complete. The canonical completion flow,
|
|
449
|
+
status-after-completion, planner/scout closure interleavings, busy-planner
|
|
450
|
+
interleaving, timeout, provider/model error observation, pane-ownership
|
|
451
|
+
rejection, temporary-resource cleanup, and parent shutdown were verified live.
|
|
452
|
+
After the parent was quit and resumed, the persistent survivor remained visible
|
|
453
|
+
and idle, while the previous opaque lifecycle handle was rejected by the
|
|
454
|
+
resumed parent. The invalid-model run exposed a readiness race:
|
|
455
|
+
`shepherd_spawn` can report success if Herdr briefly detects the child before pi
|
|
456
|
+
exits; the pane then becomes `unknown` with the model error and completion
|
|
457
|
+
sentinel visible. This is recorded as a follow-up hardening issue, not hidden as
|
|
458
|
+
a clean spawn pass.
|
|
459
|
+
|
|
460
|
+
The worker timeout also demonstrated that a late child message can be rejected
|
|
461
|
+
or accepted as an ordinary message after the task is terminal without changing
|
|
462
|
+
the timed-out result. Child parent aliases are exact lowercase values
|
|
463
|
+
(`shepherd`/`parent`); the live `Shepherd.` attempt was rejected with a structured
|
|
464
|
+
`invalid_target` response. Peer routing likewise requires the opaque registered
|
|
465
|
+
agent id, not a display name.
|
|
466
|
+
|
|
467
|
+
Note: a temporary `.shepherd/config.json` delta setting `staleWaitThreshold: 1`
|
|
468
|
+
was a no-op because the user config's `settingsScope` is `"user"` (project
|
|
469
|
+
deltas are only read when scope is `"project"`); the live stale-wait
|
|
470
|
+
notification fired at the 5-minute default, which validated the monitor anyway.
|
|
471
|
+
The scratch delta file has been removed; user config is untouched.
|
|
472
|
+
|
|
473
|
+
The only remaining live gate is parent shutdown. A fresh idle persistent child
|
|
474
|
+
labelled `p11 parent-shutdown survivor` is currently open for that check. End
|
|
475
|
+
this parent session, start a new Shepherd in the same project, confirm the
|
|
476
|
+
survivor remains visible/idle and that the new session cannot claim or close the
|
|
477
|
+
old session's pane, then update `tasks.md` and the specification status.
|
|
478
|
+
|
|
479
|
+
README and active user-facing documentation now describe the tracked task,
|
|
480
|
+
message, watch, status, compatibility, fieldnote, ownership, and stale-wait
|
|
481
|
+
behavior.
|
|
482
|
+
|
|
483
|
+
## Useful commands
|
|
484
|
+
|
|
485
|
+
Run focused tests:
|
|
486
|
+
|
|
487
|
+
```bash
|
|
488
|
+
npm run phase0:test
|
|
489
|
+
npm run task-registry:test
|
|
490
|
+
npm run messaging:test
|
|
491
|
+
npm run child-surface:test
|
|
492
|
+
npm run delegate:test
|
|
493
|
+
npm run task-completion:test
|
|
494
|
+
npm run task-failures:test
|
|
495
|
+
npm run message-routing:test
|
|
496
|
+
npm run task-watchers:test
|
|
497
|
+
npm run stale-wait:test
|
|
498
|
+
npm run compat:test
|
|
499
|
+
npm run status:test
|
|
500
|
+
npm run status-widget:test
|
|
501
|
+
npm run launch:test
|
|
502
|
+
```
|
|
503
|
+
|
|
504
|
+
Run everything:
|
|
505
|
+
|
|
506
|
+
```bash
|
|
507
|
+
npm test
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
Inspect state:
|
|
511
|
+
|
|
512
|
+
```bash
|
|
513
|
+
git status --short
|
|
514
|
+
git branch --show-current
|
|
515
|
+
git log --oneline --decorate -10
|
|
516
|
+
```
|
|
517
|
+
|
|
518
|
+
## Commit history for this feature
|
|
519
|
+
|
|
520
|
+
```text
|
|
521
|
+
(test: cover phase five task failure paths) <- tip after the Phase 5 test work
|
|
522
|
+
b2c3b59 feat: wire tracked delegation and task completion
|
|
523
|
+
44b5ae8 feat: add child messaging and completion surface
|
|
524
|
+
e48666d feat: add parent-owned messaging mailbox
|
|
525
|
+
ae68588 feat: add tracked task registry
|
|
526
|
+
a0dab9f test: establish async task lifecycle phase zero
|
|
527
|
+
986d474 docs: specify agent messaging and task lifecycle
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
## Continuation checklist
|
|
531
|
+
|
|
532
|
+
- [x] Read this handoff.
|
|
533
|
+
- [x] Read `spec.md`.
|
|
534
|
+
- [x] Read `plan.md`.
|
|
535
|
+
- [x] Read the current checkbox state in `tasks.md`.
|
|
536
|
+
- [x] Confirm the feature branch is checked out.
|
|
537
|
+
- [x] Run `npm test` before making further changes.
|
|
538
|
+
- [x] Finish remaining Phase 5 tests.
|
|
539
|
+
- [x] Implement Phase 6 parent message routing.
|
|
540
|
+
- [x] Implement Phase 7 task-aware `shepherd_watch`.
|
|
541
|
+
- [x] Implement Phase 8 stale-wait monitoring + `staleWaitThreshold` setting.
|
|
542
|
+
- [x] Implement Phase 9 task-aware status and TUI projection.
|
|
543
|
+
- [x] Make the Phase 10 compatibility decisions (shepherd_prompt deprecated;
|
|
544
|
+
shepherd_watch-only completion observation) and update active documentation.
|
|
545
|
+
- [x] Keep explicit `shepherd_done` completion authoritative.
|
|
546
|
+
- [x] Update this handoff if architecture or compatibility decisions change.
|
|
547
|
+
|
|
548
|
+
## Spec close-out (2026-09-01)
|
|
549
|
+
|
|
550
|
+
The spec is closed as delivered. Phases 0–10 are implemented; the full test
|
|
551
|
+
suite passes and the `docs/manual-tests/ping-pong-peer-messaging.md` smoke
|
|
552
|
+
test passes live, including watcher-completion delivery before cleanup
|
|
553
|
+
(steered watcher delivery, issue #10).
|
|
554
|
+
|
|
555
|
+
Deferred work is tracked out-of-band rather than left open in this spec:
|
|
556
|
+
|
|
557
|
+
- Preserve useful child output in failure results —
|
|
558
|
+
https://github.com/MikkelKappelPersson/shepherd/issues/11
|
|
559
|
+
|
|
560
|
+
Housekeeping at close: the spec directory moved from
|
|
561
|
+
`docs/specs/001-agent-messaging-and-task-lifecycle` to
|
|
562
|
+
`docs/specs/005-agent-messaging-and-task-lifecycle`, and the branch was
|
|
563
|
+
renamed from `feature/001-agent-messaging-and-task-lifecycle` to
|
|
564
|
+
`feat/005-agent-messaging-and-task-lifecycle`.
|