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.
@@ -32,8 +32,13 @@ A single explicit evidence channel keeps handoffs inspectable and lets ordinary
32
32
 
33
33
  ## Consequences
34
34
 
35
- When the recipient's work or decision depends on relevant artifacts, senders
36
- must pass them explicitly through `files`.
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; retrieval is limited to evidence accepted
22
- by the requesting assignment. A scoped, read-only `read_evidence` operation
23
- provides bounded access to authorized references. Internal storage paths and
24
- UUIDs are not model-facing identities.
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 coordination messages remain
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 belong to a branch
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. 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.
142
-
143
- Within one repository, the branch is the public work handle. A Lead is the
144
- current executor. The assignment's exact Pi session ID is an internal executor
145
- identity; exact session IDs are used only when acting on a live Lead.
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
- ├─ branch feat/a → current Lead → Agent tree
155
- └─ branch feat/b → current Lead → Agent tree
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, branch, and worktree; `resume_work` resumes the existing
177
- assignment while its checkout exists. These operations do not change project
178
- authority. Successful Herdr worktree removal or verified checkout absence
179
- retires the matching assignment and any still-pending project messages while
180
- preserving the Git branch. Manually continuing the
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`.
@@ -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. It resolves in another session only when
400
- explicitly handed through `files`; resolution is against matching completion
401
- entries or imported bindings on the caller's current Pi branch. Indexes are
402
- allocated globally and are never reused, while availability remains
403
- branch-local. Semantic result refs retain their model-facing identity during
404
- attachment preparation. Herdsman resolves the durable artifact through a
405
- hidden canonical binding and carries that binding across Pi session boundaries
406
- so the receiving session can forward the same semantic ref later.
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 semantic
65
- work handle; the Lead is the current executor. Internal assignment IDs are not
66
- project-work handles. A branch is optional when starting new work. If omitted,
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 branch. A verified Git inventory showing the
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 branch, the Manager can
145
- accept its exact source commit and use the Manager-only `integrate_branch` staff
146
- tool to fast-forward the verified primary branch. This is local Git
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 source checkout and retirement of its assignment. `cleanup_pending`
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 branch and stops its owned Agent execution tree while preserving
234
- the assignment, Pi session, Git branch, and worktree. Resume the same work with
235
- `resume_work` using its branch. `stop_lead` does not resolve project work.
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).
@@ -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 assigned project Leads. It
399
- reads only an exact reference in evidence accepted by the caller's assignment;
400
- the reference itself grants no authorization. `ref` is required. `offset` is
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
@@ -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 supervised Leads and
15
- Chief's actionable direct reports use the stable `target` discovered in the
16
- current supervision context or `list_staff`. Project actions use the Git
17
- branch. A target resolves to an exact coordinator identity, but is not
18
- authorization: every action revalidates current identity and direct-report
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 branch with derived status
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`.
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 exact branch:
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 assignment while its worktree exists.
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, Git branch, and worktree are
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 an explicitly requested assigned project's linked
220
- checkout, or register an actionable approval request:
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 branch and project checkout, explains that
253
- managed execution may be stopped, and says the Git branch and Pi conversation
254
- remain while the assignment will be retired only after verified checkout
255
- removal. Type the exact word `remove`; cancellation or any other response has
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. Integrate an assigned local branch into the verified primary
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. This operation is
277
- separately controlled by the Manager local-merge policy (see
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 · active
67
- └─ ○ fix/other · paused
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 · active 14m 61%
76
- └─ ○ fix/other · paused
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 status is `active`, `paused`, or `conflict`.
88
- An active row uses the live Lead's lifecycle marker when an executor is present;
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.
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.36.2",
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"