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.
@@ -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 to exchange technical information, prefer having
14
- them coordinate directly when eligible; mediate when project-level decisions
15
- or unavailable peer communication require it.
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.
@@ -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. A Lead may choose to wait for a response through `message_staff`.
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, simulated
194
- smoke, peer federation, and Windows bootstrap acceptance independently.
195
- Federation acceptance exercises the actual containerized Pi/Herdr integration
196
- in separate Manager and ordinary Lead phases. Unknown changes select
197
- conservative checks. A skipped conditional job is valid only when the
198
- classifier says it is not required; the aggregate `CI` check fails closed for
199
- missing or unsuccessful required jobs. Local `npm run validate` remains
200
- unchanged and does not replace hosted integration acceptance.
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; the Lead may choose to wait
171
- for a response through `message_staff`. A later automatic result may repeat
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
@@ -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:
@@ -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`, or `conflict`; active
60
- work may include the live Lead's separate `runtime_state`. Paused work remains
61
- listed without a running Lead. Verified checkout absence retires the assignment;
62
- unavailable or ambiguous Git inventory preserves it. Work items do not expose
63
- assignment session IDs, workspace IDs, or pane IDs.
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. A stopped Lead is relaunched with the same assignment while
190
- its worktree exists. Verified checkout absence retires the assignment rather
191
- than recreating it. A retired assignment cannot be resumed; new work may use
192
- `delegate_work` with the remaining branch.
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 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.
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 working as appropriate; the Lead may also choose
38
- to wait for a response through ordinary `message_staff`.
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.0",
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
  },