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.
@@ -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 `merge_project` to fast-forward
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 corresponding to one Herdr Git
117
- worktree group: its primary workspace plus linked-worktree workspaces.
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
- ## Project work belongs to a branch
136
+ ## Work assignments belong to a branch
134
137
 
135
- Manager-delegated project work is durable and keyed by repository plus semantic
136
- Git branch.
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 project, Herdsman
156
- automatically returns each completed direct Lead response as a project message
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; `resume_project` resumes the existing
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
- `resume_project` cannot restore a retired assignment; a new delegation may
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
@@ -45,10 +45,11 @@ read_staff_transcript
45
45
  message_staff
46
46
 
47
47
  Manager only:
48
- delegate_project
49
- resume_project
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 `resume_project` resumes it.
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 `merge_project` calls/results: divergence returns `needs_update`
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 `delegate_project` action and report acknowledgment. This scenario
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
- `resume_project` when a running project Lead must restart with changed launch
170
+ `resume_work` when a running project Lead must restart with changed launch
171
171
  policy.
172
172
 
173
173
  ## Minimal model override
@@ -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 `delegate_project` task is preserved
20
- unchanged as `project-brief.md`; files supplied to `delegate_project` also
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 project's evidence set.
28
+ not retained, and it cannot modify the parent assignment's evidence set.
29
29
 
30
- The Manager alone controls project-wide requirements. Root Lead delegation
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 project requirements, send the relevant files or
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 project requirements; nested descendants also 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 project-owned requirements, the Manager uses the project's **Retained
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`, `delegate_project`, `message_staff`,
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`, `delegate_project`, `message_staff`,
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 `delegate_project`. Resume existing work with
71
- `resume_project` using its branch. A verified Git inventory showing the
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 [`delegate_project`](../reference/staff.md#delegate_project) and
97
- [`resume_project`](../reference/staff.md#resume_project).
96
+ See [`delegate_work`](../reference/staff.md#delegate_work) and
97
+ [`resume_work`](../reference/staff.md#resume_work).
98
98
 
99
- Files supplied to `delegate_project` are retained as required evidence for the
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 project evidence. The Manager alone controls
104
- project requirements. Leads delegate corrections with recipient-specific
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 project-owned requirements, open the project assignment action menu,
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 `merge_project` staff
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
- `resume_project` on its branch. Do not create a second writer or treat
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
- `resume_project` using its branch. `stop_lead` does not resolve project work.
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
- [`resume_project`](../reference/staff.md#resume_project).
230
+ [`resume_work`](../reference/staff.md#resume_work).
230
231
 
231
232
  ## Retire project work
232
233
 
@@ -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 `resume_project` for a deliberately stopped assigned
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 `delegate_project` | current Manager session |
157
- | restarted managed Lead from `resume_project` | saved Pi session |
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.
@@ -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 project requirements cannot be removed or changed by a
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
- `merge_project` staff tool, not a `/manager` slash command or Manager overview
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#merge_project).
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
@@ -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. Reachable-machine probe failures are
123
- reported separately as `unavailable_machines`. If remote Lead eligibility
124
- cannot be verified, that machine does not contribute Lead results; an
125
- incomplete scan does not mean that no eligible Leads exist. Labels are not
126
- authority. Remote transport requires an independently working noninteractive
127
- OpenSSH target with normal strict host-key verification. `ssh://` targets and
128
- SSH-config aliases are supported; Herdr-only temporary authentication is not.
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
  {
@@ -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 `delegate_project`, `resume_project`,
11
- `stop_lead`, `remove_worktree`, and `merge_project`. Chief has no
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 project evidence scope.
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 `delegate_project.files` are required
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 project required evidence
126
+ ### Manage assignment required evidence
127
127
 
128
- Project-wide required evidence is Manager-owned. The project's **Retained
129
- evidence** menu shows requirement IDs, names, and origins and allows removal
130
- of project-owned entries. Inherited baseline entries are protected, and
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
- ## `delegate_project`
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 `resume_project` to
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
- ## `resume_project`
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
- `delegate_project` with the remaining branch.
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
- `resume_project` using its branch. An unassigned Lead is not a Manager staff-stop
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
- ## `merge_project`
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
- `◉`. Workspace labels are presentation text inside each lead row, not
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
- otherwise it uses `●`. Paused uses `○` and conflict uses `!`. The row suffix is
85
- project status, not the Lead's runtime state.
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. Paused or conflicted project work, lost or unresolved sessions,
137
- stale projections, truncated/omitted entries, and targets without a uniquely
138
- verified live Herdr pane are inert. Current placement is checked again when a
139
- click is handled; the status projection itself is never authorization.
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
- The fixed-width activity column animates working, settling, and starting rows;
233
- blocked, unknown, and lost rows show their static lifecycle marker in that
234
- column. Working rows use `● working`, blocked rows use `◐ blocked`, settling rows use
235
- `◌ settling`, starting rows use `◌ starting`, unknown rows use `? unknown`, and
236
- lost rows use `× lost` with the theme's attention/error styling. Working,
237
- settling, and starting animate; blocked, unknown, and lost rows are static.
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