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.
- package/SKILL.md +6 -3
- package/dist/index.js +628 -132
- package/dist/index.js.map +3 -3
- package/docs/adr/0017-use-project-assignments-for-managed-lead-authority.md +5 -0
- package/docs/adr/0021-unify-direct-supervision-authority.md +56 -0
- package/docs/adr/0022-commit-project-retirement-before-message-cleanup.md +42 -0
- package/docs/adr/0023-deliver-worktree-retirement-through-pending-manager-context.md +35 -0
- package/docs/adr/0024-support-trusted-project-orchestration-preferences.md +41 -0
- package/docs/concepts/coordination.md +9 -9
- package/docs/development/smoke-testing.md +39 -11
- package/docs/development/validation.md +24 -13
- package/docs/guides/project-orchestration.md +20 -1
- package/docs/reference/commands.md +14 -8
- package/docs/reference/configuration.md +49 -17
- package/docs/reference/staff.md +10 -8
- package/docs/reference/status-widget.md +7 -5
- package/docs/reference/supervisor.md +4 -4
- package/package.json +1 -1
|
@@ -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
|
-
|
|
37
|
-
|
|
38
|
-
|
|
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
|
-
|
|
71
|
-
|
|
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
|
|
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 (
|
|
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
|
|
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.
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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),
|
|
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,
|
|
100
|
-
pause/resume with an intact checkout, Manager turnover
|
|
101
|
-
message, verified missing-worktree retirement without
|
|
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
|
-
##
|
|
179
|
+
## CI runtime smoke
|
|
180
180
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
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
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
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
|
|
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.
|
|
61
|
-
|
|
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
|
|
245
|
-
that same Manager startup when it has no persisted role intent and
|
|
246
|
-
project's primary workspace.
|
|
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
|
|
257
|
-
|
|
258
|
-
|
|
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,
|
|
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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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
|
|
68
|
-
managed-agent session. Herdsman suppresses
|
|
69
|
-
while the assignment finalizes and leaves Pi's
|
|
70
|
-
The session receives a finalization instruction,
|
|
71
|
-
fresh agent for follow-up. Disabling
|
|
72
|
-
|
|
73
|
-
session reuse behavior untouched.
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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`
|
package/docs/reference/staff.md
CHANGED
|
@@ -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
|
|
7
|
-
|
|
8
|
-
|
|
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
|
|
25
|
-
|
|
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.
|
|
94
|
-
|
|
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
|
|
81
|
-
|
|
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.
|
|
126
|
-
|
|
127
|
-
|
|
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
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
|