pi-herdsman 0.36.2 → 0.36.3

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
@@ -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,19 @@ 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
 
70
73
  Start new work with `delegate_work`. Resume existing work with
71
- `resume_work` using its branch. A verified Git inventory showing the
74
+ `resume_work` using its original assignment branch handle; resume reuses the
75
+ existing verified checkout and exact Pi session without switching its current
76
+ branch. A verified Git inventory showing the
72
77
  assignment's worktree checkout is absent retires that assignment and its
73
78
  pending project messages; failed or ambiguous inventory preserves it. A retired
74
79
  assignment cannot be resumed, but a new delegation may start managed work from
@@ -141,9 +146,12 @@ does not necessarily require implementing them sequentially.
141
146
 
142
147
  ## Integrate completed branches
143
148
 
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
149
+ When an assigned Lead has completed and validated its work, the Manager can
150
+ accept the exact commit on the named branch currently checked out in its
151
+ verified checkout and use the Manager-only `integrate_branch` staff tool to
152
+ fast-forward the verified primary branch. The assignment branch remains the
153
+ selector; the actual source branch may differ and must still point to the
154
+ accepted SHA. This is local Git
147
155
  integration; it does not fetch, push, or merge a hosted pull request. The source
148
156
  and target must be clean, and a branch that does not contain the current target
149
157
  is returned as `needs_update`. That result is not proof of a content conflict.
@@ -154,7 +162,7 @@ the exact validated new source HEAD. Then accept that revision before retrying.
154
162
  Independent feature branches may be integrated one at a time; a later branch
155
163
  may need to incorporate earlier integration first. The Git branch is preserved.
156
164
  After verified integration, the operation attempts guarded removal of the
157
- exact source checkout and retirement of its assignment. `cleanup_pending`
165
+ exact assigned checkout and retirement of its assignment. `cleanup_pending`
158
166
  means integration is verified but at least one cleanup fact is not; retry
159
167
  with the same accepted SHA while permission remains enabled to retry the
160
168
  guarded cleanup. If the checkout is already absent, reconciliation requires
@@ -230,9 +238,11 @@ evidence only when it materially matters.
230
238
 
231
239
  ## Pause and resume
232
240
 
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.
241
+ `stop_lead` selects the assigned Lead by its original branch handle and stops
242
+ its owned Agent execution tree while preserving the assignment, Pi session,
243
+ verified checkout, and current Git state. Resume the same work with
244
+ `resume_work` using that assignment handle. `stop_lead` does not resolve
245
+ project work.
236
246
 
237
247
  See [`stop_lead`](../reference/staff.md#stop_lead) and
238
248
  [`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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-herdsman",
3
- "version": "0.36.2",
3
+ "version": "0.36.3",
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",