pi-herdsman 0.36.0 → 0.36.2
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 +11 -2
- package/dist/index.js +10921 -10725
- package/dist/index.js.map +4 -4
- package/dist/peer-bridge.js.map +2 -2
- package/dist/roles/manager.md +12 -3
- package/docs/concepts/coordination.md +11 -0
- package/docs/coordination-api.md +3 -1
- package/docs/development/instruction-interface-design.md +14 -0
- package/docs/development/validation.md +12 -8
- package/docs/guides/project-orchestration.md +10 -2
- package/docs/guides/recovery.md +52 -0
- package/docs/reference/staff.md +15 -9
- package/docs/reference/status-widget.md +9 -7
- package/docs/reference/supervisor.md +3 -2
- package/package.json +3 -1
package/dist/roles/manager.md
CHANGED
|
@@ -10,9 +10,12 @@ Coordinate assigned project work through Leads.
|
|
|
10
10
|
|
|
11
11
|
Set priorities, resolve project-level decisions and dependency sequencing,
|
|
12
12
|
review outcomes, and request corrections through the responsible Lead.
|
|
13
|
-
When assigned Leads need
|
|
14
|
-
|
|
15
|
-
or
|
|
13
|
+
When assigned Leads need technical information from one another, prefer
|
|
14
|
+
direct peer coordination when eligible. Mediate when peer communication is
|
|
15
|
+
unavailable or a project-level decision is needed. Resolve concrete
|
|
16
|
+
cross-assignment scope, priority, or sequencing conflicts with the smallest
|
|
17
|
+
decision needed for progress. Do not require repeated confirmations before
|
|
18
|
+
unaffected work continues.
|
|
16
19
|
Leave technical investigation, implementation, review, validation, and
|
|
17
20
|
integration to that Lead and its Agents rather than doing or delegating
|
|
18
21
|
the work yourself.
|
|
@@ -29,3 +32,9 @@ the Lead retains technical resolution and validation ownership.
|
|
|
29
32
|
|
|
30
33
|
Treat routine progress as informational. Intervene when a project-level
|
|
31
34
|
decision or meaningful coordination is needed.
|
|
35
|
+
|
|
36
|
+
Recover stopped assigned work rather than repeatedly inspecting or resuming a
|
|
37
|
+
running Lead. Communicate with eligible running Leads when coordination is
|
|
38
|
+
needed. After a staff-action failure, act on new relevant evidence or the
|
|
39
|
+
reported blocker; do not repeat unchanged attempts. Continue independent
|
|
40
|
+
coordination or end the turn for event-driven updates.
|
|
@@ -203,6 +203,17 @@ Coordination crosses one authority edge at a time:
|
|
|
203
203
|
| Sideways | `message_peer` | Lead <-> Lead or Manager <-> Manager |
|
|
204
204
|
| Ownership | Agent controls / `reply_agent`; `ask_owner` | owner <-> directly owned Agent |
|
|
205
205
|
|
|
206
|
+
### Coordination does not imply dependency
|
|
207
|
+
|
|
208
|
+
A peer message, shared source file, or pending supervisor question does not
|
|
209
|
+
by itself suspend an assignment. Leads continue independently safe work and
|
|
210
|
+
defer only steps with actual prerequisites.
|
|
211
|
+
|
|
212
|
+
Technical conflicts remain with the responsible Leads. The Manager resolves
|
|
213
|
+
cross-assignment scope, priority, and sequencing decisions when needed.
|
|
214
|
+
When no independent work remains, ordinary reporting and event-driven
|
|
215
|
+
continuation replace repeated messages or polling.
|
|
216
|
+
|
|
206
217
|
A supervisor may observe bounded descendant state without gaining descendant
|
|
207
218
|
control. Questions and messages are not implicitly forwarded through
|
|
208
219
|
intermediate coordinators.
|
package/docs/coordination-api.md
CHANGED
|
@@ -63,7 +63,9 @@ message_supervisor
|
|
|
63
63
|
|
|
64
64
|
Managed Leads use nonblocking `message_supervisor` for timely questions,
|
|
65
65
|
clarifications, or warnings needed before the automatic completed-result
|
|
66
|
-
handoff.
|
|
66
|
+
handoff. Continue independently safe work while a reply is pending. Defer only
|
|
67
|
+
steps that genuinely require the response; when no actionable work remains,
|
|
68
|
+
end the turn and rely on normal message delivery rather than polling.
|
|
67
69
|
Routine information that can wait belongs in the result; there is no
|
|
68
70
|
message/result deduplication. `stop_lead` pauses execution without removing the
|
|
69
71
|
assignment, and `resume_work` resumes it.
|
|
@@ -59,6 +59,20 @@ Every representation must preserve the same semantics. When practical, projectio
|
|
|
59
59
|
|
|
60
60
|
When representations drift or conflict, fix the underlying invariant and its projections rather than adding clarification around the inconsistency.
|
|
61
61
|
|
|
62
|
+
## Keep coordination convergent
|
|
63
|
+
|
|
64
|
+
Coordination should produce actionable information, a decision, an identified
|
|
65
|
+
blocker, or normal completion, rather than further coordination by default.
|
|
66
|
+
|
|
67
|
+
An overlapping assignment or unanswered message does not itself create an
|
|
68
|
+
execution dependency. Continue independently safe work, defer only genuinely
|
|
69
|
+
dependent steps, and end idle turns rather than polling for responses.
|
|
70
|
+
|
|
71
|
+
Resolve questions at the lowest appropriate ownership level. Supervisors
|
|
72
|
+
settle decisions within their authority without taking over technical
|
|
73
|
+
execution or requiring unnecessary agreement. Preserve actual authority,
|
|
74
|
+
writer-safety, and dependent-work constraints.
|
|
75
|
+
|
|
62
76
|
## Keep replaceable definitions strategy-only
|
|
63
77
|
|
|
64
78
|
Bundled Agent and role definition bodies describe specialization,
|
|
@@ -190,14 +190,18 @@ workflow. The existing required `CI` check fails when required
|
|
|
190
190
|
smoke does not succeed. Documentation-only and test-only changes normally skip
|
|
191
191
|
it.
|
|
192
192
|
|
|
193
|
-
The `Validate` workflow classifies Node tests, package, container,
|
|
194
|
-
smoke, peer federation, and Windows bootstrap acceptance independently.
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
193
|
+
The `Validate` workflow classifies formatting, Node tests, package, container,
|
|
194
|
+
simulated smoke, peer federation, and Windows bootstrap acceptance independently.
|
|
195
|
+
Contributor-only documentation avoids package and runtime checks. Published docs
|
|
196
|
+
and skills still require the package audit, including its private-material
|
|
197
|
+
screening; Docker runtime instructions remain container inputs. Non-formatable
|
|
198
|
+
assets skip Prettier, and installer and release workflow edits select their
|
|
199
|
+
existing tests. Federation acceptance exercises the actual containerized
|
|
200
|
+
Pi/Herdr integration in separate Manager and ordinary Lead phases. Unknown
|
|
201
|
+
changes select conservative checks. A skipped conditional job is valid only
|
|
202
|
+
when the classifier says it is not required; the aggregate `CI` check fails
|
|
203
|
+
closed for missing or unsuccessful required jobs. Local `npm run validate`
|
|
204
|
+
remains unchanged and does not replace hosted integration acceptance.
|
|
201
205
|
|
|
202
206
|
Simulated acceptance uses real Pi, Herdsman, and Herdr processes without model
|
|
203
207
|
credentials. It does not verify real-model decisions. CI runs `core`,
|
|
@@ -133,6 +133,12 @@ not imply ownership, and Manager must not start another writer beside a Lead
|
|
|
133
133
|
that already occupies the relevant worktree. Use separate Leads when work is
|
|
134
134
|
independent enough to justify separate branch and execution boundaries.
|
|
135
135
|
|
|
136
|
+
Two Leads modifying the same module on separate branches may coordinate their
|
|
137
|
+
interface expectations while continuing independent implementation. If an
|
|
138
|
+
actual incompatible dependency emerges, the Manager clarifies ownership or
|
|
139
|
+
sequencing, and only dependent steps wait. Integrating branches sequentially
|
|
140
|
+
does not necessarily require implementing them sequentially.
|
|
141
|
+
|
|
136
142
|
## Integrate completed branches
|
|
137
143
|
|
|
138
144
|
When an assigned Lead has completed and validated its branch, the Manager can
|
|
@@ -167,8 +173,10 @@ close project work: assignments remain open through
|
|
|
167
173
|
review and requested corrections. Routine information that can wait should go
|
|
168
174
|
through the automatic result handoff. A managed Lead may use nonblocking
|
|
169
175
|
`message_supervisor` for a timely question, clarification, warning, or other
|
|
170
|
-
information the Manager needs before that boundary
|
|
171
|
-
|
|
176
|
+
information the Manager needs before that boundary. Continue independently
|
|
177
|
+
safe work while a reply is pending. Defer only steps that genuinely require the
|
|
178
|
+
response; when no actionable work remains, end the turn and rely on normal
|
|
179
|
+
message delivery rather than polling. A later automatic result may repeat
|
|
172
180
|
some information; separate messages and results are not deduplicated.
|
|
173
181
|
|
|
174
182
|
Automatic project reports transfer summary text only, not files. A result
|
package/docs/guides/recovery.md
CHANGED
|
@@ -136,6 +136,36 @@ Refresh with `list_agents` and resolve the identity/lifecycle condition when new
|
|
|
136
136
|
evidence is available. If a cleanup or recovery error is present, inspect its
|
|
137
137
|
exact details.
|
|
138
138
|
|
|
139
|
+
### Continuing assigned work with an unresolved Agent
|
|
140
|
+
|
|
141
|
+
Keep three questions separate:
|
|
142
|
+
|
|
143
|
+
1. Is the Agent controllable under its exact identity and ownership?
|
|
144
|
+
2. Does current evidence establish, exclude within the supported observation
|
|
145
|
+
boundary, or leave unresolved potentially competing execution?
|
|
146
|
+
3. Is the work still within the Lead's own execution scope, or does it belong
|
|
147
|
+
to the unresolved Agent?
|
|
148
|
+
|
|
149
|
+
An unknown identity remains unmodifiable and does not by itself establish a
|
|
150
|
+
currently active competing writer. Use available current evidence for a
|
|
151
|
+
concrete decision and at most one bounded diagnostic read when needed; do not
|
|
152
|
+
repeat an unchanged identity investigation. A current Herdr inventory and
|
|
153
|
+
relevant pane process information can help assess competing execution, but
|
|
154
|
+
cannot establish ownership or prove that arbitrary background OS writers are
|
|
155
|
+
absent. If a potentially conflicting execution cannot be excluded, preserve
|
|
156
|
+
that scope and report the specific missing evidence or external action.
|
|
157
|
+
Continue only independently authorized work with no unresolved execution
|
|
158
|
+
conflict, and do not take over the unresolved Agent's assignment.
|
|
159
|
+
|
|
160
|
+
For example, if `agent-amber` becomes unknown after an interruption while its
|
|
161
|
+
Lead still has independent `agent-blue` work, the Lead preserves the amber
|
|
162
|
+
assignment and does not try to control or replace it. The Lead may assess
|
|
163
|
+
current competing execution once for a necessary decision, then continue
|
|
164
|
+
blue's authorized scope if evidence permits; the Manager coordinates through
|
|
165
|
+
the Lead rather than reconstructing amber's historical identity. An externally
|
|
166
|
+
stopped process is a reason to refresh current observations, not to close the
|
|
167
|
+
unknown Agent automatically.
|
|
168
|
+
|
|
139
169
|
## Agent is `lost`
|
|
140
170
|
|
|
141
171
|
`lost` means the expected physical execution is proven gone before a durable
|
|
@@ -287,6 +317,28 @@ same target. Wait for the existing assignment to finish and clean up, or close
|
|
|
287
317
|
its exact live agent when abandoning it, then retry. Do not delegate another
|
|
288
318
|
task through an agent label.
|
|
289
319
|
|
|
320
|
+
## Native Pi restoration of a managed Agent
|
|
321
|
+
|
|
322
|
+
Pi's native session restore can reopen a managed Agent's transcript without
|
|
323
|
+
restoring its managed launch environment. Quarantine applies when Herdsman's
|
|
324
|
+
extension is loaded in a Herdr-hosted root Lead process. There, such a transcript
|
|
325
|
+
cannot run tools or assume an ordinary Lead role. Return to the original Lead
|
|
326
|
+
to reconcile the saved assignment; only its proven direct owner may use the
|
|
327
|
+
existing recovery and continuation controls. Transcript history and
|
|
328
|
+
working-tree changes are preserved, and the interrupted assignment is not
|
|
329
|
+
replayed automatically.
|
|
330
|
+
|
|
331
|
+
A process that is otherwise unmanaged—for example, one launched outside Herdr
|
|
332
|
+
without a valid managed-Agent environment—does not receive the root Lead
|
|
333
|
+
quarantine. If Pi is launched without Herdsman's extension, Herdsman cannot
|
|
334
|
+
enforce tool restrictions at all. Separately, when the extension detects an
|
|
335
|
+
invalid partial managed-Agent environment, its fail-closed hooks disable tools
|
|
336
|
+
and block tool calls even though normal role registration is skipped. Until
|
|
337
|
+
selective Herdr restoration is supported and verified, operators who need to
|
|
338
|
+
prevent Agent restoration before process launch can set Herdr's global
|
|
339
|
+
`resume_agents_on_restore = false` setting. This disables restoration globally,
|
|
340
|
+
not only for the affected Agent.
|
|
341
|
+
|
|
290
342
|
## Before retrying
|
|
291
343
|
|
|
292
344
|
Check:
|
package/docs/reference/staff.md
CHANGED
|
@@ -56,11 +56,14 @@ evidence. Use `list_staff` when a fresh complete roster is materially needed.
|
|
|
56
56
|
|
|
57
57
|
Returns a fresh direct-report projection and fresh `available_tools`. For
|
|
58
58
|
Manager, `work` lists durable project assignments by branch with derived status
|
|
59
|
-
and a bounded task summary. Status is `active`, `paused`,
|
|
60
|
-
work may include the live Lead's separate `runtime_state`.
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
59
|
+
and a bounded task summary. Status is `active`, `paused`, `unknown`, or
|
|
60
|
+
`conflict`; active work may include the live Lead's separate `runtime_state`.
|
|
61
|
+
`paused` means no matching Lead appeared in the successfully collected
|
|
62
|
+
observation. `unknown` means a matching candidate was observed but could not
|
|
63
|
+
currently be verified. Neither `unknown` nor `conflict` authorizes staff
|
|
64
|
+
actions. Verified checkout absence retires the assignment; unavailable or
|
|
65
|
+
ambiguous Git inventory preserves it. Work items do not expose assignment
|
|
66
|
+
session IDs, workspace IDs, or pane IDs.
|
|
64
67
|
|
|
65
68
|
For Manager, `open_workspaces` separately reports current Herdr topology. It is
|
|
66
69
|
not assignment ownership. An assigned report's branch is the handle for its
|
|
@@ -186,10 +189,13 @@ Manager only. Resume existing unresolved project work using its exact branch:
|
|
|
186
189
|
|
|
187
190
|
The assignment must already exist; resume does not create or replace it.
|
|
188
191
|
Resuming already-running work returns the current exact Lead instead of
|
|
189
|
-
starting another.
|
|
190
|
-
its
|
|
191
|
-
|
|
192
|
-
|
|
192
|
+
starting another. This recovers no stopped Lead and does not recover its Agents
|
|
193
|
+
or refresh its progress; use `message_staff` to communicate with an eligible
|
|
194
|
+
running Lead. `resume_work` is not a general progress-refresh mechanism. A
|
|
195
|
+
stopped Lead is relaunched with the same assignment while its worktree exists.
|
|
196
|
+
Verified checkout absence retires the assignment rather than recreating it. A
|
|
197
|
+
retired assignment cannot be resumed; new work may use `delegate_work` with the
|
|
198
|
+
remaining branch.
|
|
193
199
|
|
|
194
200
|
## `stop_lead`
|
|
195
201
|
|
|
@@ -143,13 +143,15 @@ control require the Lead's current exact project assignment. Direct-report
|
|
|
143
143
|
inspection and messaging use their own fresh supervision authorization;
|
|
144
144
|
focus/navigation alone grants neither. Chief-visible nested Leads remain
|
|
145
145
|
observational. A visible truncated Manager project-work branch can focus its
|
|
146
|
-
exact verified Lead only for a fresh, active row
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
stale projections, wholly hidden labels,
|
|
150
|
-
a uniquely verified live Herdr pane are
|
|
151
|
-
again when a click is handled; the status
|
|
152
|
-
authorization.
|
|
146
|
+
exact verified Lead only for a fresh, active row; only the rendered branch
|
|
147
|
+
segment is clickable, not its status suffix. A build mismatch remains visible
|
|
148
|
+
but does not by itself disable native Herdr focus. Paused or conflicted project
|
|
149
|
+
work, lost or unresolved sessions, stale projections, wholly hidden labels,
|
|
150
|
+
omitted entries, and targets without a uniquely verified live Herdr pane are
|
|
151
|
+
inert. Current placement is checked again when a click is handled; the status
|
|
152
|
+
projection itself is never authorization. Focus grants no cross-build
|
|
153
|
+
staff-operation authority; inspection, messaging, and control retain their
|
|
154
|
+
existing authorization checks.
|
|
153
155
|
|
|
154
156
|
Headless mode has no UI-only periodic supervision observation. Explicit and
|
|
155
157
|
model-context refreshes still acquire fresh state. A refresh failure never
|
|
@@ -34,8 +34,9 @@ Available to Leads and Managers.
|
|
|
34
34
|
`message_supervisor` is asynchronous and nonblocking. Use it for material
|
|
35
35
|
information the direct supervisor needs, such as a timely question,
|
|
36
36
|
clarification, blocker, warning, scope conflict, risk, decision request, or
|
|
37
|
-
important evidence. Continue
|
|
38
|
-
|
|
37
|
+
important evidence. Continue independently safe work while a reply is pending.
|
|
38
|
+
Defer only steps that genuinely require the response; when no actionable work
|
|
39
|
+
remains, end the turn and rely on normal message delivery rather than polling.
|
|
39
40
|
|
|
40
41
|
For an assigned project Lead, information that can wait for the normal automatic
|
|
41
42
|
completed-result handoff should go there instead. Do not message solely to
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-herdsman",
|
|
3
|
-
"version": "0.36.
|
|
3
|
+
"version": "0.36.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Asynchronous Pi subagents and agent fleet orchestration for parallel coding agents with nested delegation, background work, and supervision in herdr.",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -66,6 +66,7 @@
|
|
|
66
66
|
"smoke": "node scripts/smoke.mjs",
|
|
67
67
|
"format": "prettier . --write",
|
|
68
68
|
"format:check": "prettier . --check",
|
|
69
|
+
"lint": "oxlint",
|
|
69
70
|
"check": "node scripts/check.mjs",
|
|
70
71
|
"build": "node scripts/build.mjs",
|
|
71
72
|
"package:audit": "node scripts/package-audit.mjs",
|
|
@@ -87,6 +88,7 @@
|
|
|
87
88
|
"@howaboua/pi-codex-conversion": "4.0.4",
|
|
88
89
|
"@types/proper-lockfile": "4.1.4",
|
|
89
90
|
"esbuild": "^0.28.2",
|
|
91
|
+
"oxlint": "1.90.0",
|
|
90
92
|
"prettier": "3.9.10",
|
|
91
93
|
"typebox": "^1.3.7"
|
|
92
94
|
},
|