pi-herdsman 0.36.2 → 0.37.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/dist/index.js +8955 -7962
- package/dist/index.js.map +4 -4
- package/dist/peer-bridge.js +195 -194
- package/dist/peer-bridge.js.map +4 -4
- package/docs/adr/0005-use-files-for-explicit-evidence-handoffs.md +7 -2
- package/docs/adr/0028-reference-historical-assignment-evidence.md +14 -6
- package/docs/adr/0035-separate-assignment-handle-from-checked-out-branch.md +63 -0
- package/docs/concepts/coordination.md +25 -15
- package/docs/development/validation.md +8 -0
- package/docs/guides/handoffs.md +9 -8
- package/docs/guides/project-orchestration.md +41 -11
- package/docs/reference/agent.md +4 -3
- package/docs/reference/staff.md +33 -22
- package/docs/reference/status-widget.md +55 -12
- package/docs/reference/supervisor.md +3 -0
- package/package.json +5 -2
|
@@ -32,8 +32,13 @@ A single explicit evidence channel keeps handoffs inspectable and lets ordinary
|
|
|
32
32
|
|
|
33
33
|
## Consequences
|
|
34
34
|
|
|
35
|
-
|
|
36
|
-
|
|
35
|
+
Use `files` to explicitly hand off selected artifacts across ownership roots
|
|
36
|
+
or when a recipient otherwise needs an artifact that is not available through
|
|
37
|
+
its verified scope. Published Agent results are automatically readable through
|
|
38
|
+
`read_evidence` by the verified root controller and Agents in that exact
|
|
39
|
+
ownership tree; repeating those references in `files` is unnecessary. This
|
|
40
|
+
access does not transfer ownership: a cross-root recipient must receive the
|
|
41
|
+
specific result through an explicit `files` handoff.
|
|
37
42
|
|
|
38
43
|
Result references remain valid evidence selectors within that channel.
|
|
39
44
|
|
|
@@ -18,17 +18,25 @@ ownership.
|
|
|
18
18
|
Retained text snapshots have stable `evidence:<name>#<index>` references,
|
|
19
19
|
allocated uniquely within the Herdsman data root. Agent results retain their
|
|
20
20
|
existing `result:<agent>#<index>` references. References identify immutable
|
|
21
|
-
evidence but do not authorize access
|
|
22
|
-
by the requesting assignment. A scoped, read-only
|
|
23
|
-
provides bounded access to authorized references
|
|
24
|
-
|
|
21
|
+
evidence but do not authorize access. Retained assignment evidence retrieval is
|
|
22
|
+
limited to evidence accepted by the requesting assignment. A scoped, read-only
|
|
23
|
+
`read_evidence` operation provides bounded access to authorized references;
|
|
24
|
+
completed results also follow the same-root registration exception below.
|
|
25
|
+
Internal storage paths and UUIDs are not model-facing identities.
|
|
26
|
+
|
|
27
|
+
Separately, a completed result is readable when it is either explicitly
|
|
28
|
+
accepted or registered as published within the requester's exact verified
|
|
29
|
+
ownership root. Registered same-root results are readable without being
|
|
30
|
+
selected through `files`; selected `files` handoffs remain the explicit path
|
|
31
|
+
for cross-root or other transferred artifacts. This ownership-tree access
|
|
32
|
+
does not expand the accepted required-evidence set or grant project authority.
|
|
25
33
|
|
|
26
34
|
This decision supersedes ADR 0025 only where it specifies embedding small
|
|
27
35
|
historical required evidence by default. Its decisions about evidence
|
|
28
36
|
ownership, retention, assignment scope, and inheritance remain in force, as
|
|
29
37
|
modified by ADR 0026. ADR 0001's semantic result identity, ADR 0005's explicit
|
|
30
|
-
`files` handoffs, and ADR 0027's complete-text
|
|
31
|
-
unchanged.
|
|
38
|
+
`files` handoffs for cross-tree transfers, and ADR 0027's complete-text
|
|
39
|
+
coordination messages remain unchanged.
|
|
32
40
|
|
|
33
41
|
## Rationale
|
|
34
42
|
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Separate assignment handles from checked-out branches
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted
|
|
6
|
+
|
|
7
|
+
## Context
|
|
8
|
+
|
|
9
|
+
Managed project work has a branch-scoped public selector, an exact Pi session,
|
|
10
|
+
and a physical Git checkout. Treating the branch currently checked out in that
|
|
11
|
+
worktree as all three identities makes an ordinary branch switch look like a
|
|
12
|
+
different or missing assignment. It can also confuse the source selected for
|
|
13
|
+
integration with the assignment used to address the Lead.
|
|
14
|
+
|
|
15
|
+
This decision refines the branch-scoped assignment semantics in
|
|
16
|
+
[ADR 0017](0017-use-project-assignments-for-managed-lead-authority.md) and
|
|
17
|
+
[ADR 0029](0029-use-immutable-managed-lead-session-identity.md). It does not
|
|
18
|
+
replace exact-session authority or the retirement boundary in
|
|
19
|
+
[ADR 0019](0019-retire-project-assignments-when-worktrees-are-absent.md).
|
|
20
|
+
|
|
21
|
+
## Decision
|
|
22
|
+
|
|
23
|
+
Keep these facts distinct:
|
|
24
|
+
|
|
25
|
+
1. **Assignment handle:** the repository plus the original assignment branch
|
|
26
|
+
is the durable, branch-scoped selector used by Manager project operations.
|
|
27
|
+
It remains unchanged when the Lead checks out another branch.
|
|
28
|
+
2. **Managed session:** authority remains bound to the exact assigned Pi
|
|
29
|
+
session and its immutable managed-session identity. A matching branch name
|
|
30
|
+
does not authorize another session.
|
|
31
|
+
3. **Physical checkout:** the assignment's linked worktree is established
|
|
32
|
+
independently from verified checkout provenance and current Git/Herdr
|
|
33
|
+
observations. A branch name, directory label, or repository match alone is
|
|
34
|
+
not proof that a session occupies the assigned checkout.
|
|
35
|
+
4. **Checked-out branch:** the named branch currently at that verified
|
|
36
|
+
checkout's `HEAD` is mutable observed Git state, not assignment identity.
|
|
37
|
+
A branch switch, rename, or deletion does not by itself transfer authority
|
|
38
|
+
or retire the assignment. Missing or contradictory placement evidence
|
|
39
|
+
remains unknown or conflicting and fails closed.
|
|
40
|
+
5. **Branch-sensitive operations:** operation targets continue to use the
|
|
41
|
+
assignment handle, but integration acts on the actual named source branch
|
|
42
|
+
at the verified checkout and validates the accepted source SHA. Detached
|
|
43
|
+
or changed source state cannot be silently substituted. Removal remains
|
|
44
|
+
authorized against the exact assigned checkout and existing approval,
|
|
45
|
+
cleanliness, occupancy, and Herdr safeguards; it is not permission to
|
|
46
|
+
remove whichever checkout happens to use the assignment branch name.
|
|
47
|
+
6. **Retirement:** retire the exact assignment only after successful removal
|
|
48
|
+
of its checkout or authoritative verification that the checkout is absent.
|
|
49
|
+
A changed checked-out branch is not evidence of absence; failed, partial,
|
|
50
|
+
or ambiguous inventory preserves the assignment.
|
|
51
|
+
|
|
52
|
+
Resume reuses the existing verified checkout and exact Pi session without
|
|
53
|
+
switching its Git branch, replacing the session, or re-keying the assignment.
|
|
54
|
+
|
|
55
|
+
## Consequences
|
|
56
|
+
|
|
57
|
+
- Branch-scoped Manager selectors remain stable across branch changes.
|
|
58
|
+
- Exact session and physical checkout evidence remain independent authority
|
|
59
|
+
checks; uncertainty does not grant actionability.
|
|
60
|
+
- Integration and removal remain branch-sensitive where their effects require
|
|
61
|
+
it, while assignment lookup remains stable.
|
|
62
|
+
- Assignment retirement continues to follow ADR 0019's verified-absence
|
|
63
|
+
boundary; no completion or acceptance is inferred from retirement.
|
|
@@ -133,16 +133,21 @@ Workspace membership is physical placement, not assignment ownership. Multiple
|
|
|
133
133
|
Leads can share a workspace, and a branch can have a worktree without implying
|
|
134
134
|
that every session in that workspace owns its work.
|
|
135
135
|
|
|
136
|
-
## Work assignments
|
|
136
|
+
## Work assignments use a branch-scoped handle
|
|
137
137
|
|
|
138
138
|
A **work assignment** is one durable, branch-scoped objective assigned to an
|
|
139
|
-
exact managed Lead.
|
|
140
|
-
branch. An **Agent assignment** is bounded work
|
|
141
|
-
owner-managed Agent; it is separate from a work
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
139
|
+
exact managed Lead. Its immutable public handle is repository identity plus
|
|
140
|
+
the original semantic Git branch. An **Agent assignment** is bounded work
|
|
141
|
+
delegated to an exact owner-managed Agent; it is separate from a work
|
|
142
|
+
assignment.
|
|
143
|
+
|
|
144
|
+
Within one repository, the original branch is the public assignment selector.
|
|
145
|
+
The exact Pi session ID is the immutable managed executor identity. The
|
|
146
|
+
assignment's linked checkout is verified independently from session and
|
|
147
|
+
Herdr/Git evidence; the branch currently checked out there is mutable Git state,
|
|
148
|
+
not the assignment handle. A branch-name match alone proves neither session
|
|
149
|
+
identity nor physical checkout placement. A Lead may switch branches in its
|
|
150
|
+
verified checkout without changing which assignment the Manager selects.
|
|
146
151
|
|
|
147
152
|
Because durable work is not keyed by a Manager or primary workspace identity, a
|
|
148
153
|
replacement Manager or replacement primary workspace for the same repository
|
|
@@ -151,8 +156,9 @@ again when the work is observed or resumed.
|
|
|
151
156
|
|
|
152
157
|
```text
|
|
153
158
|
project work
|
|
154
|
-
├─
|
|
155
|
-
└─
|
|
159
|
+
├─ assignment handle feat/a → exact Lead/session → verified checkout
|
|
160
|
+
│ └─ currently checked out: feat/a or feat/c
|
|
161
|
+
└─ assignment handle feat/b → exact Lead/session → verified checkout
|
|
156
162
|
```
|
|
157
163
|
|
|
158
164
|
The assignment is the durable indicator that project work remains open. It
|
|
@@ -173,11 +179,15 @@ ownership without asserting completion or acceptance. See
|
|
|
173
179
|
[Project orchestration](../guides/project-orchestration.md) for the workflow.
|
|
174
180
|
|
|
175
181
|
`stop_lead` pauses assigned execution while preserving the assignment, Pi
|
|
176
|
-
session,
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
182
|
+
session, checkout, and its current Git state; `resume_work` resumes the exact
|
|
183
|
+
session in the existing verified checkout without switching branches. These
|
|
184
|
+
operations do not change project authority. Integration selects work by its
|
|
185
|
+
assignment handle but validates and integrates the actual named branch and
|
|
186
|
+
accepted SHA at the assigned checkout. Removal targets that exact checkout
|
|
187
|
+
under the existing authorization and safety checks. Successful Herdr worktree
|
|
188
|
+
removal or verified checkout absence retires the matching assignment and any
|
|
189
|
+
still-pending project messages while preserving the Git branch. A changed
|
|
190
|
+
checked-out branch is not checkout absence. Manually continuing the
|
|
181
191
|
exact assigned Pi session remains managed; `managed-lead` is launch policy,
|
|
182
192
|
not authority.
|
|
183
193
|
A complete Git worktree inventory that verifies the checkout is absent retires
|
|
@@ -118,6 +118,14 @@ npm run check
|
|
|
118
118
|
`npm run check` remains the bounded full check, including platform-appropriate
|
|
119
119
|
process-tree cleanup when the test runner times out or leaks descendants.
|
|
120
120
|
|
|
121
|
+
## Node compatibility target
|
|
122
|
+
|
|
123
|
+
`package.json` `engines.node` defines the minimum supported Node.js version.
|
|
124
|
+
Compatibility CI jobs and esbuild derive their targets from it; `@types/node`
|
|
125
|
+
must use the same major version. The Unix and Windows installers check the
|
|
126
|
+
published package requirement. Release/Preview tooling and the Docker image
|
|
127
|
+
may deliberately use newer Node versions.
|
|
128
|
+
|
|
121
129
|
## Dependency availability
|
|
122
130
|
|
|
123
131
|
A fresh worktree may not contain `node_modules`.
|
package/docs/guides/handoffs.md
CHANGED
|
@@ -396,14 +396,15 @@ through `files` using the exact refs shown by the completions:
|
|
|
396
396
|
```
|
|
397
397
|
|
|
398
398
|
`result:<agent>#<index>` is a globally unique reusable direct-result ref within
|
|
399
|
-
the Herdsman durable data root.
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
399
|
+
the Herdsman durable data root. A completed result published by an Agent is
|
|
400
|
+
available through `read_evidence` to that Agent's verified root controller and
|
|
401
|
+
Agents in the same ownership tree, even after the producer's mailbox is
|
|
402
|
+
cleaned up. This grants read access only; it does not create an attachment or
|
|
403
|
+
make task/report text a binding. Other roots, including supervisors of a
|
|
404
|
+
different Lead, need an explicit `files` transfer. Indexes are allocated
|
|
405
|
+
globally and are never reused. Semantic refs retain their model-facing
|
|
406
|
+
identity while Herdsman resolves the artifact through a hidden canonical
|
|
407
|
+
binding.
|
|
407
408
|
|
|
408
409
|
Pass an exact canonical reference through `files` when it was supplied as file
|
|
409
410
|
evidence, especially for a transitive handoff:
|
|
@@ -61,14 +61,33 @@ Ask Manager for a bounded objective:
|
|
|
61
61
|
Implement the API change on branch feat/api-change.
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
-
Manager delegates the work to a Lead. The Git branch is the durable
|
|
65
|
-
|
|
66
|
-
|
|
64
|
+
Manager delegates the work to a Lead. The original Git branch is the durable
|
|
65
|
+
assignment handle used to select the work; the exact Pi session is its
|
|
66
|
+
executor, and its physical linked checkout is verified independently. The
|
|
67
|
+
branch currently checked out there is mutable Git state and may differ from
|
|
68
|
+
the assignment handle. Internal assignment IDs are not project-work handles.
|
|
69
|
+
A branch is optional when starting new work. If omitted,
|
|
67
70
|
Pi Herdsman can generate one. The first delegation can create the first linked
|
|
68
71
|
worktree, and an unoccupied existing worktree for the branch is reused.
|
|
69
72
|
|
|
73
|
+
Manager's optional worktree statistics compare tracked working-tree contents
|
|
74
|
+
with the assignment's stable Git baseline, including committed, staged, and
|
|
75
|
+
unstaged changes without double-counting. Untracked files are excluded from
|
|
76
|
+
numeric totals but make the row dirty (`*`); binary-only changes can appear as
|
|
77
|
+
a changed-file count such as `2f`, and `±0` means no net tracked differences.
|
|
78
|
+
Baselines captured for new assignments stay fixed when Manager's `main`
|
|
79
|
+
advances, although merging upstream changes into a Lead checkout can contribute
|
|
80
|
+
to its net diff. Older assignments without a stored baseline use an approximate
|
|
81
|
+
merge-base estimate shown with `~`; it is not saved. If the Lead checks out a
|
|
82
|
+
different branch, `↪ branch` shows the actual branch while the original
|
|
83
|
+
assignment handle remains the row's focus target. These are advisory net
|
|
84
|
+
worktree measurements, not cumulative Lead-authored effort or proof of
|
|
85
|
+
integration readiness.
|
|
86
|
+
|
|
70
87
|
Start new work with `delegate_work`. Resume existing work with
|
|
71
|
-
`resume_work` using its
|
|
88
|
+
`resume_work` using its original assignment branch handle; resume reuses the
|
|
89
|
+
existing verified checkout and exact Pi session without switching its current
|
|
90
|
+
branch. A verified Git inventory showing the
|
|
72
91
|
assignment's worktree checkout is absent retires that assignment and its
|
|
73
92
|
pending project messages; failed or ambiguous inventory preserves it. A retired
|
|
74
93
|
assignment cannot be resumed, but a new delegation may start managed work from
|
|
@@ -141,9 +160,12 @@ does not necessarily require implementing them sequentially.
|
|
|
141
160
|
|
|
142
161
|
## Integrate completed branches
|
|
143
162
|
|
|
144
|
-
When an assigned Lead has completed and validated its
|
|
145
|
-
accept
|
|
146
|
-
|
|
163
|
+
When an assigned Lead has completed and validated its work, the Manager can
|
|
164
|
+
accept the exact commit on the named branch currently checked out in its
|
|
165
|
+
verified checkout and use the Manager-only `integrate_branch` staff tool to
|
|
166
|
+
fast-forward the verified primary branch. The assignment branch remains the
|
|
167
|
+
selector; the actual source branch may differ and must still point to the
|
|
168
|
+
accepted SHA. This is local Git
|
|
147
169
|
integration; it does not fetch, push, or merge a hosted pull request. The source
|
|
148
170
|
and target must be clean, and a branch that does not contain the current target
|
|
149
171
|
is returned as `needs_update`. That result is not proof of a content conflict.
|
|
@@ -154,7 +176,7 @@ the exact validated new source HEAD. Then accept that revision before retrying.
|
|
|
154
176
|
Independent feature branches may be integrated one at a time; a later branch
|
|
155
177
|
may need to incorporate earlier integration first. The Git branch is preserved.
|
|
156
178
|
After verified integration, the operation attempts guarded removal of the
|
|
157
|
-
exact
|
|
179
|
+
exact assigned checkout and retirement of its assignment. `cleanup_pending`
|
|
158
180
|
means integration is verified but at least one cleanup fact is not; retry
|
|
159
181
|
with the same accepted SHA while permission remains enabled to retry the
|
|
160
182
|
guarded cleanup. If the checkout is already absent, reconciliation requires
|
|
@@ -203,6 +225,12 @@ reported as unresolved unless a later Lead execution completes successfully.
|
|
|
203
225
|
Cancellation is reported separately as a factual, nonterminal message without
|
|
204
226
|
partial assistant output.
|
|
205
227
|
|
|
228
|
+
Manager-bound Lead messages are labeled by source: explicit `message_supervisor`
|
|
229
|
+
messages, completed direct responses, settled herd runs, execution failures, and
|
|
230
|
+
cancellations have distinct headings. These labels describe the message only;
|
|
231
|
+
they do not imply assignment acceptance, review readiness, integration, or
|
|
232
|
+
retirement.
|
|
233
|
+
|
|
206
234
|
An assigned Lead reports an execution failure to its Manager through the
|
|
207
235
|
durable project-message path. If the Manager is absent, the report remains
|
|
208
236
|
pending; when the exact current Manager returns idle, an unreceived failure
|
|
@@ -230,9 +258,11 @@ evidence only when it materially matters.
|
|
|
230
258
|
|
|
231
259
|
## Pause and resume
|
|
232
260
|
|
|
233
|
-
`stop_lead` selects the assigned Lead by
|
|
234
|
-
|
|
235
|
-
|
|
261
|
+
`stop_lead` selects the assigned Lead by its original branch handle and stops
|
|
262
|
+
its owned Agent execution tree while preserving the assignment, Pi session,
|
|
263
|
+
verified checkout, and current Git state. Resume the same work with
|
|
264
|
+
`resume_work` using that assignment handle. `stop_lead` does not resolve
|
|
265
|
+
project work.
|
|
236
266
|
|
|
237
267
|
See [`stop_lead`](../reference/staff.md#stop_lead) and
|
|
238
268
|
[`resume_work`](../reference/staff.md#resume_work).
|
package/docs/reference/agent.md
CHANGED
|
@@ -395,9 +395,10 @@ observation path. Transcript is read-only and does not change agent state.
|
|
|
395
395
|
}
|
|
396
396
|
```
|
|
397
397
|
|
|
398
|
-
`read_evidence` is available to managed Agents and
|
|
399
|
-
|
|
400
|
-
|
|
398
|
+
`read_evidence` is available to managed Agents and root controllers. It reads
|
|
399
|
+
exact accepted assignment evidence and completed results published to the
|
|
400
|
+
requester's verified ownership tree; a reference itself grants no
|
|
401
|
+
authorization. Cross-tree results require an explicit `files` transfer. `ref` is required. `offset` is
|
|
401
402
|
an optional 1-based line number (default `1`), `limit` is an optional positive
|
|
402
403
|
line count (default `200`, maximum `200`), and `byteOffset` is an optional
|
|
403
404
|
non-negative byte offset within the selected line (default `0`), for resuming a
|
package/docs/reference/staff.md
CHANGED
|
@@ -11,12 +11,14 @@ the branch-based project operations `delegate_work`, `resume_work`,
|
|
|
11
11
|
`stop_lead`, `remove_worktree`, and `integrate_branch`. Chief has no
|
|
12
12
|
project-operation tools.
|
|
13
13
|
|
|
14
|
-
Managers select assigned Leads by `branch`; ordinary
|
|
15
|
-
Chief's actionable direct reports use the stable `target`
|
|
16
|
-
current supervision context or `list_staff`. Project actions
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
authority.
|
|
14
|
+
Managers select assigned Leads by the original assignment `branch`; ordinary
|
|
15
|
+
supervised Leads and Chief's actionable direct reports use the stable `target`
|
|
16
|
+
discovered in the current supervision context or `list_staff`. Project actions
|
|
17
|
+
use the Git branch handle. Exact session and verified physical checkout are
|
|
18
|
+
established independently; the checked-out branch may differ and is observed
|
|
19
|
+
Git state, not an alternate selector or authority. A target resolves to an
|
|
20
|
+
exact coordinator identity, but is not authorization: every action revalidates
|
|
21
|
+
current identity and direct-report authority.
|
|
20
22
|
|
|
21
23
|
Target bindings are scoped to the caller's current Pi-session history. If a
|
|
22
24
|
target cannot be resolved in the current history, the operation rejects it;
|
|
@@ -55,9 +57,11 @@ evidence. Use `list_staff` when a fresh complete roster is materially needed.
|
|
|
55
57
|
```
|
|
56
58
|
|
|
57
59
|
Returns a fresh direct-report projection and fresh `available_tools`. For
|
|
58
|
-
Manager, `work` lists durable project assignments by
|
|
59
|
-
and a bounded task summary. Status is `active`,
|
|
60
|
-
`conflict`; active work may include the live Lead's
|
|
60
|
+
Manager, `work` lists durable project assignments by their original branch
|
|
61
|
+
handle with derived status and a bounded task summary. Status is `active`,
|
|
62
|
+
`paused`, `unknown`, or `conflict`; active work may include the live Lead's
|
|
63
|
+
separate `runtime_state`. When exposed, the checked-out branch is observed
|
|
64
|
+
state, not the assignment selector.
|
|
61
65
|
`paused` means no matching Lead appeared in the successfully collected
|
|
62
66
|
observation. `unknown` means a matching candidate was observed but could not
|
|
63
67
|
currently be verified. Neither `unknown` nor `conflict` authorizes staff
|
|
@@ -181,7 +185,8 @@ decision for that run; this does not modify Pi's persistent trust store.
|
|
|
181
185
|
|
|
182
186
|
## `resume_work`
|
|
183
187
|
|
|
184
|
-
Manager only. Resume existing unresolved project work using its
|
|
188
|
+
Manager only. Resume existing unresolved project work using its original
|
|
189
|
+
assignment branch handle:
|
|
185
190
|
|
|
186
191
|
```json
|
|
187
192
|
{ "branch": "feat/example" }
|
|
@@ -192,7 +197,9 @@ Resuming already-running work returns the current exact Lead instead of
|
|
|
192
197
|
starting another. This recovers no stopped Lead and does not recover its Agents
|
|
193
198
|
or refresh its progress; use `message_staff` to communicate with an eligible
|
|
194
199
|
running Lead. `resume_work` is not a general progress-refresh mechanism. A
|
|
195
|
-
stopped Lead is relaunched with the same
|
|
200
|
+
stopped Lead is relaunched with the same exact session in its existing verified
|
|
201
|
+
checkout while that checkout exists; its current branch is not reset to the
|
|
202
|
+
assignment handle.
|
|
196
203
|
Verified checkout absence retires the assignment rather than recreating it. A
|
|
197
204
|
retired assignment cannot be resumed; new work may use `delegate_work` with the
|
|
198
205
|
remaining branch.
|
|
@@ -204,8 +211,8 @@ remaining branch.
|
|
|
204
211
|
```
|
|
205
212
|
|
|
206
213
|
Stops only an exact currently assigned project Lead and its owned Agent
|
|
207
|
-
execution tree. The assignment, Pi session,
|
|
208
|
-
preserved. Resume the work with
|
|
214
|
+
execution tree. The assignment, Pi session, linked checkout, and its current
|
|
215
|
+
Git state are preserved. Resume the work with
|
|
209
216
|
`resume_work` using its branch. An unassigned Lead is not a Manager staff-stop
|
|
210
217
|
target. Failed or ambiguous cleanup does not retire an assignment. Successful
|
|
211
218
|
Herdr worktree removal or verified checkout absence retires the assignment and
|
|
@@ -216,8 +223,8 @@ exact-owner recovery remains independently authorized.
|
|
|
216
223
|
|
|
217
224
|
## `remove_worktree`
|
|
218
225
|
|
|
219
|
-
Manager only. Remove
|
|
220
|
-
|
|
226
|
+
Manager only. Remove the exact verified linked checkout of an explicitly
|
|
227
|
+
requested assignment, or register an actionable approval request:
|
|
221
228
|
|
|
222
229
|
```json
|
|
223
230
|
{ "branch": "feat/example" }
|
|
@@ -249,10 +256,12 @@ not automatically restarted. A closed Herdr workspace may be reopened to
|
|
|
249
256
|
address its verified checkout. Herdr remains responsible for removing the
|
|
250
257
|
worktree.
|
|
251
258
|
|
|
252
|
-
The confirmation identifies the
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
259
|
+
The confirmation identifies the assignment handle and exact project checkout,
|
|
260
|
+
including its current checked-out branch when different. The assignment
|
|
261
|
+
branch is not proof that a checkout currently has that branch checked out. It
|
|
262
|
+
explains that managed execution may be stopped, and says the Git branch and Pi
|
|
263
|
+
conversation remain while the assignment will be retired only after verified
|
|
264
|
+
checkout removal. Type the exact word `remove`; cancellation or any other response has
|
|
256
265
|
no destructive effect. Successful checkout removal is followed by
|
|
257
266
|
the existing assignment reconciliation, which retires the matching assignment
|
|
258
267
|
and pending project messages when authoritative checkout absence is verified.
|
|
@@ -265,7 +274,8 @@ deletes the Git branch or Pi conversation.
|
|
|
265
274
|
|
|
266
275
|
## `integrate_branch`
|
|
267
276
|
|
|
268
|
-
Manager only.
|
|
277
|
+
Manager only. Use the assignment branch to select work, then integrate the
|
|
278
|
+
actual named source branch at its verified checkout into the verified primary
|
|
269
279
|
branch using fast-forward-only Git:
|
|
270
280
|
|
|
271
281
|
```json
|
|
@@ -273,8 +283,9 @@ branch using fast-forward-only Git:
|
|
|
273
283
|
```
|
|
274
284
|
|
|
275
285
|
`expected_head` is the exact source revision the Manager accepted after
|
|
276
|
-
validation; the source branch must still point to it
|
|
277
|
-
separately controlled by the Manager
|
|
286
|
+
validation; the actual source branch must still point to it and may differ from
|
|
287
|
+
the assignment handle. This operation is separately controlled by the Manager
|
|
288
|
+
local-merge policy (see
|
|
278
289
|
[Configuration](configuration.md#manager-local-merge)). It does not fetch,
|
|
279
290
|
push, create a merge commit, or delete the Git branch. Divergence returns
|
|
280
291
|
`needs_update` with the observed target revision; this means the source branch
|
|
@@ -63,8 +63,8 @@ a confidently identified mismatch.
|
|
|
63
63
|
|
|
64
64
|
```text
|
|
65
65
|
● manager · pi-herdsman
|
|
66
|
-
├─ ● feat/example
|
|
67
|
-
└─
|
|
66
|
+
├─ ● feat/example
|
|
67
|
+
└─ ◫ fix/other
|
|
68
68
|
```
|
|
69
69
|
|
|
70
70
|
When available, managed work rows can append the Lead's active herd-run elapsed
|
|
@@ -72,8 +72,8 @@ time and Pi's current context percentage:
|
|
|
72
72
|
|
|
73
73
|
```text
|
|
74
74
|
● manager · pi-herdsman
|
|
75
|
-
├─ ● feat/foo
|
|
76
|
-
└─
|
|
75
|
+
├─ ● feat/foo 14m 61%
|
|
76
|
+
└─ ◫ fix/other
|
|
77
77
|
```
|
|
78
78
|
|
|
79
79
|
Elapsed time is the same active herd-run interval shown by the ordinary Lead
|
|
@@ -84,20 +84,63 @@ the live Lead's runtime state. Chief rows receive matching theme styling but do
|
|
|
84
84
|
not show these telemetry columns. A stale Manager snapshot suppresses elapsed
|
|
85
85
|
telemetry while retaining other available metadata such as context percentage.
|
|
86
86
|
|
|
87
|
-
Manager work
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
verified build incompatibility
|
|
93
|
-
|
|
94
|
-
|
|
87
|
+
Routine Manager work is symbol-only: active work uses the verified Lead's
|
|
88
|
+
lifecycle marker, or muted `·` when no verified Lead is present; paused work
|
|
89
|
+
uses muted `◫`, distinct from an idle/done Lead's `○`. Exceptional states keep
|
|
90
|
+
their complete labels: blocked, unknown, and lost describe the verified Lead's
|
|
91
|
+
runtime state; project unknown and conflict use `?` and warning-colored `!`;
|
|
92
|
+
independently verified build incompatibility uses `!` and `build mismatch`.
|
|
93
|
+
These concise labels are presentation only and do not change work status or
|
|
94
|
+
focus eligibility. Ordinary supervised Lead rows retain `· Lead`, which
|
|
95
|
+
identifies their relationship rather than repeating lifecycle state.
|
|
96
|
+
|
|
97
|
+
Chief direct and nested Leads likewise use one marker before the identity;
|
|
98
|
+
only blocked, unknown, lost, and incompatible-build rows add explanatory text.
|
|
99
|
+
The ordinary Lead Agent widget retains a single animated/static lifecycle
|
|
100
|
+
marker. It adds aligned text only for blocked, unknown, and lost Agents, while
|
|
101
|
+
its ambient header summarizes nonzero working, blocked, transitioning,
|
|
102
|
+
unknown, and lost categories as `● N ◐ N ◌ N ? N × N` (starting and settling share
|
|
103
|
+
`◌`). If no Agent needs an attention label, the state-text column disappears;
|
|
104
|
+
when attention is present, routine rows keep its blank alignment. Running
|
|
105
|
+
menus and consequential confirmations continue to use full descriptive
|
|
106
|
+
lifecycle labels and counts.
|
|
95
107
|
Ordinary Leads supervised by the Manager are shown separately from project
|
|
96
108
|
work, with a supervised label; they are not treated as managed work. A Manager
|
|
97
109
|
can inspect an eligible direct report through the overview, independently of
|
|
98
110
|
mouse focus/navigation. Branches are display handles; exact session identity is
|
|
99
111
|
revalidated for control actions.
|
|
100
112
|
|
|
113
|
+
### Manager Git indicators
|
|
114
|
+
|
|
115
|
+
Eligible Manager work rows can show net tracked textual additions and
|
|
116
|
+
deletions from a stable assignment baseline to the current worktree contents.
|
|
117
|
+
The comparison includes committed, staged, and unstaged tracked changes without
|
|
118
|
+
double-counting them; untracked files do not contribute numeric totals. `*`
|
|
119
|
+
means the assigned checkout is dirty, including untracked changes. Thus `±0*`
|
|
120
|
+
means the verified comparison found no net tracked differences but the checkout
|
|
121
|
+
is dirty; `±0` means it found no net tracked differences and the checkout is
|
|
122
|
+
clean. A changed-file count such as `2f` is used when files changed without
|
|
123
|
+
textual line counts, such as binary-only changes. These are net worktree
|
|
124
|
+
contents, not cumulative effort or proof of merge readiness; merging upstream
|
|
125
|
+
changes into a Lead checkout can contribute to its net diff.
|
|
126
|
+
|
|
127
|
+
The stored baseline remains fixed when the Manager's `main` advances. Existing
|
|
128
|
+
assignments without a stored baseline use a dynamically inferred merge-base
|
|
129
|
+
approximation, marked with `~` before numeric statistics. That fallback is not
|
|
130
|
+
persisted. If a Lead switches branches in its assigned worktree, `↪` followed
|
|
131
|
+
by the checked-out branch distinguishes that mutable Git branch from the
|
|
132
|
+
original assignment branch shown as the row's clickable handle. Branch-switch
|
|
133
|
+
metadata and Git suffixes are not clickable; the assignment handle continues to
|
|
134
|
+
target the same exact managed Lead.
|
|
135
|
+
|
|
136
|
+
No Git suffix means the optional observation is unavailable or has not yet
|
|
137
|
+
been sampled; it does not mean the checkout is clean. Sampling is best-effort,
|
|
138
|
+
with a minimum interval of about 30 seconds between attempts. Under width
|
|
139
|
+
pressure, optional Git details may be omitted. The branch remains the
|
|
140
|
+
navigation target; its suffix is not clickable. Git indicators are advisory
|
|
141
|
+
display values only and do not establish project status, authority, or
|
|
142
|
+
integration readiness.
|
|
143
|
+
|
|
101
144
|
## Installation
|
|
102
145
|
|
|
103
146
|
The widget is installed only when the current session has a valid supported
|
|
@@ -37,6 +37,9 @@ clarification, blocker, warning, scope conflict, risk, decision request, or
|
|
|
37
37
|
important evidence. Continue independently safe work while a reply is pending.
|
|
38
38
|
Defer only steps that genuinely require the response; when no actionable work
|
|
39
39
|
remains, end the turn and rely on normal message delivery rather than polling.
|
|
40
|
+
For an assigned project Lead, this explicit message is labeled separately from
|
|
41
|
+
the automatic completed-result or settled-herd handoff; the label does not
|
|
42
|
+
change assignment lifecycle or review state.
|
|
40
43
|
|
|
41
44
|
For an assigned project Lead, information that can wait for the normal automatic
|
|
42
45
|
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.
|
|
3
|
+
"version": "0.37.0",
|
|
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",
|
|
@@ -69,6 +69,7 @@
|
|
|
69
69
|
"lint": "oxlint",
|
|
70
70
|
"check": "node scripts/check.mjs",
|
|
71
71
|
"build": "node scripts/build.mjs",
|
|
72
|
+
"typecheck": "tsc --project tsconfig.json",
|
|
72
73
|
"package:audit": "node scripts/package-audit.mjs",
|
|
73
74
|
"validate": "npm run format:check && npm run check && npm run build && npm run package:audit",
|
|
74
75
|
"release:check": "npm run validate && npm publish --dry-run --ignore-scripts",
|
|
@@ -86,11 +87,13 @@
|
|
|
86
87
|
"@earendil-works/pi-coding-agent": "1.4.0",
|
|
87
88
|
"@earendil-works/pi-tui": "1.4.0",
|
|
88
89
|
"@howaboua/pi-codex-conversion": "4.0.4",
|
|
90
|
+
"@types/node": "22.19.19",
|
|
89
91
|
"@types/proper-lockfile": "4.1.4",
|
|
90
92
|
"esbuild": "^0.28.2",
|
|
91
93
|
"oxlint": "1.90.0",
|
|
92
94
|
"prettier": "3.9.10",
|
|
93
|
-
"typebox": "^1.3.7"
|
|
95
|
+
"typebox": "^1.3.7",
|
|
96
|
+
"typescript": "7.0.2"
|
|
94
97
|
},
|
|
95
98
|
"engines": {
|
|
96
99
|
"node": ">=22.19.0"
|