pi-herdsman 0.28.0 → 0.30.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.
@@ -4,6 +4,11 @@
4
4
  > supersedes the retirement conditions described below: verified checkout
5
5
  > absence also retires assignments. Exact-assignment authority and confirmed
6
6
  > `/takeover` remain unchanged; the current runtime implements the later policy.
7
+ >
8
+ > **Supervision update:** [ADR 0021](0021-unify-direct-supervision-authority.md)
9
+ > supersedes this record's restrictions on ordinary-Lead inspection,
10
+ > transcript access, and active-message steering. Exact-assignment project
11
+ > authority and the other decisions below remain in force.
7
12
 
8
13
  ## Status
9
14
 
@@ -0,0 +1,56 @@
1
+ # Unify direct supervision capabilities independently of project assignments
2
+
3
+ [Documentation index](../README.md)
4
+
5
+ ## Status
6
+
7
+ Accepted
8
+
9
+ ## Context
10
+
11
+ Manager supervision covers eligible Leads throughout the Manager's verified
12
+ project worktree group, while `ProjectAssignment` identifies which Lead owns
13
+ managed project execution. The ordinary-supervision restrictions introduced
14
+ in [ADR 0017](0017-use-project-assignments-for-managed-lead-authority.md) and
15
+ refined through PRs #405 and #413 made direct-report observation and active
16
+ message delivery depend on assignment status, despite supervision being
17
+ verified independently.
18
+
19
+ ## Decision
20
+
21
+ Verified direct supervision authorizes the same staff observation and
22
+ communication capabilities for assigned and ordinary Leads. This includes
23
+ bounded inspection, transcript reading when valid persisted session evidence is
24
+ available, and messaging; every operation still revalidates current identity
25
+ and authority.
26
+
27
+ Authorized supervisor messages use the same Pi-native cooperative steering
28
+ behavior regardless of project assignment. Steering is cooperative and does
29
+ not abort current work or interrupt an in-flight tool call.
30
+
31
+ `ProjectAssignment` remains the sole authority for managed project execution
32
+ and its lifecycle. Supervision alone does not grant project lifecycle
33
+ operations, project-result handoff, or accounting as managed work.
34
+
35
+ Exact-session ownership of Agents remains independent of supervision. A
36
+ supervisor does not acquire ownership of a Lead's Agent tree merely by
37
+ supervising that Lead.
38
+
39
+ This decision supersedes only the ordinary-supervision restrictions in ADR
40
+ 0017, as refined by PRs #405 and #413, on inspection, transcript access, and
41
+ active-message steering. It does not supersede ADR 0017's exact-assignment
42
+ authority, ADR 0019's assignment-retirement rules, or ADR 0020's confirmed
43
+ worktree-removal requirements.
44
+
45
+ ## Consequences
46
+
47
+ - Assigned and ordinary Leads in a verified direct-report scope have the same
48
+ observation and communication capabilities, subject to current validation
49
+ and transcript availability.
50
+ - Manager messages to ordinary Leads may cooperatively steer active work using
51
+ Pi's native delivery behavior.
52
+ - Project execution and its lifecycle remain assignment-bound; no assignment
53
+ is created or promoted by supervision.
54
+ - A Lead retains ownership of its Agent tree independently of who supervises
55
+ it.
56
+ - No new permission system, durable record, or transport is required.
@@ -0,0 +1,42 @@
1
+ # Commit project retirement before message cleanup
2
+
3
+ ## Status
4
+
5
+ Accepted. The worktree-retirement deletion decision is superseded by
6
+ [ADR 0023](0023-deliver-worktree-retirement-through-pending-manager-context.md).
7
+ Confirmed takeover still deletes the exact assignment; the commit-before-cleanup
8
+ ordering and assignment-scoped cleanup remain in force.
9
+
10
+ ## Decision
11
+
12
+ Removal of the exact current `ProjectAssignment`, including assignment-directory
13
+ synchronization, commits retirement. Compare identity and remove authority under
14
+ the existing global assignment-authority lock, inside the caller's branch lock.
15
+ Pending-message cleanup follows that commit and removes only records whose
16
+ `fromSessionId` identifies the retired assignment. A cleanup error is reported
17
+ without reversing or misreporting committed retirement.
18
+
19
+ Verified Manager initialization recovers interrupted cleanup from existing
20
+ assignment and message records, independently of worktree topology. Recovery
21
+ validates record identity against its storage path and holds the global
22
+ authority lock across comparison and deletion. It never acquires a branch lock
23
+ or restores authority. Uncertain records fail closed.
24
+
25
+ ## Rationale
26
+
27
+ [ADR 0016](0016-consume-project-messages-after-manager-delivery.md) keeps messages
28
+ pending-only; [ADR 0017](0017-use-project-assignments-for-managed-lead-authority.md)
29
+ makes assignments the sole authority; [ADR 0019](0019-retire-project-assignments-when-worktrees-are-absent.md)
30
+ defines retirement eligibility. Deleting messages before authority can lose a
31
+ handoff when retirement fails. Branch-wide cleanup can erase replacement work.
32
+ Existing exact session identities and durable records suffice for safe cleanup,
33
+ without transaction journals, tombstones, or another persistence schema.
34
+
35
+ ## Limits
36
+
37
+ If unlink succeeds but directory synchronization fails, propagate the error and
38
+ preserve messages; do not recreate authority or claim confirmed retirement.
39
+ Filesystem power-loss durability remains platform-dependent. Recovery is
40
+ opportunistic at Manager initialization, not a recurring cleanup service.
41
+ Retirement does not assert successful task completion or remove sessions,
42
+ branches, worktrees, conversations, or Agent ownership.
@@ -0,0 +1,35 @@
1
+ # Deliver worktree retirement through pending Manager context
2
+
3
+ ## Status
4
+
5
+ Accepted
6
+
7
+ ## Decision
8
+
9
+ The active-assignment namespace remains the authority boundary. Verified
10
+ worktree retirement atomically renames the exact assignment into pending context
11
+ storage outside that namespace, rather than deleting its evidence. This
12
+ supersedes only ADR 0022's worktree-retirement deletion decision; confirmed
13
+ `/takeover` retains exact assignment deletion and emits no retirement notice.
14
+ Commit-before-cleanup ordering and assignment-scoped handoff cleanup remain.
15
+
16
+ Pending retirement context belongs to the verified repository Manager role,
17
+ not a destination process. The existing inbox delivers factual context through
18
+ Pi without waking or steering the Manager. The same delivery path runs after
19
+ pre-turn reconciliation so the starting request includes newly discovered
20
+ retirement. Active runs are not interrupted.
21
+
22
+ Pi history owns delivered context, as in
23
+ [ADR 0016](0016-consume-project-messages-after-manager-delivery.md).
24
+ After retired-assignment handoff cleanup succeeds, exact notice receipts or
25
+ matching successful removal tool results prove awareness and permit consumption.
26
+ There is no permanent retirement log or separate acknowledgment database; a
27
+ crash between delivery and consumption can replay context to a replacement
28
+ Manager.
29
+
30
+ [ADR 0017](0017-use-project-assignments-for-managed-lead-authority.md)'s exact
31
+ assignment authority and [ADR 0019](0019-retire-project-assignments-when-worktrees-are-absent.md)'s
32
+ verified checkout-absence requirements are unchanged. Herdsman's retirement
33
+ operation does not itself delete Git branches or Pi conversations; external
34
+ actors may independently remove them. Retirement does not establish task
35
+ completion, acceptance, merge, or discard.
@@ -0,0 +1,41 @@
1
+ # Support trusted project orchestration preferences
2
+
3
+ ## Status
4
+
5
+ Accepted
6
+
7
+ ## Decision
8
+
9
+ Durable Herdsman coordination state remains under the resolved Pi agent data
10
+ directory, and the global Herdsman configuration remains the source of user
11
+ defaults. A trusted project's Pi settings may override only the
12
+ `autoActivateManager` and `contextRetirement` preferences in
13
+ `<project>/.pi/settings.json`, under `piHerdsman`. Explicit project values
14
+ override global values; omitted values inherit them.
15
+
16
+ These preferences configure behavior but do not establish authority or persist
17
+ lifecycle intent. Manager authority and Agent ownership continue to use their
18
+ existing contracts. Agent-definition precedence is unchanged. This is a narrow
19
+ exception for two project preferences, not a general project-configuration
20
+ framework.
21
+
22
+ This decision narrows ADR 0007's rejection of splitting Herdsman configuration
23
+ across project and global settings. Its decision to keep durable coordination
24
+ state and the global configuration under Pi agent data remains in force.
25
+
26
+ ## Rationale
27
+
28
+ Manager auto-start and context retirement are project-sensitive orchestration
29
+ preferences, while the global file remains the user's default. Pi's trusted
30
+ project settings provide a native, scoped place for those overrides without
31
+ moving durable coordination state or changing authority and lifecycle-state
32
+ ownership.
33
+
34
+ ## Consequences
35
+
36
+ - Only trusted project settings can override these two preferences.
37
+ - Global values continue to apply when the project is untrusted or a property
38
+ is omitted.
39
+ - Other Herdsman configuration fields remain global-only.
40
+ - Project and global Agent-definition composition is unaffected.
41
+ - No additional durable state or generalized inheritance mechanism is added.
@@ -32,11 +32,11 @@ An ordinary Lead in a verified project worktree group has the active project
32
32
  Manager as its supervisor; otherwise Chief supervises it when eligible. A Lead
33
33
  is managed for project execution only when exactly one current
34
34
  `ProjectAssignment` for the repository names its exact Pi session. Manager
35
- supervision of an ordinary Lead permits bounded discovery and communication
36
- only, not execution control, private inspection, Agent ownership, or automatic
37
- project-result delivery. Authorized messages may start a normal turn in an idle
38
- ordinary Lead, but do not steer active work; the Lead may reply explicitly with
39
- `message_supervisor`. Supervision does not grant Agent ownership: Manager
35
+ supervision of an ordinary Lead permits bounded discovery and communication,
36
+ including live inspection, persisted transcript access when available, and
37
+ cooperative steering through authorized messages. It does not grant project
38
+ execution control, Agent ownership, or automatic project-result delivery. The
39
+ Lead may reply explicitly with `message_supervisor`. Supervision does not grant Agent ownership: Manager
40
40
  and Chief can own only Agents they directly start from their own exact Pi
41
41
  session, when their effective `agents` profile permits it.
42
42
 
@@ -67,15 +67,15 @@ the session as ordinary `Orchestrate` execution.
67
67
  Manager is a dedicated project-coordination mode. It controls only Leads named
68
68
  by current `ProjectAssignment` records for its repository, and additionally
69
69
  supervises eligible ordinary Leads throughout its verified worktree group for
70
- bounded discovery and communication. Ordinary Leads allow message-only staff
71
- access. Manager may optionally start its own Agents using definitions in its
70
+ the same direct-report observation and communication capabilities as assigned
71
+ Leads. Manager may optionally start its own Agents using definitions in its
72
72
  effective `agents` profile. This does not grant control over supervised Leads'
73
73
  Agents or alter project assignments or authority. Its reserved `manager`
74
74
  definition customizes instructions, ordinary tool selection, and this
75
75
  direct-delegation allowlist.
76
76
 
77
77
  Project execution belongs to assigned Leads and their Agent trees. Manager can
78
- inspect assigned Leads and communicate with all direct Leads, but it does not
78
+ inspect and communicate with all direct Leads, but it does not
79
79
  acquire ownership of their Agents.
80
80
 
81
81
  ### Chief
@@ -187,7 +187,7 @@ Coordination crosses one authority edge at a time:
187
187
  | Up | `message_supervisor` / automatic results | Assigned Lead -> Manager |
188
188
  | Down | `message_staff` / project operations | Manager -> assigned Lead |
189
189
  | Up | `message_supervisor` | Ordinary Lead -> Manager or Chief; Manager -> Chief |
190
- | Down | `message_staff` | Manager -> ordinary Lead (idle turn; active queued) |
190
+ | Down | `message_staff` | Manager -> ordinary Lead (cooperative steering) |
191
191
  | Sideways | `message_peer` | Lead <-> Lead or Manager <-> Manager |
192
192
  | Ownership | Agent controls / `reply_agent`; `ask_owner` | owner <-> directly owned Agent |
193
193
 
@@ -57,7 +57,7 @@ managed descendants do not load the probe.
57
57
 
58
58
  ### Deterministic simulated acceptance
59
59
 
60
- The harness also supports an opt-in Pi-native faux provider for five bounded
60
+ The harness also supports an opt-in Pi-native faux provider for seven bounded
61
61
  scenarios:
62
62
 
63
63
  ```sh
@@ -66,6 +66,8 @@ npm run smoke -- continuation --simulated
66
66
  npm run smoke -- chief-tree --simulated
67
67
  npm run smoke -- supervisor-agent --simulated
68
68
  npm run smoke -- terminal-failure --simulated
69
+ npm run smoke -- agent-terminal-failure --simulated
70
+ npm run smoke -- manager-handoff --simulated
69
71
  ```
70
72
 
71
73
  Simulation supplies model decisions only. Pi still runs its real agent loop and
@@ -73,10 +75,12 @@ tools, while Herdsman and Herdr perform and record the actual delegation,
73
75
  continuation, role transitions, process/session lifecycle, and cleanup. The
74
76
  provider accepts only expected transcript states and requires actual correlated
75
77
  tool results before producing completion responses. It cannot produce
76
- successful tool results or directly mutate Herdsman or Herdr state. Simulated
77
- runs do not require model credentials or inference, but retain runtime
78
- compatibility checks, build, isolation, Herdr setup, and cleanup. They are
79
- integration checks, not replacements for real-model acceptance.
78
+ successful tool results or directly mutate Herdsman or Herdr state. The two
79
+ additional scenarios are simulated-only and use real Pi, Herdsman, and Herdr;
80
+ they do not replace live-model acceptance. Simulated runs do not require model
81
+ credentials or inference, but retain runtime compatibility checks, build,
82
+ isolation, Herdr setup, and cleanup. They are integration checks, not
83
+ replacements for real-model acceptance.
80
84
 
81
85
  Nested Agent completions arrive asynchronously through Herdsman's normal
82
86
  `pi.sendMessage(..., { triggerTurn: true, deliverAs: "steer" })` path. Pi
@@ -84,22 +88,46 @@ normalizes these custom results as user messages in the provider transcript.
84
88
  The faux rules require the exact delivered Agent-result message and its
85
89
  correlated successful tool call before returning completion markers; the smoke
86
90
  assertions independently verify the persisted tool and session evidence.
91
+ For a separate external Git checkout-absence check, the maintainer-only
92
+ `manager-recovery --manager-external-removal` variant reuses the same disposable
93
+ lifecycle and passive-notice assertions. It revalidates the exact owned checkout,
94
+ branch, workspace, and isolated Git repository before non-forced Git worktree
95
+ removal. The default `manager-recovery` invocation retains Herdr removal. These
96
+ are separate acceptance invocations; neither adds a production setting or
97
+ proves pending retirement delivery across Manager replacement.
98
+
87
99
  `manager-recovery --simulated` remains unsupported and fails immediately.
88
100
  `--simulated` cannot be combined with `--model`. Without
89
101
  `--simulated`, the configured or explicitly selected live model remains in use;
90
102
  there is no fallback between modes. `terminal-failure` uses the same native
91
103
  faux fixture for its disposable Lead's controlled partial response and terminal
92
104
  error, while its Manager remains on the selected live model unless the whole
93
- scenario is explicitly simulated.
105
+ scenario is explicitly simulated. `agent-terminal-failure` verifies that a
106
+ real managed Agent's native Pi terminal execution failure settles as a failed
107
+ assignment and reaches its exact owner; partial assistant text is not accepted
108
+ as successful assignment content. It does not establish replay guarantees for
109
+ arbitrary tool side effects. `manager-handoff` verifies that an assigned Lead's
110
+ ordinary project message is retained while the Manager role is absent and
111
+ delivered after Manager mode is reentered in a new role generation, without
112
+ retiring or changing the project assignment. It does not test complete Pi
113
+ session replacement, worktree retirement, or passive retirement notices.
114
+ Project-message delivery may be replayed after ambiguous delivery and Manager
115
+ replacement as described by [ADR 0016](../adr/0016-consume-project-messages-after-manager-delivery.md);
116
+ this scenario does not establish universal exactly-once transport or tool
117
+ side effects.
94
118
 
95
119
  The available scenarios are `core` (nested delegation and candidate-extension
96
120
  propagation), `continuation` (persisted Pi-session continuation across managed
97
- generations), `chief-tree` (current Chief/session_tree behavior), and
121
+ generations), `chief-tree` (current Chief/session_tree behavior),
98
122
  `supervisor-agent` (Chief direct Agent delegation, completed result delivery,
99
- and role exit), `manager-recovery` (Manager delegation, review messaging, `stop_lead`, verified
100
- pause/resume with an intact checkout, Manager turnover with a pending project
101
- message, verified missing-worktree retirement without recreating the assignment,
102
- and refusal to resume retired work).
123
+ and role exit), `manager-recovery` (Manager delegation, review messaging,
124
+ `stop_lead`, verified pause/resume with an intact checkout, Manager turnover
125
+ with a pending project message, verified missing-worktree retirement without
126
+ recreating the assignment, and refusal to resume retired work),
127
+ `agent-terminal-failure` (managed-Agent terminal failure settlement and exact
128
+ owner delivery), `manager-handoff` (project-message retention during Manager
129
+ absence and delivery after role reentry), and `terminal-failure` (assigned-Lead
130
+ terminal failure and project reporting).
103
131
  `terminal-failure` creates an isolated Manager project and exactly assigned
104
132
  Lead, selects the isolated native faux `terminal-error` model only for that
105
133
  Lead, and exhausts Pi's bounded native retry after partial assistant output
@@ -176,30 +176,41 @@ Record:
176
176
 
177
177
  Do not claim a passing full check from a partial focused run.
178
178
 
179
- ## Runtime smoke verification
179
+ ## CI runtime smoke
180
180
 
181
- Deterministic tests are the repository gate. Cross-process Pi/herdr behavior may
182
- also require isolated live smoke, selected according to the change being
183
- verified:
181
+ GitHub Actions runs all supported simulated Pi/Herdr smoke scenarios for
182
+ changes affecting the runtime, its dependencies, build, smoke harness, or
183
+ validation workflow. The existing required `CI` check fails when required
184
+ smoke does not succeed. Documentation-only and test-only changes normally skip
185
+ it.
186
+
187
+ Simulated acceptance uses real Pi, Herdsman, and Herdr processes without model
188
+ credentials. It does not verify real-model decisions. The supported simulated
189
+ scenarios are `core`, `continuation`, `chief-tree`, `supervisor-agent`, and
190
+ `terminal-failure`.
191
+
192
+ `npm run validate` remains unchanged and does not run smoke. Manual/live smoke
193
+ remains separate and opt-in. For cross-process Pi/Herdr behavior outside the CI
194
+ acceptance, choose an isolated smoke scenario according to the change:
184
195
 
185
196
  ```sh
186
197
  npm run smoke
187
198
  npm run smoke -- core
188
199
  npm run smoke -- continuation
189
200
  npm run smoke -- chief-tree
201
+ npm run smoke -- supervisor-agent
190
202
  npm run smoke -- manager-recovery
191
203
  npm run smoke -- terminal-failure
192
204
  ```
193
205
 
194
- The opt-in `--simulated` mode covers `core`, `continuation`, `chief-tree`, and
195
- `terminal-failure` using
196
- Pi's native faux provider, without remote inference credentials. It retains
197
- the real Pi/Herdr runtime checks and does not replace live-model acceptance.
198
- `manager-recovery` remains live-only and rejects `--simulated`. Asynchronous
199
- Agent results are delivered as user messages to the real Pi transcript; the
200
- simulated scenarios require those delivered results and correlated tool
201
- evidence. Without that flag, smoke remains live-model acceptance and uses the configured
202
- `pi-herdsman.smoke-model` or a one-run `--model` override.
206
+ The opt-in `--simulated` mode uses Pi's native faux provider without remote
207
+ inference credentials. It retains the real Pi/Herdr runtime checks and does not
208
+ replace live-model acceptance. `manager-recovery` remains live-only and rejects
209
+ `--simulated`. Asynchronous Agent results are delivered as user messages to the
210
+ real Pi transcript; the simulated scenarios require those delivered results
211
+ and correlated tool evidence. Without that flag, smoke remains live-model
212
+ acceptance and uses the configured `pi-herdsman.smoke-model` or a one-run
213
+ `--model` override.
203
214
  `npm run smoke` defaults to live `core`. The runner creates its own isolated
204
215
  Herdr server and workspace, so smoke can run from an ordinary repository
205
216
  shell, including one already inside Herdr. See [Smoke testing](smoke-testing.md)
@@ -164,6 +164,23 @@ See [`stop_lead`](../reference/staff.md#stop_lead) and
164
164
 
165
165
  ## Retire project work
166
166
 
167
+ Verified worktree retirement atomically removes the exact assignment from active
168
+ authority and preserves it as pending context for the repository's Manager role.
169
+ The next verified Manager receives a factual, hidden Pi context message without
170
+ starting a turn or interrupting active work. Pre-turn reconciliation delivers
171
+ newly discovered retirement before the first model request; background delivery
172
+ waits for idle. Pre-turn processing is bounded; excess backlog remains pending
173
+ for later inbox passes. The notice does not establish completion, acceptance, merge, or
174
+ discard, and preserves the Git branch and Pi conversation.
175
+
176
+ Pending context survives Manager replacement. After assignment-scoped handoff
177
+ cleanup succeeds and Pi history proves delivery, it is consumed rather than
178
+ kept as a retirement log. An exact successful removal tool result in the receiving
179
+ Manager's history also proves awareness; a UI-only notification does not.
180
+ A crash between delivery and consumption can replay context to a replacement
181
+ Manager. Cleanup failures preserve pending evidence for a later inbox pass.
182
+ Takeover does not generate a worktree-retirement notice.
183
+
167
184
  Successful Herdr worktree removal or verified checkout absence retires the
168
185
  matching project assignment and any still-pending messages; the Git branch
169
186
  remains. Failed or ambiguous inventory does not imply absence, so the
@@ -210,7 +227,9 @@ the current Herdr runtime and directly supervises ordinary Leads only when they
210
227
  have no active project Manager. An active Manager supervises every eligible
211
228
  Lead in its verified project worktree group, but controls project execution
212
229
  only for Leads named by exact current project assignments. Ordinary Leads
213
- remain independent and receive message-only Manager supervision; ambiguous
230
+ remain independent while receiving the same verified direct-report inspection,
231
+ transcript (when valid persisted evidence exists), and messaging capabilities;
232
+ authorized messages can cooperatively steer an active Lead. Ambiguous
214
233
  Manager evidence does not trigger Chief fallback. Assignment authority
215
234
  survives Manager process replacement. A Manager does not become Chief or
216
235
  forward assigned Leads into a parallel Chief control path.
@@ -57,8 +57,12 @@ depend on Agent status or definitions to render.
57
57
  `Settings` contains `Default Lead execution`, `Manager auto-start`, `Context
58
58
  retirement`, and `Message limits`. The default is `Flexible` and applies only
59
59
  when a future ordinary Lead session has no persisted execution choice; changing
60
- it does not change the current session. The Message limits view edits the user-wide inline attachment and
61
- mailbox payload limits. It is available only to a lead Pi session with UI.
60
+ it does not change the current session. Manager auto-start and context
61
+ retirement show their effective values and identify project overrides, when
62
+ present. These controls edit the global defaults only; project overrides are
63
+ edited in the trusted project's `.pi/settings.json` under `piHerdsman`. The
64
+ Message limits view edits the user-wide inline attachment and mailbox payload
65
+ limits. It is available only to a lead Pi session with UI.
62
66
  Current values and presets show a rough token equivalent using four UTF-8
63
67
  bytes per token. The enforced limits are bytes, not tokens.
64
68
 
@@ -241,9 +245,10 @@ session's ordinary Lead tool baseline and selected execution profile. Their
241
245
  `agents` allowlist independently controls fresh direct delegation. See
242
246
  [Coordination](../concepts/coordination.md) for the role and project boundaries.
243
247
 
244
- The `Manager auto-start` setting optionally makes a new session attempt
245
- that same Manager startup when it has no persisted role intent and starts in the
246
- project's primary workspace. Explicit persisted Lead, Manager, or Chief intent
248
+ The effective `Manager auto-start` setting optionally makes a new session
249
+ attempt that same Manager startup when it has no persisted role intent and
250
+ starts in the project's primary workspace. A trusted project value can
251
+ override the global default. Explicit persisted Lead, Manager, or Chief intent
247
252
  takes precedence. Ineligible or contended optional startup remains an ordinary
248
253
  Lead; successful automatic startup does not persist Manager intent. Changing
249
254
  the setting affects only a later `session_start`, not the running role.
@@ -253,9 +258,10 @@ live assigned Lead, plus `Remove worktree…` for assigned projects including
253
258
  paused work. This uses the same explicitly confirmed removal operation as
254
259
  `/manager remove <branch>`; it preserves the Git branch and Pi conversation.
255
260
  Running managed execution may be stopped, and assignment retirement is
256
- reported separately from checkout removal. Manager staff reports contain only live exact Leads named
257
- by current project assignments; physical worktree scope alone grants no
258
- authority. Project assignments survive Manager replacement and manual
261
+ reported separately from checkout removal. Manager staff reports include
262
+ eligible live Leads in its verified worktree group; exact current assignments
263
+ grant project execution and lifecycle authority, not direct supervision.
264
+ Project assignments survive Manager replacement and manual
259
265
  continuation of the exact assigned Pi session. `managed-lead` is launch policy,
260
266
  not authority. Successful Herdr worktree removal or verified checkout absence
261
267
  retires an assignment; failed or ambiguous inventory preserves it. A retired
@@ -2,7 +2,8 @@
2
2
 
3
3
  [Documentation index](../README.md)
4
4
 
5
- Pi Herdsman keeps its configuration in one flat, user-wide file:
5
+ Pi Herdsman keeps its defaults and general configuration in one flat,
6
+ user-wide file:
6
7
 
7
8
  ```text
8
9
  <Pi agent directory>/pi-herdsman/config.json
@@ -13,9 +14,28 @@ The default location is `~/.pi/agent/pi-herdsman/config.json`. Pi's native
13
14
  `PI_CODING_AGENT_DIR` relocates the file to
14
15
  `$PI_CODING_AGENT_DIR/pi-herdsman/config.json`.
15
16
 
16
- Project trust and project settings do not affect Herdsman configuration.
17
- Agent definitions remain a separate feature and continue to use the bundled,
18
- project-local, and user agent-definition locations described in the
17
+ Two preferences can be overridden for a trusted project in Pi's
18
+ `<project>/.pi/settings.json`:
19
+
20
+ ```json
21
+ {
22
+ "piHerdsman": {
23
+ "autoActivateManager": true,
24
+ "contextRetirement": false
25
+ }
26
+ }
27
+ ```
28
+
29
+ Only `autoActivateManager` and `contextRetirement` are project-overridable.
30
+ Built-in defaults are overlaid by the global configuration, then by explicitly
31
+ set project values. An omitted project property inherits the global value;
32
+ explicit `false` overrides global `true`. Project overrides apply only when Pi
33
+ considers the current project trusted. An untrusted project or an absent
34
+ project override inherits the global value; malformed trusted project settings
35
+ raise a configuration error instead of falling back. The rest of
36
+ `.pi/settings.json` remains Pi-owned. Agent definitions are separate and
37
+ continue to use the bundled, project-local, and user agent-definition
38
+ locations described in the
19
39
  [agent-definition guide](../guides/agent-definitions.md).
20
40
 
21
41
  ## Schema and defaults
@@ -64,19 +84,31 @@ coordination records remain subject to this configured limit and their fixed
64
84
  inbox notification, so that coordination ceiling does not reduce the evidence
65
85
  capacity of a Manager-to-Lead assignment.
66
86
 
67
- When `contextRetirement` is enabled, automatic context pressure retires a
68
- managed-agent session. Herdsman suppresses preventive threshold compaction
69
- while the assignment finalizes and leaves Pi's overflow recovery available.
70
- The session receives a finalization instruction, and its result requires a
71
- fresh agent for follow-up. Disabling it bypasses retirement completely,
72
- including existing retirement markers, and leaves Pi's native compaction and
73
- session reuse behavior untouched.
74
-
75
- When `autoActivateManager` is enabled, a session without a persisted
76
- `pi-herdsman-role` entry attempts Manager startup only from its Herdr primary
77
- workspace. Linked workspaces, unavailable eligibility evidence, or an existing
78
- Manager leave it as an ordinary Lead. The preference does not persist Manager
79
- role intent and changing it does not affect the current session.
87
+ When the effective `contextRetirement` preference is enabled, automatic
88
+ context pressure retires a managed-agent session. Herdsman suppresses
89
+ preventive threshold compaction while the assignment finalizes and leaves Pi's
90
+ overflow recovery available. The session receives a finalization instruction,
91
+ and its result requires a fresh agent for follow-up. Disabling the preference
92
+ bypasses retirement, including enforcement of existing retirement markers,
93
+ and leaves Pi's native compaction and session reuse behavior untouched. The
94
+ preference is evaluated at retirement and continuation checks, so a trusted
95
+ project setting can change how an existing marker is enforced. The policy is
96
+ applied in the applicable project context; a caller's project override cannot
97
+ bypass a retired marker for an Agent from another project when that target
98
+ project's applicable opt-out cannot be verified. In that case, continue from
99
+ the original trusted project context or create a fresh Agent.
100
+
101
+ When the effective `autoActivateManager` preference is enabled, a session
102
+ without a persisted `pi-herdsman-role` entry attempts Manager startup only from
103
+ its Herdr primary workspace. Linked workspaces, unavailable eligibility
104
+ evidence, or an existing Manager leave it as an ordinary Lead. The preference
105
+ does not persist Manager role intent and changing it does not affect the current
106
+ session.
107
+
108
+ The Settings menu edits global defaults only. It identifies when the effective
109
+ Manager auto-start or context-retirement value comes from a project override;
110
+ changing the global value does not replace that project value. Edit a project
111
+ override in the project's `.pi/settings.json`.
80
112
 
81
113
  Placement affects future starts, not existing agents. `tab` uses one lead-owned
82
114
  agents tab, `subtree` gives each lead-direct agent its own tab, and `split`
@@ -3,9 +3,10 @@
3
3
  [Documentation index](../README.md) · [Coordination](../concepts/coordination.md)
4
4
 
5
5
  Staff tools are available to active Chief and Manager sessions. Both roles can
6
- use `list_staff` and `message_staff`. `inspect_staff` and
7
- `read_staff_transcript` are available for Chief direct reports and Manager's
8
- assigned Leads, not ordinary Manager-supervised Leads. Manager additionally has
6
+ use `list_staff`, `inspect_staff`, and `message_staff`; `read_staff_transcript`
7
+ is available when persisted session evidence is available. Manager and Chief
8
+ have the same direct-report observation and communication capabilities.
9
+ Manager additionally has
9
10
  the branch-based project operations `delegate_project`, `resume_project`,
10
11
  `stop_lead`, and `remove_worktree`. Chief has no project-operation tools.
11
12
 
@@ -21,8 +22,10 @@ Manager. Assigned Leads are never Chief targets. A Manager's nested assigned
21
22
  and ordinary supervised Leads may be summarized for Chief but are not Chief
22
23
  targets. Manager sees eligible Leads throughout its verified project worktree
23
24
  group. A current `ProjectAssignment` marks an assigned report; an ordinary
24
- report is derived supervision only and permits `message_staff`, not inspection,
25
- transcript access, steering, stopping, or project lifecycle operations.
25
+ report is derived supervision, not project ownership. Both assigned and
26
+ ordinary Manager reports allow inspection, transcript access when valid
27
+ persisted evidence is available, and messaging. Project lifecycle operations
28
+ remain assignment-bound.
26
29
  Ordinary Manager-supervised Leads are excluded from Chief's actionable roster.
27
30
  Ambiguous duplicate assignments or unverified topology do not produce an
28
31
  actionable report.
@@ -90,9 +93,8 @@ Sends an asynchronous durable message to the exact current direct report. The
90
93
  message is queued by Herdsman before submission. If an assigned report is
91
94
  actively running, supervisor direction uses Pi's cooperative steering lane;
92
95
  steering does not abort the current operation or interrupt an in-flight tool
93
- call. A Manager message to an ordinary Lead starts a turn when the Lead is idle;
94
- while active, the message remains queued and does not steer the Lead's current
95
- work.
96
+ call. Authorized Manager messages to ordinary Leads use the same cooperative
97
+ steering behavior, whether the Lead is active or idle.
96
98
  `files` accepts ordinary paths, reusable direct Agent refs, and canonical
97
99
  result refs already supplied as evidence. Attachments are prepared at
98
100
  submission; the coordination record carries the prepared text and any hidden
@@ -77,8 +77,9 @@ An active row uses the live Lead's lifecycle marker when an executor is present;
77
77
  otherwise it uses `●`. Paused uses `○` and conflict uses `!`. The row suffix is
78
78
  project status, not the Lead's runtime state.
79
79
  Ordinary Leads supervised by the Manager are shown separately from project
80
- work, with a supervised label and navigation only; they are not treated as
81
- managed work. Branches are display handles; exact session identity is
80
+ work, with a supervised label; they are not treated as managed work. A Manager
81
+ can inspect an eligible direct report through the overview, independently of
82
+ mouse focus/navigation. Branches are display handles; exact session identity is
82
83
  revalidated for control actions.
83
84
 
84
85
  ## Installation
@@ -122,9 +123,10 @@ and the existing keyboard/menu alternatives such as the Running menu and
122
123
 
123
124
  Navigation does not grant coordination authority. Agent targets are checked
124
125
  against the caller's durable ownership ancestry; Manager targets for project
125
- control require the Lead's current exact project assignment. Ordinary
126
- Manager-supervised Leads permit focus/navigation only, and Chief-visible nested
127
- Leads remain observational. Paused or conflicted project work, lost or unresolved sessions,
126
+ control require the Lead's current exact project assignment. Direct-report
127
+ inspection and messaging use their own fresh supervision authorization;
128
+ focus/navigation alone grants neither. Chief-visible nested Leads remain
129
+ observational. Paused or conflicted project work, lost or unresolved sessions,
128
130
  stale projections, truncated/omitted entries, and targets without a uniquely
129
131
  verified live Herdr pane are inert. Current placement is checked again when a
130
132
  click is handled; the status projection itself is never authorization.
@@ -54,10 +54,10 @@ recipient to forward them.
54
54
 
55
55
  Direct-supervisor messages are queued for the exact current recipient and
56
56
  validated against current authority before delivery. A Manager message to an
57
- ordinary Lead starts a normal turn when the Lead is idle and remains queued
58
- while it is active; it does not steer active work. Ordinary Leads can reply
59
- explicitly with `message_supervisor`; a triggered turn does not guarantee a
60
- reply. Assigned Lead delivery retains existing steering/follow-up behavior.
57
+ ordinary Lead uses Pi's cooperative steering lane whether the Lead is active or
58
+ idle. Steering does not abort the current operation or interrupt an in-flight
59
+ tool call. Ordinary Leads can reply explicitly with `message_supervisor`; a
60
+ triggered turn does not guarantee a reply.
61
61
 
62
62
  ## See also
63
63