pi-herdsman 0.34.0 → 0.35.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/SKILL.md +12 -10
- package/dist/agent-definitions/manager.md +1 -1
- package/dist/index.js +892 -276
- package/dist/index.js.map +3 -3
- package/dist/peer-bridge.js.map +2 -2
- package/docs/concepts/coordination.md +15 -10
- package/docs/coordination-api.md +4 -3
- package/docs/development/smoke-testing.md +2 -2
- package/docs/guides/customizing-agents.md +1 -1
- package/docs/guides/handoffs.md +19 -9
- package/docs/guides/project-orchestration.md +13 -12
- package/docs/guides/recovery.md +9 -1
- package/docs/reference/agent-definition-schema.md +2 -2
- package/docs/reference/agent-states.md +8 -0
- package/docs/reference/agent.md +21 -2
- package/docs/reference/commands.md +2 -2
- package/docs/reference/peer.md +54 -7
- package/docs/reference/staff.md +15 -14
- package/docs/reference/status-widget.md +35 -14
- package/package.json +1 -1
|
@@ -78,7 +78,7 @@ direct-delegation allowlist.
|
|
|
78
78
|
|
|
79
79
|
Project implementation, technical conflict repair, and validation belong to
|
|
80
80
|
assigned Leads and their Agent trees. The Manager owns
|
|
81
|
-
project-level integration decisions and may use `
|
|
81
|
+
project-level integration decisions and may use `integrate_branch` to fast-forward
|
|
82
82
|
an accepted assigned branch into the verified primary branch when local-merge
|
|
83
83
|
permission is enabled. Manager's Git integration does not grant ownership of
|
|
84
84
|
the Lead's Agents or transfer responsibility for technical validation. The
|
|
@@ -113,8 +113,11 @@ participate in Manager, Chief, staff, supervisor, or peer authority.
|
|
|
113
113
|
|
|
114
114
|
## Project scope
|
|
115
115
|
|
|
116
|
-
A Herdsman **project** is the coordination scope
|
|
117
|
-
worktree group: its primary workspace plus linked-worktree
|
|
116
|
+
A Herdsman **project** is the coordination scope of one verified local Git
|
|
117
|
+
repository's Herdr worktree group: its primary workspace plus linked-worktree
|
|
118
|
+
workspaces. A **worktree** is a physical Git checkout, not a separate project
|
|
119
|
+
or ownership record. Separately verified worktree groups are not conflated
|
|
120
|
+
merely because their repositories share an identity.
|
|
118
121
|
|
|
119
122
|
Manager authority is scoped to that group. A Lead in the primary workspace may
|
|
120
123
|
enter Manager mode; a Lead in a linked-worktree workspace remains a Lead. An
|
|
@@ -130,10 +133,12 @@ Workspace membership is physical placement, not assignment ownership. Multiple
|
|
|
130
133
|
Leads can share a workspace, and a branch can have a worktree without implying
|
|
131
134
|
that every session in that workspace owns its work.
|
|
132
135
|
|
|
133
|
-
##
|
|
136
|
+
## Work assignments belong to a branch
|
|
134
137
|
|
|
135
|
-
|
|
136
|
-
|
|
138
|
+
A **work assignment** is one durable, branch-scoped objective assigned to an
|
|
139
|
+
exact managed Lead. It is keyed by repository identity plus semantic Git
|
|
140
|
+
branch. An **Agent assignment** is bounded work delegated to an exact
|
|
141
|
+
owner-managed Agent; it is separate from a work assignment.
|
|
137
142
|
|
|
138
143
|
Within one repository, the branch is the public work handle. A Lead is the
|
|
139
144
|
current executor. The assignment's exact Pi session ID is an internal executor
|
|
@@ -152,8 +157,8 @@ project work
|
|
|
152
157
|
|
|
153
158
|
The assignment is the durable indicator that project work remains open. It
|
|
154
159
|
survives Manager turnover and runtime loss; current Herdr placement is derived
|
|
155
|
-
again when the work is observed or resumed. For an assigned
|
|
156
|
-
automatically returns each completed direct Lead response as
|
|
160
|
+
again when the work is observed or resumed. For an assigned Lead, Herdsman
|
|
161
|
+
automatically returns each completed direct Lead response as an assignment update
|
|
157
162
|
for the Manager role. If managed Agent work is active, the herd run owns that
|
|
158
163
|
handoff until it settles, and the settled response should summarize outcome,
|
|
159
164
|
validation, and important unresolved points. Routine information that can wait
|
|
@@ -168,7 +173,7 @@ ownership without asserting completion or acceptance. See
|
|
|
168
173
|
[Project orchestration](../guides/project-orchestration.md) for the workflow.
|
|
169
174
|
|
|
170
175
|
`stop_lead` pauses assigned execution while preserving the assignment, Pi
|
|
171
|
-
session, branch, and worktree; `
|
|
176
|
+
session, branch, and worktree; `resume_work` resumes the existing
|
|
172
177
|
assignment while its checkout exists. These operations do not change project
|
|
173
178
|
authority. Successful Herdr worktree removal or verified checkout absence
|
|
174
179
|
retires the matching assignment and any still-pending project messages while
|
|
@@ -178,7 +183,7 @@ not authority.
|
|
|
178
183
|
A complete Git worktree inventory that verifies the checkout is absent retires
|
|
179
184
|
the exact assignment and pending project messages, even when a Herdr removal
|
|
180
185
|
event was missed. Failed or ambiguous inventory preserves the assignment.
|
|
181
|
-
`
|
|
186
|
+
`resume_work` cannot restore a retired assignment; a new delegation may
|
|
182
187
|
reuse the remaining Git branch.
|
|
183
188
|
|
|
184
189
|
For the task-oriented workflow, see
|
package/docs/coordination-api.md
CHANGED
|
@@ -45,10 +45,11 @@ read_staff_transcript
|
|
|
45
45
|
message_staff
|
|
46
46
|
|
|
47
47
|
Manager only:
|
|
48
|
-
|
|
49
|
-
|
|
48
|
+
delegate_work
|
|
49
|
+
resume_work
|
|
50
50
|
stop_lead
|
|
51
51
|
remove_worktree
|
|
52
|
+
integrate_branch
|
|
52
53
|
```
|
|
53
54
|
|
|
54
55
|
## Direct supervisor
|
|
@@ -65,7 +66,7 @@ clarifications, or warnings needed before the automatic completed-result
|
|
|
65
66
|
handoff. A Lead may choose to wait for a response through `message_staff`.
|
|
66
67
|
Routine information that can wait belongs in the result; there is no
|
|
67
68
|
message/result deduplication. `stop_lead` pauses execution without removing the
|
|
68
|
-
assignment, and `
|
|
69
|
+
assignment, and `resume_work` resumes it.
|
|
69
70
|
Successful Herdr worktree removal retires the matching project assignment and
|
|
70
71
|
any still-pending project messages. Verified Git worktree inventory showing
|
|
71
72
|
checkout absence also retires the assignment. Failed or ambiguous inventory
|
|
@@ -97,7 +97,7 @@ registration, Herdr, and an isolated local repository with no remote. The
|
|
|
97
97
|
assigned managed Lead uses Pi's real `bash` tool to commit source work, then
|
|
98
98
|
incorporates an independent target-side commit, validates the reconciled
|
|
99
99
|
checkout, and reports the exact final SHA. The scenario verifies actual
|
|
100
|
-
Manager `
|
|
100
|
+
Manager `integrate_branch` calls/results: divergence returns `needs_update`
|
|
101
101
|
without changing either checkout; retrying the accepted reconciled SHA
|
|
102
102
|
fast-forwards verified `main` to exactly that SHA. Before generic teardown it
|
|
103
103
|
checks that the exact source worktree is gone, its active assignment record is
|
|
@@ -175,7 +175,7 @@ exact Lead, assignment worktree, and session without success handoff or tool
|
|
|
175
175
|
replay. The provider fixture, project definition, retry settings, and evidence
|
|
176
176
|
files remain within the smoke isolation. For live acceptance the Manager
|
|
177
177
|
continues using the configured smoke model; simulated acceptance scripts only
|
|
178
|
-
its intended `
|
|
178
|
+
its intended `delegate_work` action and report acknowledgment. This scenario
|
|
179
179
|
is a single acceptance invocation and is never automatically retried.
|
|
180
180
|
|
|
181
181
|
`chief-tree` records ordinary Lead, Chief, and post-`session_tree` tool
|
|
@@ -167,7 +167,7 @@ Include the team's branch-validation checklist in the final handoff.
|
|
|
167
167
|
Its ordinary tool policy may be overridden, but Herdsman's mandatory Lead
|
|
168
168
|
coordination tools cannot be removed. Definition changes apply to future Lead
|
|
169
169
|
launches, not already-running Leads. Use `stop_lead` followed by
|
|
170
|
-
`
|
|
170
|
+
`resume_work` when a running project Lead must restart with changed launch
|
|
171
171
|
policy.
|
|
172
172
|
|
|
173
173
|
## Minimal model override
|
package/docs/guides/handoffs.md
CHANGED
|
@@ -16,8 +16,8 @@ carries evidence, not runtime capability.
|
|
|
16
16
|
## Required assignment evidence
|
|
17
17
|
|
|
18
18
|
A verified managed project assignment can retain **required evidence** for
|
|
19
|
-
future delegated Agents. The initial `
|
|
20
|
-
unchanged as `project-brief.md`; files supplied to `
|
|
19
|
+
future delegated Agents. The initial `delegate_work` task is preserved
|
|
20
|
+
unchanged as `project-brief.md`; files supplied to `delegate_work` also
|
|
21
21
|
become required evidence. Later evidence is retained as part of a handoff by
|
|
22
22
|
setting `retain: true` on an existing coordination operation:
|
|
23
23
|
|
|
@@ -25,12 +25,13 @@ setting `retain: true` on an existing coordination operation:
|
|
|
25
25
|
for the target assigned Lead's project assignment.
|
|
26
26
|
- An eligible managed Agent uses `delegate_agent` to retain supplied files as
|
|
27
27
|
additions to its local assignment for its own descendants. Its task text is
|
|
28
|
-
not retained, and it cannot modify the parent
|
|
28
|
+
not retained, and it cannot modify the parent assignment's evidence set.
|
|
29
29
|
|
|
30
|
-
The Manager alone controls
|
|
30
|
+
The Manager alone controls each assignment's requirements; sibling Lead
|
|
31
|
+
assignments do not automatically inherit one another's evidence. Root Lead delegation
|
|
31
32
|
accepts `files` for the current handoff, without a retention parameter.
|
|
32
33
|
Leads can forward findings directly for immediate correction; when findings
|
|
33
|
-
should become continuing
|
|
34
|
+
should become continuing assignment requirements, send the relevant files or
|
|
34
35
|
result references through `message_supervisor.files` for Manager evaluation.
|
|
35
36
|
Ordinary delegation need not wait for that decision.
|
|
36
37
|
|
|
@@ -54,7 +55,7 @@ handoff and deduplicated by verified version and result binding. The Manager's
|
|
|
54
55
|
latest retained update identifies one current batch for future eligible
|
|
55
56
|
descendants; other required entries remain historical and reference-first.
|
|
56
57
|
Project
|
|
57
|
-
descendants inherit
|
|
58
|
+
descendants inherit assignment requirements; nested descendants also inherit
|
|
58
59
|
relevant additions owned by their Agent parent. Siblings do not inherit one
|
|
59
60
|
another's local additions. An inherited snapshot keeps its original
|
|
60
61
|
`sourceAssignmentId`; forwarding inherited evidence does not transfer
|
|
@@ -110,7 +111,7 @@ or unrelated session acquires no automatic evidence scope. Retained evidence
|
|
|
110
111
|
removal remains an internal exact-ID capability; there is no standalone
|
|
111
112
|
model-facing evidence-management tool. Removing a requirement does not erase
|
|
112
113
|
prior Pi-session entries or evidence already accepted by an Agent.
|
|
113
|
-
For
|
|
114
|
+
For assignment-owned requirements, the Manager uses the assignment's **Retained
|
|
114
115
|
evidence** menu. Inherited baseline requirements are protected; removal leaves
|
|
115
116
|
snapshots, source files, and evidence already accepted by Agents unchanged.
|
|
116
117
|
The menu cannot remove managed-Agent-local additions. See
|
|
@@ -121,7 +122,7 @@ Pi Herdsman has two text-file mechanisms with different purposes:
|
|
|
121
122
|
|
|
122
123
|
- `files` supplies evidence to the coordination operations that accept it:
|
|
123
124
|
`delegate_agent`, `continue_agent`, `steer_agent`, `interrupt_agent`,
|
|
124
|
-
`reply_agent`, `
|
|
125
|
+
`reply_agent`, `delegate_work`, `message_staff`,
|
|
125
126
|
`message_supervisor`, `message_peer`, and `ask_owner`.
|
|
126
127
|
- whole-line body `@file` references put definition-owned text into the agent
|
|
127
128
|
system prompt when a new agent generation is built.
|
|
@@ -209,7 +210,7 @@ physical path attribute, and observed byte size. File content remains raw text.
|
|
|
209
210
|
markup frames evidence for the model and is not a security boundary.
|
|
210
211
|
|
|
211
212
|
`files` is supported by `delegate_agent`, `continue_agent`, `steer_agent`,
|
|
212
|
-
`interrupt_agent`, `reply_agent`, `
|
|
213
|
+
`interrupt_agent`, `reply_agent`, `delegate_work`, `message_staff`,
|
|
213
214
|
`message_supervisor`, `message_peer`, and `ask_owner`. For controller actions,
|
|
214
215
|
relative paths resolve from the calling controller's cwd; for `ask_owner`, they
|
|
215
216
|
resolve from the managed agent's cwd. Accepted ordinary filesystem paths retain
|
|
@@ -415,6 +416,15 @@ A result reference mentioned only in message text does not establish a reusable
|
|
|
415
416
|
binding. A semantic result reference can be forwarded through `files` when the
|
|
416
417
|
current Pi branch contains either its direct Agent completion or an explicitly
|
|
417
418
|
imported result binding.
|
|
419
|
+
|
|
420
|
+
A managed Agent may select semantic result refs for its eventual completion to
|
|
421
|
+
its direct owner with `attach_handoff({ files: ["result:scout#21"] })`. This
|
|
422
|
+
non-blocking operation selects evidence for completion; it does not send a
|
|
423
|
+
separate message or transfer artifact content. Each successful call replaces
|
|
424
|
+
the prior selection, and an empty list clears it. The selected binding and
|
|
425
|
+
artifact are revalidated at settlement and again before owner delivery. The
|
|
426
|
+
owner's completion inventory names refs that were successfully imported;
|
|
427
|
+
mentions in completion prose alone never create bindings.
|
|
418
428
|
A canonical result reference resolves internally to the normal private result file under Pi
|
|
419
429
|
Herdsman's durable data directory; it is still validated, canonicalized, and
|
|
420
430
|
deduplicated like any other file. Preserve the exact reference already supplied
|
|
@@ -67,8 +67,8 @@ project-work handles. A branch is optional when starting new work. If omitted,
|
|
|
67
67
|
Pi Herdsman can generate one. The first delegation can create the first linked
|
|
68
68
|
worktree, and an unoccupied existing worktree for the branch is reused.
|
|
69
69
|
|
|
70
|
-
Start new work with `
|
|
71
|
-
`
|
|
70
|
+
Start new work with `delegate_work`. Resume existing work with
|
|
71
|
+
`resume_work` using its branch. A verified Git inventory showing the
|
|
72
72
|
assignment's worktree checkout is absent retires that assignment and its
|
|
73
73
|
pending project messages; failed or ambiguous inventory preserves it. A retired
|
|
74
74
|
assignment cannot be resumed, but a new delegation may start managed work from
|
|
@@ -93,15 +93,16 @@ overlay. A trusted project may therefore configure the Lead that works on its
|
|
|
93
93
|
branch. A Lead that is already live is not hot-reconfigured; changed launch
|
|
94
94
|
policy takes effect on its next start.
|
|
95
95
|
|
|
96
|
-
See [`
|
|
97
|
-
[`
|
|
96
|
+
See [`delegate_work`](../reference/staff.md#delegate_work) and
|
|
97
|
+
[`resume_work`](../reference/staff.md#resume_work).
|
|
98
98
|
|
|
99
|
-
Files supplied to `
|
|
99
|
+
Files supplied to `delegate_work` are retained as required evidence for the
|
|
100
100
|
assignment and delivered to future delegated descendants. To make later
|
|
101
101
|
review material a continuing requirement while sending it to an assigned
|
|
102
102
|
Lead, a Manager uses `message_staff` with `retain: true`; the message text and
|
|
103
|
-
files then become required
|
|
104
|
-
|
|
103
|
+
files then become required evidence for that assignment. The Manager alone controls
|
|
104
|
+
its requirements; sibling Lead assignments do not automatically share evidence.
|
|
105
|
+
Leads delegate corrections with recipient-specific
|
|
105
106
|
`files` and send continuing findings through `message_supervisor.files` for
|
|
106
107
|
Manager evaluation. On supported operations, omitted or false `retain` keeps
|
|
107
108
|
files limited to that handoff. Retention
|
|
@@ -110,7 +111,7 @@ explicit rather than falling back to an ordinary handoff. Ordinary Leads have
|
|
|
110
111
|
no automatic evidence scope. See [required assignment evidence](handoffs.md#required-assignment-evidence)
|
|
111
112
|
and the [`message_staff`](../reference/staff.md#message_staff) and
|
|
112
113
|
[`delegate_agent`](../reference/agent.md#delegate_agent) references.
|
|
113
|
-
To remove
|
|
114
|
+
To remove assignment-owned requirements, open the project assignment action menu,
|
|
114
115
|
choose **Retained evidence**, select the entry by ID, name, and origin, then
|
|
115
116
|
**Remove requirement…** and confirm **Remove requirement**. Inherited baseline
|
|
116
117
|
entries are protected. Removal leaves the snapshot, source file, and evidence
|
|
@@ -135,7 +136,7 @@ independent enough to justify separate branch and execution boundaries.
|
|
|
135
136
|
## Integrate completed branches
|
|
136
137
|
|
|
137
138
|
When an assigned Lead has completed and validated its branch, the Manager can
|
|
138
|
-
accept its exact source commit and use the Manager-only `
|
|
139
|
+
accept its exact source commit and use the Manager-only `integrate_branch` staff
|
|
139
140
|
tool to fast-forward the verified primary branch. This is local Git
|
|
140
141
|
integration; it does not fetch, push, or merge a hosted pull request. The source
|
|
141
142
|
and target must be clean, and a branch that does not contain the current target
|
|
@@ -209,7 +210,7 @@ retry the model run or replay tool calls automatically. Before continuing the
|
|
|
209
210
|
same assigned session, inspect its transcript and any external effects because
|
|
210
211
|
a failed execution may have partially acted. Send an authorized message to the
|
|
211
212
|
exact live, idle Lead to continue; resume a deliberately stopped Lead with
|
|
212
|
-
`
|
|
213
|
+
`resume_work` on its branch. Do not create a second writer or treat
|
|
213
214
|
cancellation as a request to resume. Missing or conflicting runtime identity
|
|
214
215
|
fails closed; verify current assignment and supervisor authority before acting.
|
|
215
216
|
Managers should treat routine results as informational and act when useful
|
|
@@ -223,10 +224,10 @@ evidence only when it materially matters.
|
|
|
223
224
|
|
|
224
225
|
`stop_lead` stops a Lead and its owned Agent execution tree while preserving
|
|
225
226
|
the assignment, Pi session, Git branch, and worktree. Resume the same work with
|
|
226
|
-
`
|
|
227
|
+
`resume_work` using its branch. `stop_lead` does not resolve project work.
|
|
227
228
|
|
|
228
229
|
See [`stop_lead`](../reference/staff.md#stop_lead) and
|
|
229
|
-
[`
|
|
230
|
+
[`resume_work`](../reference/staff.md#resume_work).
|
|
230
231
|
|
|
231
232
|
## Retire project work
|
|
232
233
|
|
package/docs/guides/recovery.md
CHANGED
|
@@ -69,6 +69,14 @@ an externally blocked runtime. Do not delegate a new task to a blocked agent.
|
|
|
69
69
|
- launch handoff;
|
|
70
70
|
- one-shot cleanup.
|
|
71
71
|
|
|
72
|
+
If owner-side revalidation or import of an explicitly forwarded result artifact
|
|
73
|
+
fails, the durable completion remains pending and undelivered; delivery retries
|
|
74
|
+
automatically and fails closed. While the state is `settling`, inspect the
|
|
75
|
+
current error in `list_agents` as `cleanup_error`. Restoring access to the same
|
|
76
|
+
artifact permits delivery. Do not substitute evidence or acknowledge success.
|
|
77
|
+
There is no permanent-loss classification, retry limit, timeout, or automatic
|
|
78
|
+
escalation for this condition.
|
|
79
|
+
|
|
72
80
|
Do not delegate another task yet.
|
|
73
81
|
|
|
74
82
|
If nothing independent remains, end the turn normally and let result/attention
|
|
@@ -105,7 +113,7 @@ Failure reporting does not retry the model run, replay tools, stop child Agents,
|
|
|
105
113
|
or complete project work. Continue only the same exact authorized session or
|
|
106
114
|
assignment after inspecting whether prior tools or external actions may have
|
|
107
115
|
taken effect. Use the existing authorized coordination path to ask a live,
|
|
108
|
-
idle Lead to continue; use `
|
|
116
|
+
idle Lead to continue; use `resume_work` for a deliberately stopped assigned
|
|
109
117
|
Lead. Do not start a second process or blindly repeat an operation. Cancellation
|
|
110
118
|
does not automatically resume.
|
|
111
119
|
|
|
@@ -153,8 +153,8 @@ inherited according to this precedence:
|
|
|
153
153
|
| fresh `delegate` | current spawning controller session |
|
|
154
154
|
| nested fresh `delegate` | current spawning managed-agent session |
|
|
155
155
|
| `continue` | saved Pi session |
|
|
156
|
-
| fresh managed Lead from `
|
|
157
|
-
| restarted managed Lead from `
|
|
156
|
+
| fresh managed Lead from `delegate_work` | current Manager session |
|
|
157
|
+
| restarted managed Lead from `resume_work` | saved Pi session |
|
|
158
158
|
| any operation with an explicit definition field | explicit definition value |
|
|
159
159
|
|
|
160
160
|
Model and thinking resolve independently, so either field can be explicit while
|
|
@@ -59,6 +59,14 @@ Examples include an uncompleted task handoff, pending final result delivery,
|
|
|
59
59
|
direct-agent gating, terminal cleanup, result persistence recovery, and startup
|
|
60
60
|
or integration handoff. Do not assign another task to a settling agent.
|
|
61
61
|
|
|
62
|
+
If owner-side revalidation or import of an explicitly forwarded result artifact
|
|
63
|
+
fails, the durable completion remains pending and undelivered; delivery retries
|
|
64
|
+
automatically and fails closed. While the state is `settling`, `list_agents`
|
|
65
|
+
exposes the current error as `cleanup_error`. Restoring access to the same
|
|
66
|
+
artifact permits delivery. Do not substitute evidence or acknowledge success.
|
|
67
|
+
There is no permanent-loss classification, retry limit, timeout, or automatic
|
|
68
|
+
escalation for this condition.
|
|
69
|
+
|
|
62
70
|
`settling` alone is not timeout-worthy and does not generate generic health
|
|
63
71
|
attention. A durable `result_error` within settling may still produce direct
|
|
64
72
|
owner attention so the stored persistence recovery can be handled.
|
package/docs/reference/agent.md
CHANGED
|
@@ -15,6 +15,7 @@ close_agent
|
|
|
15
15
|
inspect_agent
|
|
16
16
|
read_agent_transcript
|
|
17
17
|
read_evidence
|
|
18
|
+
attach_handoff
|
|
18
19
|
```
|
|
19
20
|
|
|
20
21
|
Each tool accepts only its operation's fields. Schemas require necessary fields
|
|
@@ -24,7 +25,25 @@ and authorized delegating-agent controllers. Root fresh-delegation eligibility
|
|
|
24
25
|
follows the active role: Leads retain their existing policy, while Manager and
|
|
25
26
|
Chief are limited to their effective `agents` allowlist. Existing ownership
|
|
26
27
|
controls remain available for the root session's own Agents when fresh
|
|
27
|
-
delegation is disabled.
|
|
28
|
+
delegation is disabled. `attach_handoff` is available only to managed Agents.
|
|
29
|
+
|
|
30
|
+
## `attach_handoff`
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"files": ["result:scout#21"]
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
A managed Agent can use `attach_handoff` to select exact semantic result refs
|
|
39
|
+
for its eventual completion to its direct owner. This is a non-blocking
|
|
40
|
+
completion selection, not a separate message or evidence-transfer channel; the
|
|
41
|
+
ordinary completion still carries the Agent's final text. Only verified
|
|
42
|
+
semantic result refs available on the current Pi branch are accepted, and
|
|
43
|
+
their artifacts are revalidated when the assignment settles. A successful
|
|
44
|
+
call replaces the prior selection; `files: []` clears it. A ref mentioned only
|
|
45
|
+
in completion text is not selected or made forwardable. The owner receives a
|
|
46
|
+
short inventory of successfully imported refs, not embedded artifact contents.
|
|
28
47
|
|
|
29
48
|
## `delegate_agent`
|
|
30
49
|
|
|
@@ -53,7 +72,7 @@ Eligible managed-Agent controllers additionally accept optional boolean
|
|
|
53
72
|
`retain`, defaulting to `false`. Omitted or false means `files` apply only
|
|
54
73
|
to this handoff. With `retain: true`, supplied files become required evidence
|
|
55
74
|
in the Agent's local assignment for its own descendants only. Task text is not
|
|
56
|
-
retained. Inherited
|
|
75
|
+
retained. Inherited assignment requirements cannot be removed or changed by a
|
|
57
76
|
managed Agent. Retention validates assignment authority and evidence and fails
|
|
58
77
|
explicitly rather than falling back to ordinary delegation; if retention is
|
|
59
78
|
persisted but delivery fails, the result reports that partial outcome.
|
|
@@ -338,13 +338,13 @@ case it invokes the same guarded operation without another confirmation.
|
|
|
338
338
|
See [Staff tools](staff.md#remove_worktree) for the result contract.
|
|
339
339
|
|
|
340
340
|
Local branch integration is exposed to an authorized Manager through the
|
|
341
|
-
`
|
|
341
|
+
`integrate_branch` staff tool, not a `/manager` slash command or Manager overview
|
|
342
342
|
action. Its separate opt-in is available in Settings and in the verified
|
|
343
343
|
Manager's project overrides (`Inherit / On / Off`); enabling either policy
|
|
344
344
|
requires typing `enable`. The authorization is stored in user-wide Herdsman
|
|
345
345
|
configuration. See
|
|
346
346
|
[Configuration](configuration.md#manager-local-merge) and
|
|
347
|
-
[Staff tools](staff.md#
|
|
347
|
+
[Staff tools](staff.md#integrate_branch).
|
|
348
348
|
|
|
349
349
|
An eligible ordinary Lead can activate runtime Chief mode with `/chief`.
|
|
350
350
|
While Chief, `/chief` refreshes its validated profile after the current turn
|
package/docs/reference/peer.md
CHANGED
|
@@ -119,13 +119,60 @@ on enabled, reachable saved Herdr machines. An ordinary Lead similarly
|
|
|
119
119
|
discovers only remote Leads verified as ordinary and unassigned by the remote
|
|
120
120
|
machine's authoritative assignment scan. Managed or assigned Leads are not
|
|
121
121
|
remote federation targets. Those entries retain the exact Pi session ID and
|
|
122
|
-
include a `machine` display label.
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
122
|
+
include a `machine` display label. If remote Lead eligibility cannot be
|
|
123
|
+
verified, that machine does not contribute Lead results; an incomplete scan
|
|
124
|
+
does not mean that no eligible Leads exist. Labels are not authority. Remote
|
|
125
|
+
transport requires an independently working noninteractive OpenSSH target with
|
|
126
|
+
normal strict host-key verification. `ssh://` targets and SSH-config aliases
|
|
127
|
+
are supported; Herdr-only temporary authentication is not.
|
|
128
|
+
|
|
129
|
+
An eligible peer in `peers` has been verified for discovery, but
|
|
130
|
+
`message_peer` still revalidates identity and authority when sending. A peer in
|
|
131
|
+
`reply_only` has an existing authorized return correspondence: its reply can
|
|
132
|
+
be queued even though its current independent availability is unverified.
|
|
133
|
+
Neither display metadata nor a diagnostic observation makes a target
|
|
134
|
+
addressable. Discovery failures appear as an optional `remote_diagnostics`
|
|
135
|
+
array and do not hide peers discovered successfully elsewhere:
|
|
136
|
+
|
|
137
|
+
```json
|
|
138
|
+
{
|
|
139
|
+
"remote_diagnostics": [
|
|
140
|
+
{
|
|
141
|
+
"machine": "base",
|
|
142
|
+
"reason": "build_mismatch",
|
|
143
|
+
"peer": "worker",
|
|
144
|
+
"local_build": "v0.34.1 · 0123456789ab",
|
|
145
|
+
"remote_build": "v0.34.0 · fedcba987654"
|
|
146
|
+
}
|
|
147
|
+
]
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Each diagnostic has one of these reasons:
|
|
152
|
+
|
|
153
|
+
- `machine_list_failed`: Herdr's saved machine list could not be read.
|
|
154
|
+
- `herdr_not_reachable`: Herdr did not confirm reachability for the saved
|
|
155
|
+
machine; this does not establish that its physical host is offline.
|
|
156
|
+
- `probe_failed`: the remote peer probe failed before identity was established.
|
|
157
|
+
- `build_mismatch`: an observed peer has valid build evidence that differs from
|
|
158
|
+
this runtime. The affected peer is excluded from `peers`.
|
|
159
|
+
- `build_unverified`: an observed peer has missing or invalid build evidence
|
|
160
|
+
and is excluded from `peers`.
|
|
161
|
+
- `eligibility_unverified`: a remote ordinary-Lead assignment scan was
|
|
162
|
+
incomplete. That machine contributes no Lead results; this does not assert
|
|
163
|
+
that it has no eligible Leads.
|
|
164
|
+
|
|
165
|
+
`machine` and optional `peer` values are bounded display hints, not target
|
|
166
|
+
handles. Build fields appear only for validated build mismatches. Diagnostics
|
|
167
|
+
contain no connection targets, credentials, or raw transport errors; they are
|
|
168
|
+
observations, never authorization records. A complete scan with no eligible
|
|
169
|
+
peers is a normal empty result and needs no diagnostic. A listing, reachability,
|
|
170
|
+
probe, or eligibility diagnostic means discovery is incomplete even when other
|
|
171
|
+
peers were found; build diagnostics report observed peers that were excluded.
|
|
172
|
+
`remote_diagnostics` contains at most 20 entries. If more were observed,
|
|
173
|
+
`remote_diagnostics_omitted` gives the exact additional count; total warnings
|
|
174
|
+
are the array length plus that count. Expanded Pi output also reports any
|
|
175
|
+
diagnostics it omits from display.
|
|
129
176
|
|
|
130
177
|
```json
|
|
131
178
|
{
|
package/docs/reference/staff.md
CHANGED
|
@@ -7,8 +7,8 @@ use `list_staff`, `inspect_staff`, and `message_staff`; `read_staff_transcript`
|
|
|
7
7
|
is available when persisted session evidence is available. Manager and Chief
|
|
8
8
|
have the same direct-report observation and communication capabilities.
|
|
9
9
|
Manager additionally has
|
|
10
|
-
the branch-based project operations `
|
|
11
|
-
`stop_lead`, `remove_worktree`, and `
|
|
10
|
+
the branch-based project operations `delegate_work`, `resume_work`,
|
|
11
|
+
`stop_lead`, `remove_worktree`, and `integrate_branch`. Chief has no
|
|
12
12
|
project-operation tools.
|
|
13
13
|
|
|
14
14
|
Lead-targeted actions use the exact full Pi `session` ID from a fresh
|
|
@@ -115,26 +115,27 @@ forward.
|
|
|
115
115
|
`retain` is optional and defaults to `false`. Set it to `true` only when the
|
|
116
116
|
message text and supplied files should become continuing required evidence
|
|
117
117
|
for the target's verified project assignment. The target must be an assigned
|
|
118
|
-
project Lead; ordinary supervised Leads have no
|
|
118
|
+
project Lead; ordinary supervised Leads have no assignment evidence scope.
|
|
119
119
|
Retention validates authority and evidence and fails explicitly when either is
|
|
120
120
|
unavailable; it is never silently treated as an ordinary message. Retention
|
|
121
121
|
and message delivery are one logical operation, but if persistence succeeds
|
|
122
122
|
and delivery fails, the outcome reports that partial success rather than
|
|
123
|
-
claiming the handoff completed. Initial `
|
|
123
|
+
claiming the handoff completed. Initial `delegate_work.files` are required
|
|
124
124
|
as well. See [Handoffs and files](../guides/handoffs.md#required-assignment-evidence).
|
|
125
125
|
|
|
126
|
-
### Manage
|
|
126
|
+
### Manage assignment required evidence
|
|
127
127
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
128
|
+
Each assignment's required evidence is Manager-owned; sibling Lead assignments
|
|
129
|
+
do not automatically share it. The assignment's **Retained evidence** menu shows
|
|
130
|
+
requirement IDs, names, and origins and allows removal of assignment-owned
|
|
131
|
+
entries. Inherited baseline entries are protected, and
|
|
131
132
|
removal leaves snapshots, source files, and evidence already accepted by
|
|
132
133
|
Agents unchanged. Managed-Agent-local additions have no independent UI or
|
|
133
134
|
model-facing removal tool. See [Project orchestration](../guides/project-orchestration.md#start-and-resume-project-work)
|
|
134
135
|
for the procedure; assigned Leads use delegation `files` for recipient-specific
|
|
135
136
|
evidence.
|
|
136
137
|
|
|
137
|
-
## `
|
|
138
|
+
## `delegate_work`
|
|
138
139
|
|
|
139
140
|
Manager only. Start new project work with a required `task` and optional
|
|
140
141
|
`branch`, `base`, and `files`:
|
|
@@ -143,7 +144,7 @@ Manager only. Start new project work with a required `task` and optional
|
|
|
143
144
|
{ "task": "Implement the change", "branch": "feat/example" }
|
|
144
145
|
```
|
|
145
146
|
|
|
146
|
-
An existing assignment on that branch is rejected; use `
|
|
147
|
+
An existing assignment on that branch is rejected; use `resume_work` to
|
|
147
148
|
continue it. An unoccupied existing Herdr worktree may still be reused for new
|
|
148
149
|
work. A different live Lead occupying that worktree prevents another managed
|
|
149
150
|
writer.
|
|
@@ -160,7 +161,7 @@ preserved snapshot.
|
|
|
160
161
|
Manager-created Leads inherit the Manager session's effective project-trust
|
|
161
162
|
decision for that run; this does not modify Pi's persistent trust store.
|
|
162
163
|
|
|
163
|
-
## `
|
|
164
|
+
## `resume_work`
|
|
164
165
|
|
|
165
166
|
Manager only. Resume existing unresolved project work using its exact branch:
|
|
166
167
|
|
|
@@ -173,7 +174,7 @@ Resuming already-running work returns the current exact Lead instead of
|
|
|
173
174
|
starting another. A stopped Lead is relaunched with the same assignment while
|
|
174
175
|
its worktree exists. Verified checkout absence retires the assignment rather
|
|
175
176
|
than recreating it. A retired assignment cannot be resumed; new work may use
|
|
176
|
-
`
|
|
177
|
+
`delegate_work` with the remaining branch.
|
|
177
178
|
|
|
178
179
|
## `stop_lead`
|
|
179
180
|
|
|
@@ -184,7 +185,7 @@ than recreating it. A retired assignment cannot be resumed; new work may use
|
|
|
184
185
|
Stops only an exact currently assigned project Lead and its owned Agent
|
|
185
186
|
execution tree. The assignment, Pi session, Git branch, and worktree are
|
|
186
187
|
preserved. Resume the work with
|
|
187
|
-
`
|
|
188
|
+
`resume_work` using its branch. An unassigned Lead is not a Manager staff-stop
|
|
188
189
|
target. Failed or ambiguous cleanup does not retire an assignment. Successful
|
|
189
190
|
Herdr worktree removal or verified checkout absence retires the assignment and
|
|
190
191
|
removes pending project messages. Failed or ambiguous inventory preserves the
|
|
@@ -241,7 +242,7 @@ false value is not proof that the assignment remains. Overall success requires
|
|
|
241
242
|
both checkout absence and assignment retirement to be confirmed. Removal never
|
|
242
243
|
deletes the Git branch or Pi conversation.
|
|
243
244
|
|
|
244
|
-
## `
|
|
245
|
+
## `integrate_branch`
|
|
245
246
|
|
|
246
247
|
Manager only. Integrate an assigned local branch into the verified primary
|
|
247
248
|
branch using fast-forward-only Git:
|
|
@@ -33,7 +33,11 @@ Selection and lifecycle remain separate: `>` means
|
|
|
33
33
|
selected, `●` means working, `◐` means blocked,
|
|
34
34
|
`◌` means settling or starting, `○` means idle or done, `?` means unknown, and
|
|
35
35
|
`×` means lost. An idle or done lead with active delegated descendants uses
|
|
36
|
-
|
|
36
|
+
`◉` in accent styling. Lifecycle labels use success for working, accent for
|
|
37
|
+
starting and settling, warning for blocked and unknown, error for lost, and
|
|
38
|
+
muted for idle and done. The leading `●` in a widget header is a
|
|
39
|
+
success-colored identity marker for the status surface, not proof of active
|
|
40
|
+
execution. Workspace labels are presentation text inside each lead row, not
|
|
37
41
|
additional hierarchy nodes. For example, a Manager with one Lead child appears
|
|
38
42
|
as:
|
|
39
43
|
|
|
@@ -77,12 +81,17 @@ widget; context is Pi's current context percentage. Both are best-effort
|
|
|
77
81
|
presentation metadata and unavailable values are omitted. Under width pressure,
|
|
78
82
|
elapsed is dropped before context. Manager work status remains distinct from
|
|
79
83
|
the live Lead's runtime state. Chief rows receive matching theme styling but do
|
|
80
|
-
not show these telemetry columns.
|
|
84
|
+
not show these telemetry columns. A stale Manager snapshot suppresses elapsed
|
|
85
|
+
telemetry while retaining other available metadata such as context percentage.
|
|
81
86
|
|
|
82
87
|
Manager work status is `active`, `paused`, or `conflict`.
|
|
83
88
|
An active row uses the live Lead's lifecycle marker when an executor is present;
|
|
84
|
-
|
|
85
|
-
|
|
89
|
+
without a verified Lead it uses a muted `·`, not a claim of verified execution.
|
|
90
|
+
Paused uses `○`; conflict uses warning-colored `!`. A blocked Lead uses its
|
|
91
|
+
warning-colored `◐` lifecycle marker without an additional `!`. Independently
|
|
92
|
+
verified build incompatibility is shown with `!` and `build mismatch`. For
|
|
93
|
+
compatible work, the row suffix is project status, not the Lead's runtime
|
|
94
|
+
state.
|
|
86
95
|
Ordinary Leads supervised by the Manager are shown separately from project
|
|
87
96
|
work, with a supervised label; they are not treated as managed work. A Manager
|
|
88
97
|
can inspect an eligible direct report through the overview, independently of
|
|
@@ -133,10 +142,14 @@ against the caller's durable ownership ancestry; Manager targets for project
|
|
|
133
142
|
control require the Lead's current exact project assignment. Direct-report
|
|
134
143
|
inspection and messaging use their own fresh supervision authorization;
|
|
135
144
|
focus/navigation alone grants neither. Chief-visible nested Leads remain
|
|
136
|
-
observational.
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
145
|
+
observational. A visible truncated Manager project-work branch can focus its
|
|
146
|
+
exact verified Lead only for a fresh, active row with a compatible Lead; only
|
|
147
|
+
the rendered branch segment is clickable, not its status suffix. Paused or
|
|
148
|
+
conflicted project work, incompatible Leads, lost or unresolved sessions,
|
|
149
|
+
stale projections, wholly hidden labels, omitted entries, and targets without
|
|
150
|
+
a uniquely verified live Herdr pane are inert. Current placement is checked
|
|
151
|
+
again when a click is handled; the status projection itself is never
|
|
152
|
+
authorization.
|
|
140
153
|
|
|
141
154
|
Headless mode has no UI-only periodic supervision observation. Explicit and
|
|
142
155
|
model-context refreshes still acquire fresh state. A refresh failure never
|
|
@@ -212,6 +225,13 @@ After a later refresh failure, the widget retains the last valid snapshot and
|
|
|
212
225
|
marks the header `stale`.
|
|
213
226
|
|
|
214
227
|
Header refresh staleness is not agent inactivity.
|
|
228
|
+
Stale and unavailable labels use warning styling. Freshness is prioritized
|
|
229
|
+
over counts and optional metadata: when width permits, the identity is
|
|
230
|
+
shortened to retain the freshness label. At extremely narrow widths, the label
|
|
231
|
+
may itself be truncated. Identity-only Agent headers retain freshness without
|
|
232
|
+
Agent counts. Stale Agent herd-run and row elapsed values use the snapshot's
|
|
233
|
+
observation time (`refreshedAt`), and are omitted when `refreshedAt` is absent.
|
|
234
|
+
Agent inactivity metadata remains independently reported.
|
|
215
235
|
|
|
216
236
|
## Agent rows
|
|
217
237
|
|
|
@@ -229,12 +249,13 @@ then elapsed time, then context percentage; the same column choice is used for
|
|
|
229
249
|
every row. The task is the rightmost elastic field and is kept only when it has
|
|
230
250
|
useful room before it is truncated.
|
|
231
251
|
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
252
|
+
Lifecycle labels and static activity glyphs use the canonical markers and
|
|
253
|
+
semantic theme colors described above. The fixed-width Agent activity column
|
|
254
|
+
animates only working and starting rows, and only for a fresh, available
|
|
255
|
+
snapshot; settling is static, as are blocked, unknown, lost, and every row in a
|
|
256
|
+
stale or unavailable snapshot. A stale snapshot continues to show its last
|
|
257
|
+
observed lifecycle state, but elapsed values do not advance past that
|
|
258
|
+
observation.
|
|
238
259
|
While a controller-local start remains pending, an authoritative `settling`
|
|
239
260
|
row is presented as `starting` so launch and request handoff remain visually
|
|
240
261
|
continuous. `working`, `blocked`, and `unknown` authoritative states are never
|