pi-herdsman 0.40.0 → 0.41.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/CHANGELOG.md +44 -0
- package/README.md +18 -1
- package/SKILL.md +8 -6
- package/dist/coordinators/manager.md +5 -6
- package/dist/index.js +1643 -1300
- package/dist/index.js.map +4 -4
- package/dist/peer-bridge.js +23 -13
- package/dist/peer-bridge.js.map +3 -3
- package/docs/README.md +2 -2
- package/docs/concepts/agents.md +1 -1
- package/docs/concepts/lifecycle.md +6 -4
- package/docs/coordination-api.md +3 -2
- package/docs/development/validation.md +12 -8
- package/docs/getting-started.md +9 -2
- package/docs/guides/container-deployment.md +126 -38
- package/docs/guides/project-orchestration.md +10 -0
- package/docs/guides/recovery.md +12 -11
- package/docs/reference/agent-definition-schema.md +1 -1
- package/docs/reference/agent-states.md +10 -10
- package/docs/reference/agent.md +26 -25
- package/docs/reference/commands.md +1 -1
- package/docs/reference/staff.md +9 -2
- package/package.json +3 -2
package/docs/README.md
CHANGED
|
@@ -11,7 +11,8 @@ do not drift into competing contracts.
|
|
|
11
11
|
Start with [Getting started](getting-started.md).
|
|
12
12
|
|
|
13
13
|
It covers installation, the first asynchronous Agent delegation, `/herdsman`,
|
|
14
|
-
configuration, and where to go next.
|
|
14
|
+
configuration, and where to go next. For a prebuilt SSH-accessible environment,
|
|
15
|
+
use [Container deployment](guides/container-deployment.md).
|
|
15
16
|
|
|
16
17
|
## Orchestrate project work
|
|
17
18
|
|
|
@@ -35,7 +36,6 @@ authority, project-scope, and ownership model.
|
|
|
35
36
|
- [Customizing bundled Agents](guides/customizing-agents.md)
|
|
36
37
|
- [Agent-definition schema](reference/agent-definition-schema.md)
|
|
37
38
|
- [Configuration](reference/configuration.md)
|
|
38
|
-
- [Container deployment](guides/container-deployment.md)
|
|
39
39
|
|
|
40
40
|
## Use the coordination API
|
|
41
41
|
|
package/docs/concepts/agents.md
CHANGED
|
@@ -33,7 +33,7 @@ my-review
|
|
|
33
33
|
|
|
34
34
|
Use the exact `agent` value from `list_agents` only for
|
|
35
35
|
the `agent` parameter to `inspect_agent`, `read_agent_transcript`, `steer_agent`,
|
|
36
|
-
`interrupt_agent`, `reply_agent`, or `
|
|
36
|
+
`interrupt_agent`, `reply_agent`, or `stop_agent` while those actions are listed
|
|
37
37
|
in `available_tools`. An agent label is the stable logical name across
|
|
38
38
|
sequential generations of one managed session, not a continuation selector.
|
|
39
39
|
It is a control target only for the currently live generation.
|
|
@@ -164,7 +164,7 @@ turn. For stale attention:
|
|
|
164
164
|
Do not repeat reads solely because of a reminder.
|
|
165
165
|
6. Otherwise use `interrupt_agent` to abandon the current operation and continue
|
|
166
166
|
the same assignment; it supersedes earlier undelivered steering.
|
|
167
|
-
7. Use `
|
|
167
|
+
7. Use `stop_agent` only when abandoning the assignment is intended.
|
|
168
168
|
|
|
169
169
|
For other attention, use `read_agent_transcript` for persisted Pi conversation and tool
|
|
170
170
|
history and `inspect_agent` for live terminal/process state as needed. Use `reply_agent` only
|
|
@@ -216,7 +216,7 @@ After normal mailbox cleanup, scoped continuation is allowed only when the
|
|
|
216
216
|
saved assignment evidence matches its terminal result, or verified closure
|
|
217
217
|
evidence matches the accepted request, exact session, and exact owner on the
|
|
218
218
|
active Pi branch, and the project remains currently authorized. A clean
|
|
219
|
-
`
|
|
219
|
+
`stop_agent` or `/agents stop` may preserve a versioned owner-history receipt for
|
|
220
220
|
explicit exact-session continuation. Stop never automatically restarts an
|
|
221
221
|
Agent. Closing or stopping abandons unfinished work; continuation starts a new
|
|
222
222
|
generation from the saved conversation and does not replay that work.
|
|
@@ -251,8 +251,10 @@ has not yet delivered, and supplies the replacement instruction that continues
|
|
|
251
251
|
the same assignment. The generation, active task
|
|
252
252
|
request, ownership, Pi session, and final-result obligation remain unchanged.
|
|
253
253
|
|
|
254
|
-
Neither action creates another assignment. `
|
|
255
|
-
|
|
254
|
+
Neither action creates another assignment. `stop_agent` abandons the Agent's
|
|
255
|
+
unfinished assignment and managed generation. By contrast, `stop_lead` stops a
|
|
256
|
+
Manager-assigned Lead while preserving the project assignment, Pi session,
|
|
257
|
+
branch, and worktree.
|
|
256
258
|
|
|
257
259
|
Steering is at-least-once at the agent boundary: an agent can apply a steer
|
|
258
260
|
before its acknowledgement write is recorded. If that acknowledgement write
|
package/docs/coordination-api.md
CHANGED
|
@@ -18,7 +18,7 @@ continue_agent
|
|
|
18
18
|
steer_agent
|
|
19
19
|
interrupt_agent
|
|
20
20
|
reply_agent
|
|
21
|
-
|
|
21
|
+
stop_agent
|
|
22
22
|
inspect_agent
|
|
23
23
|
read_agent_transcript
|
|
24
24
|
```
|
|
@@ -35,7 +35,8 @@ Chief and Manager use [Staff tools](reference/staff.md) for direct-report
|
|
|
35
35
|
observation and communication.
|
|
36
36
|
|
|
37
37
|
Manager additionally uses branch-based project operations to start and resume
|
|
38
|
-
project work, can stop a Lead
|
|
38
|
+
project work, can use `stop_lead` to stop a Lead while preserving its project
|
|
39
|
+
assignment, and can request
|
|
39
40
|
independent human confirmation to remove an assigned project's worktree.
|
|
40
41
|
`resume_work` requires a fresh instruction for the existing assignment; it
|
|
41
42
|
queues that instruction separately without replacing the saved task. Already
|
|
@@ -17,6 +17,8 @@ npm run format
|
|
|
17
17
|
|
|
18
18
|
# Read-only verification before staging or committing.
|
|
19
19
|
npm run format:check
|
|
20
|
+
npm run typecheck
|
|
21
|
+
npm run lint -- --deny-warnings
|
|
20
22
|
npm run check
|
|
21
23
|
git diff --check
|
|
22
24
|
```
|
|
@@ -24,11 +26,13 @@ git diff --check
|
|
|
24
26
|
Do not run formatting again between these verification commands and staging or
|
|
25
27
|
committing.
|
|
26
28
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
29
|
+
TypeScript typechecking (`npm run typecheck`) and warning-free Oxlint
|
|
30
|
+
(`npm run lint -- --deny-warnings`) are mandatory local and CI checks.
|
|
31
|
+
`npm run validate` runs formatting verification, typechecking, warning-free
|
|
32
|
+
linting, tests, build, and package audit. `npm run format` applies formatting;
|
|
33
|
+
`npm run format:check` verifies it without changing files. Both use the locally
|
|
34
|
+
installed Prettier version pinned by the lockfile. `npm run check` runs the
|
|
35
|
+
bounded behavioral test suite, and `git diff --check` checks Git whitespace.
|
|
32
36
|
|
|
33
37
|
When reviewing staged work, also run as appropriate:
|
|
34
38
|
|
|
@@ -54,7 +58,8 @@ The test runner uses:
|
|
|
54
58
|
|
|
55
59
|
On POSIX systems the test runner runs in a detached process group. On Windows
|
|
56
60
|
it runs as a normal child process and uses the native `taskkill.exe /PID <pid>
|
|
57
|
-
/T /F` process-tree operation for timeout cleanup.
|
|
61
|
+
/T /F` process-tree operation for timeout cleanup. The suite deadline is
|
|
62
|
+
360 seconds on all three platforms.
|
|
58
63
|
|
|
59
64
|
On POSIX suite deadline, the runner attempts:
|
|
60
65
|
|
|
@@ -68,8 +73,7 @@ snapshot. The runner invokes `taskkill.exe /PID <pid> /T /F` and waits for the
|
|
|
68
73
|
runner process to disappear. Filename attribution is best-effort and may be
|
|
69
74
|
unavailable when cleanup wins the race; raw command lines and environment
|
|
70
75
|
details are not logged. Snapshot failure does not replace the original
|
|
71
|
-
suite-timeout failure.
|
|
72
|
-
disappearance does not verify descendant
|
|
76
|
+
suite-timeout failure. Runner disappearance does not verify descendant
|
|
73
77
|
cleanup, which is explicitly reported as unverified.
|
|
74
78
|
|
|
75
79
|
A test runner that leaks descendants after normal exit is reported as a failure
|
package/docs/getting-started.md
CHANGED
|
@@ -16,6 +16,9 @@ curl -fsSL https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.sh
|
|
|
16
16
|
irm https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.ps1 | iex
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
+
**Docker Compose:** For a prebuilt SSH-accessible environment instead of a
|
|
20
|
+
native installation, follow [Container deployment](guides/container-deployment.md).
|
|
21
|
+
|
|
19
22
|
**Already have Pi and Herdr?**
|
|
20
23
|
|
|
21
24
|
```sh
|
|
@@ -23,20 +26,24 @@ pi install npm:pi-herdsman
|
|
|
23
26
|
herdr integration install pi
|
|
24
27
|
```
|
|
25
28
|
|
|
26
|
-
The bootstraps install missing components and preserve compatible newer
|
|
29
|
+
The native bootstraps install missing components and preserve compatible newer
|
|
27
30
|
versions. If installation fails, follow the reported recovery instructions.
|
|
28
31
|
For manual installation, see [Pi's Quickstart](https://pi.dev/docs/latest/quickstart)
|
|
29
32
|
and [Herdr's installation guide](https://herdr.dev/docs/install/).
|
|
30
33
|
|
|
31
34
|
## Start Pi in Herdr
|
|
32
35
|
|
|
33
|
-
|
|
36
|
+
For a native installation, start Herdr in your project directory, then Pi
|
|
37
|
+
in its pane:
|
|
34
38
|
|
|
35
39
|
```sh
|
|
36
40
|
herdr
|
|
37
41
|
pi
|
|
38
42
|
```
|
|
39
43
|
|
|
44
|
+
With Docker, [connect to the container](guides/container-deployment.md#quick-start)
|
|
45
|
+
and run `pi` in the Herdr pane instead.
|
|
46
|
+
|
|
40
47
|
## Delegate your first task
|
|
41
48
|
|
|
42
49
|
If Pi needs model authentication, use `/login` and select a provider. Then ask
|
|
@@ -6,25 +6,49 @@ Run Pi Herdsman as a portable SSH-accessible coding-agent environment with Pi, H
|
|
|
6
6
|
|
|
7
7
|
## Quick start
|
|
8
8
|
|
|
9
|
+
The repository includes a ready-to-use [compose.yaml](../../compose.yaml)
|
|
10
|
+
with a prebuilt image, SSH access, and persistent Docker-managed volumes.
|
|
11
|
+
You need Docker Compose and an SSH public key (for example,
|
|
12
|
+
`~/.ssh/id_ed25519.pub`).
|
|
13
|
+
|
|
14
|
+
If you cloned the repository, use its root directory. Otherwise, download
|
|
15
|
+
the Compose file into a new directory:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
mkdir -p pi-herdsman && cd pi-herdsman
|
|
19
|
+
curl -fsSLO https://raw.githubusercontent.com/boadij/pi-herdsman/main/compose.yaml
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Choose [Tailscale](#use-tailscale) or a [host bind mount](#use-a-host-bind-mount)
|
|
23
|
+
before first start if needed, to avoid changing networking or migrating data
|
|
24
|
+
later. The default named volumes require no permission setup. Optional deployments
|
|
25
|
+
record their Compose file selection in a local `.env`, so subsequent commands
|
|
26
|
+
use the same networking and storage configuration.
|
|
27
|
+
|
|
9
28
|
Start:
|
|
10
29
|
|
|
11
30
|
```sh
|
|
12
31
|
SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" docker compose up -d
|
|
13
32
|
```
|
|
14
33
|
|
|
15
|
-
Connect:
|
|
34
|
+
Connect from the Docker host:
|
|
16
35
|
|
|
17
36
|
```sh
|
|
18
|
-
ssh -p 2222 herdsman@
|
|
37
|
+
ssh -p 2222 herdsman@localhost
|
|
19
38
|
```
|
|
20
39
|
|
|
40
|
+
For a remote connection, replace `localhost` with the Docker host's name or
|
|
41
|
+
address. The default configuration publishes SSH port 2222 on the host's
|
|
42
|
+
network interfaces; restrict network access accordingly. SSH requires a
|
|
43
|
+
public key and does not permit password login.
|
|
44
|
+
|
|
21
45
|
Herdr opens automatically. Select a workspace and run:
|
|
22
46
|
|
|
23
47
|
```sh
|
|
24
48
|
pi
|
|
25
49
|
```
|
|
26
50
|
|
|
27
|
-
|
|
51
|
+
Use `/login` if Pi needs model-provider authentication.
|
|
28
52
|
|
|
29
53
|
## Add it to Herdr
|
|
30
54
|
|
|
@@ -42,39 +66,84 @@ The remote machine then appears alongside Local in Herdr.
|
|
|
42
66
|
|
|
43
67
|
## Use Tailscale
|
|
44
68
|
|
|
45
|
-
|
|
69
|
+
If you downloaded only the base Compose file, also download the
|
|
70
|
+
[Tailscale overlay](../../compose.tailscale.yaml) into the same directory:
|
|
46
71
|
|
|
47
72
|
```sh
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
73
|
+
curl -fsSLO https://raw.githubusercontent.com/boadij/pi-herdsman/main/compose.tailscale.yaml
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
In the same directory, set the selected Compose files and tailnet hostname in
|
|
77
|
+
`.env` (create it if needed):
|
|
78
|
+
|
|
79
|
+
```dotenv
|
|
80
|
+
COMPOSE_FILE=compose.yaml:compose.tailscale.yaml
|
|
81
|
+
TAILSCALE_HOSTNAME=pi-herdsman
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`COMPOSE_FILE` is a native Docker Compose setting: plain `docker compose`
|
|
85
|
+
commands now include the Tailscale overlay automatically. If you also want a
|
|
86
|
+
[bind-mounted home](#use-a-host-bind-mount), use this **single** `COMPOSE_FILE`
|
|
87
|
+
value instead:
|
|
88
|
+
|
|
89
|
+
```dotenv
|
|
90
|
+
COMPOSE_FILE=compose.yaml:compose.tailscale.yaml:compose.bind-mount.yaml
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Keep any other `.env` settings when editing it. The `:` separator applies on
|
|
94
|
+
Linux and macOS; use `;` on Windows. Shell-level `COMPOSE_FILE` and explicit
|
|
95
|
+
`-f` arguments can override this selection. Setting `COMPOSE_FILE` also
|
|
96
|
+
disables automatic `compose.override.yaml` discovery: if an existing stack
|
|
97
|
+
uses that file, either keep the default discovery behavior or include it
|
|
98
|
+
explicitly in the selected file list.
|
|
99
|
+
|
|
100
|
+
Tailscale needs `/dev/net/tun` and the networking capabilities declared in
|
|
101
|
+
the overlay. Nested containers (for example, Proxmox LXC) may require host-side
|
|
102
|
+
TUN passthrough first. Configure that on the host; Herdsman does not do it.
|
|
103
|
+
Create a non-ephemeral auth key in your Tailscale admin console. In a
|
|
104
|
+
**Bash** shell, enter the key without echoing it or including it in command
|
|
105
|
+
history (other shells need their own hidden-input equivalent):
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
printf 'Tailscale auth key: '
|
|
109
|
+
IFS= read -rs TS_AUTHKEY
|
|
110
|
+
printf '\n'
|
|
111
|
+
export TS_AUTHKEY
|
|
112
|
+
SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" docker compose up -d
|
|
54
113
|
```
|
|
55
114
|
|
|
56
|
-
|
|
115
|
+
Verify Tailscale has authenticated:
|
|
57
116
|
|
|
58
117
|
```sh
|
|
59
|
-
|
|
118
|
+
docker compose exec tailscale tailscale status
|
|
60
119
|
```
|
|
61
120
|
|
|
62
|
-
|
|
121
|
+
After successful registration, stop passing the bootstrap key and apply the
|
|
122
|
+
key-free configuration:
|
|
63
123
|
|
|
64
124
|
```sh
|
|
65
|
-
|
|
125
|
+
unset TS_AUTHKEY
|
|
126
|
+
docker compose up -d
|
|
66
127
|
```
|
|
67
128
|
|
|
68
|
-
|
|
129
|
+
The sidecar persists `/var/lib/tailscale` and uses `TS_AUTH_ONCE=true` to
|
|
130
|
+
reuse its identity on subsequent starts. If you saved `TS_AUTHKEY` in `.env`
|
|
131
|
+
instead, remove it after registration and apply the configuration again. Do
|
|
132
|
+
not share `docker compose config` output while a key is configured: it can
|
|
133
|
+
expose container environment values. The key-free recreate does not erase
|
|
134
|
+
copies of credentials previously stored outside the active container.
|
|
135
|
+
|
|
136
|
+
Connect (with Tailscale and MagicDNS working on the client):
|
|
69
137
|
|
|
70
138
|
```sh
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
139
|
+
ssh herdsman@pi-herdsman
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
For a different hostname, set `TAILSCALE_HOSTNAME` in `.env`, and connect
|
|
143
|
+
to that name. Add the machine to Herdr with:
|
|
144
|
+
|
|
145
|
+
```sh
|
|
146
|
+
herdr machine add ssh://herdsman@pi-herdsman --label my-herd
|
|
78
147
|
```
|
|
79
148
|
|
|
80
149
|
Tailscale provides networking only. SSH remains normal OpenSSH.
|
|
@@ -91,20 +160,40 @@ Run `/reload` in each affected Pi session to adopt the update; running sessions
|
|
|
91
160
|
do not adopt it automatically. No container restart is needed. If builds
|
|
92
161
|
overlap, incompatible coordination fails closed rather than proceeding.
|
|
93
162
|
|
|
94
|
-
To update the image-owned Pi and Herdr runtimes
|
|
163
|
+
To update the image-owned Pi and Herdr runtimes, finish active work first,
|
|
164
|
+
then run from the same Compose project directory:
|
|
95
165
|
|
|
96
166
|
```sh
|
|
167
|
+
docker compose config --quiet
|
|
97
168
|
docker compose pull
|
|
98
169
|
docker compose up -d
|
|
99
170
|
```
|
|
100
171
|
|
|
172
|
+
For optional deployments, the project's `.env` keeps `COMPOSE_FILE` fixed
|
|
173
|
+
across these commands. Keep that file and the selected overlays alongside
|
|
174
|
+
`compose.yaml`. Existing deployments that used explicit `-f` options should
|
|
175
|
+
first record their full selection in `.env`, or continue using **the same**
|
|
176
|
+
`-f` list for every operation. Otherwise, a base-only recreation can change
|
|
177
|
+
published ports and mounted home data. A Compose-management UI must likewise
|
|
178
|
+
use the chosen file list; do not assume it discovers custom overlays.
|
|
179
|
+
Container recreation terminates running processes.
|
|
180
|
+
|
|
101
181
|
Persistent state, including the npm-managed Herdsman version, survives container
|
|
102
182
|
replacement. A Herdsman update may require a newer image for a compatible Pi and
|
|
103
183
|
Herdr runtime.
|
|
104
184
|
|
|
105
185
|
## Use a host bind mount
|
|
106
186
|
|
|
107
|
-
The default Docker-managed volume needs no manual permission setup.
|
|
187
|
+
The default Docker-managed volume needs no manual permission setup. Configure
|
|
188
|
+
a bind mount before first start if you want to avoid later state migration.
|
|
189
|
+
The [optional bind-mount overlay](../../compose.bind-mount.yaml) replaces only
|
|
190
|
+
Herdsman's home mount; SSH host identity remains in a named volume.
|
|
191
|
+
|
|
192
|
+
If you downloaded only the base Compose file, get the overlay:
|
|
193
|
+
|
|
194
|
+
```sh
|
|
195
|
+
curl -fsSLO https://raw.githubusercontent.com/boadij/pi-herdsman/main/compose.bind-mount.yaml
|
|
196
|
+
```
|
|
108
197
|
|
|
109
198
|
For a Linux or NAS bind mount, prepare the directory for the UID/GID the
|
|
110
199
|
container will use:
|
|
@@ -118,34 +207,31 @@ sudo chown "$PUID:$PGID" ./data/herdsman-home
|
|
|
118
207
|
sudo chmod go-w ./data/herdsman-home
|
|
119
208
|
```
|
|
120
209
|
|
|
121
|
-
|
|
210
|
+
Use the same IDs and persistent file selection in the project-local `.env`:
|
|
122
211
|
|
|
123
212
|
```dotenv
|
|
124
213
|
PUID=1035
|
|
125
214
|
PGID=65537
|
|
215
|
+
COMPOSE_FILE=compose.yaml:compose.bind-mount.yaml
|
|
126
216
|
```
|
|
127
217
|
|
|
128
|
-
|
|
129
|
-
directory while keeping the SSH server identity in its named volume:
|
|
218
|
+
For Tailscale **and** a bind-mounted home, select all three files instead:
|
|
130
219
|
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
herdsman:
|
|
134
|
-
volumes:
|
|
135
|
-
- ./data/herdsman-home:/home/herdsman
|
|
136
|
-
- herdsman-ssh:/var/lib/herdsman/ssh
|
|
220
|
+
```dotenv
|
|
221
|
+
COMPOSE_FILE=compose.yaml:compose.tailscale.yaml:compose.bind-mount.yaml
|
|
137
222
|
```
|
|
138
223
|
|
|
139
|
-
|
|
224
|
+
Keep only one `COMPOSE_FILE` setting. Then start with the normal command:
|
|
140
225
|
|
|
141
226
|
```sh
|
|
142
|
-
SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)"
|
|
143
|
-
docker compose -f compose.yaml -f compose.bind-mount.yaml up -d
|
|
227
|
+
SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" docker compose up -d
|
|
144
228
|
```
|
|
145
229
|
|
|
146
230
|
OpenSSH requires the home directory to be owned by root or the login user and
|
|
147
231
|
not writable by group or others. The container validates this at startup but
|
|
148
|
-
does not change ownership or permissions of host bind mounts.
|
|
232
|
+
does not change ownership or permissions of host bind mounts. Changing from
|
|
233
|
+
an existing named volume to a bind mount is a separate data migration, not an
|
|
234
|
+
automatic conversion.
|
|
149
235
|
|
|
150
236
|
## Forward your SSH agent
|
|
151
237
|
|
|
@@ -170,7 +256,9 @@ Tools installed with mise persist in the home volume.
|
|
|
170
256
|
| `/home/herdsman` | Pi and Herdr state, repositories, config, credentials, SSH state, installed tools |
|
|
171
257
|
| `/var/lib/herdsman/ssh` | SSH server identity |
|
|
172
258
|
|
|
173
|
-
Running processes do not survive a container restart.
|
|
259
|
+
Running processes do not survive a container restart. Named volumes survive
|
|
260
|
+
`docker compose down`, but `docker compose down -v` deletes them; do not use
|
|
261
|
+
`-v` when retaining state.
|
|
174
262
|
|
|
175
263
|
Run only one active Herdsman runtime against a writable home volume. Linux
|
|
176
264
|
lock recovery verifies process identity within the current PID namespace;
|
|
@@ -124,6 +124,16 @@ overlay. A trusted project may therefore configure the Lead that works on its
|
|
|
124
124
|
branch. A Lead that is already live is not hot-reconfigured; changed launch
|
|
125
125
|
policy takes effect on its next start.
|
|
126
126
|
|
|
127
|
+
Herdsman-managed Leads inherit the Manager's effective Pi project-trust
|
|
128
|
+
decision when launched into a verified linked worktree. A trusted Manager
|
|
129
|
+
authorizes project and private-repository definitions in that worktree, even
|
|
130
|
+
if a separate saved decision for the worktree differs. An untrusted Manager
|
|
131
|
+
launches the Lead restricted. The decision applies to the managed process and
|
|
132
|
+
does not modify Pi's persistent trust store. Same-worktree delegated Agents
|
|
133
|
+
inherit their parent's effective trust. Already-running Leads are not
|
|
134
|
+
reconfigured. Trust controls configuration access; it is not an
|
|
135
|
+
operating-system sandbox.
|
|
136
|
+
|
|
127
137
|
See [`delegate_work`](../reference/staff.md#delegate_work) and
|
|
128
138
|
[`resume_work`](../reference/staff.md#resume_work).
|
|
129
139
|
|
package/docs/guides/recovery.md
CHANGED
|
@@ -29,7 +29,7 @@ For stale attention, use this decision sequence:
|
|
|
29
29
|
6. Keep waiting only while existing evidence still justifies the operation;
|
|
30
30
|
otherwise use `interrupt_agent` to abandon it and continue the same assignment.
|
|
31
31
|
Interrupt supersedes earlier undelivered steering.
|
|
32
|
-
7. Use `
|
|
32
|
+
7. Use `stop_agent` only when abandoning the assignment is intended.
|
|
33
33
|
|
|
34
34
|
Other persistent actionable conditions may repeat approximately `5m → 2m30s →
|
|
35
35
|
1m15s → 1m`; stale episodes repeat approximately every five minutes after the
|
|
@@ -174,12 +174,13 @@ unknown Agent automatically.
|
|
|
174
174
|
`lost` means the expected physical execution is proven gone before a durable
|
|
175
175
|
terminal result resolved the assignment. The durable mailbox remains owned and
|
|
176
176
|
the assignment remains unresolved; loss is not completion or task failure.
|
|
177
|
-
Only the direct owner may use `
|
|
178
|
-
`
|
|
179
|
-
|
|
177
|
+
Only the direct owner may use `stop_agent` to abandon the lost generation. When
|
|
178
|
+
`stop_agent` is listed, use it before replacing it or continuing its saved
|
|
179
|
+
session.
|
|
180
|
+
If `stop_agent` is absent, resolve the condition blocking its stop preflight first.
|
|
180
181
|
Herdsman never redelegates or continues it automatically. Moved or conflicting
|
|
181
182
|
evidence is `unknown`, not `lost`, and remains fail-closed.
|
|
182
|
-
After a verified clean
|
|
183
|
+
After a verified clean Agent stop, the direct owner may explicitly continue the exact
|
|
183
184
|
saved session. A verified `/agents stop` can also preserve a versioned receipt
|
|
184
185
|
in the owner's history for that explicit continuation. Stop never auto-restarts
|
|
185
186
|
work. Continuation starts a new generation and does not replay the abandoned
|
|
@@ -270,14 +271,14 @@ before retrying.
|
|
|
270
271
|
A later attempt should not reuse a label or resource whose ownership is still
|
|
271
272
|
uncertain.
|
|
272
273
|
|
|
273
|
-
##
|
|
274
|
+
## Agent stop failure
|
|
274
275
|
|
|
275
|
-
|
|
276
|
+
`stop_agent` targets one exact directly owned live agent or a directly
|
|
276
277
|
owned generation proven `lost` by fresh absence evidence. Unknown presence
|
|
277
278
|
fails closed.
|
|
278
279
|
|
|
279
|
-
|
|
280
|
-
agent cannot be proved or
|
|
280
|
+
Stopping a delegating agent cascades through its owned agents first. If an
|
|
281
|
+
agent cannot be proved or stopped safely, the delegating agent remains rather
|
|
281
282
|
than being destructively guessed away.
|
|
282
283
|
|
|
283
284
|
For lead-only human emergency cleanup, `/agents stop` operates on the proven
|
|
@@ -321,8 +322,8 @@ override or regenerate its saved label.
|
|
|
321
322
|
An exact session that is already represented by active or unresolved managed
|
|
322
323
|
work cannot be activated concurrently. The session-start exclusion applies to
|
|
323
324
|
the canonical session path, so an exact UUID and its exact path identify the
|
|
324
|
-
same target. Wait for the existing assignment to finish and clean up, or
|
|
325
|
-
its exact live
|
|
325
|
+
same target. Wait for the existing assignment to finish and clean up, or use
|
|
326
|
+
`stop_agent` to abandon its exact live Agent, then retry. Do not delegate another
|
|
326
327
|
task through an agent label.
|
|
327
328
|
|
|
328
329
|
## Native Pi restoration of a managed Agent
|
|
@@ -334,7 +334,7 @@ is disabled when `excludeTools` contains `agent`, when `noTools: true` unless
|
|
|
334
334
|
the explicit `tools` list contains `agent`, or when `tools` is explicitly
|
|
335
335
|
empty. Otherwise, a non-empty `agents` list enables all nine coordination
|
|
336
336
|
tools: `list_agents`, `delegate_agent`, `continue_agent`, `steer_agent`,
|
|
337
|
-
`interrupt_agent`, `reply_agent`, `
|
|
337
|
+
`interrupt_agent`, `reply_agent`, `stop_agent`, `inspect_agent`, and
|
|
338
338
|
`read_agent_transcript`. Thus omitted `tools` permits delegation, and explicit
|
|
339
339
|
ordinary tools permit it unless one of those opt-outs applies. An omitted or
|
|
340
340
|
empty `agents` list always makes the agent a leaf. Every managed agent receives
|
|
@@ -21,7 +21,7 @@ from `state` alone. `steer_agent` means active work accepts cooperative steering
|
|
|
21
21
|
`interrupt_agent` means a currently working Pi operation may be preempted,
|
|
22
22
|
superseding earlier undelivered steering with replacement direction,
|
|
23
23
|
`reply_agent` means a correlated pending `ask_owner` is valid, and
|
|
24
|
-
`
|
|
24
|
+
`stop_agent` means exact direct ownership and the current applicable stop
|
|
25
25
|
preflight permit teardown. For a
|
|
26
26
|
Lead-owned parent, that preflight includes its owned descendant cascade.
|
|
27
27
|
`available_tools` never includes `delegate_agent`; an agent generation handles one assignment only. Every operation
|
|
@@ -36,7 +36,7 @@ currently working Pi operation. Stale or inactive fields are advisory and do
|
|
|
36
36
|
not automatically authorize or recommend interrupt. Descendant visibility does not imply authority;
|
|
37
37
|
records outside the controller's direct ownership can have an empty action list.
|
|
38
38
|
Directly owned live records may expose the applicable live controls; directly
|
|
39
|
-
owned live or proven `lost` records may expose `
|
|
39
|
+
owned live or proven `lost` records may expose `stop_agent` when the applicable stop
|
|
40
40
|
preflight currently succeeds. They may also expose the read-only `read_agent_transcript`
|
|
41
41
|
action when a materialized persisted Pi session file exists. Unknown records and
|
|
42
42
|
non-direct descendants remain fail-closed with no actions.
|
|
@@ -90,8 +90,8 @@ When exact physical evidence changes, re-evaluate the record from fresh state.
|
|
|
90
90
|
|
|
91
91
|
`lost` is different: a coherent Herdr inventory proves the expected pane,
|
|
92
92
|
session, and run-scoped alias are absent. It is not completion or task failure;
|
|
93
|
-
use direct-owner `
|
|
94
|
-
applicable
|
|
93
|
+
use direct-owner `stop_agent` to abandon the unresolved generation when the
|
|
94
|
+
applicable stop preflight succeeds. Lost attention may repeat for the direct
|
|
95
95
|
owner while the assignment remains unresolved.
|
|
96
96
|
|
|
97
97
|
## Result precedence and actions
|
|
@@ -101,11 +101,11 @@ absence and projects as `settling` while delivery or recovery converges. A
|
|
|
101
101
|
failed inventory never proves `lost`; relocated or conflicting evidence is
|
|
102
102
|
`unknown`.
|
|
103
103
|
|
|
104
|
-
| Record | Direct-owner actions
|
|
105
|
-
| --------- |
|
|
106
|
-
| `live` | `inspect_agent`, eligible `read_agent_transcript`, `steer_agent`, `interrupt_agent`, `reply_agent`, and `
|
|
107
|
-
| `lost` | eligible `read_agent_transcript` and `
|
|
108
|
-
| `unknown` | None.
|
|
104
|
+
| Record | Direct-owner actions |
|
|
105
|
+
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
106
|
+
| `live` | `inspect_agent`, eligible `read_agent_transcript`, `steer_agent`, `interrupt_agent`, `reply_agent`, and `stop_agent` when the applicable stop preflight succeeds. |
|
|
107
|
+
| `lost` | eligible `read_agent_transcript` and `stop_agent` when the applicable stop preflight succeeds. |
|
|
108
|
+
| `unknown` | None. |
|
|
109
109
|
|
|
110
110
|
Owned descendants remain visible through proven durable ancestry but do not gain
|
|
111
111
|
direct control from that visibility.
|
|
@@ -120,7 +120,7 @@ do not advance `last_activity_at`. This advisory does not change the state or
|
|
|
120
120
|
prove a hang. The first stale attention is eligible after ten minutes without
|
|
121
121
|
qualifying progress; if the same condition persists, reminders may repeat at
|
|
122
122
|
approximately `5m → 2m30s → 1m15s → 1m`, subject to the 30-second health scan.
|
|
123
|
-
Leave healthy or legitimately long-running work alone. Use `read_agent_transcript` for persisted evidence and `inspect_agent` for live evidence; stale alone does not justify `interrupt_agent` or `
|
|
123
|
+
Leave healthy or legitimately long-running work alone. Use `read_agent_transcript` for persisted evidence and `inspect_agent` for live evidence; stale alone does not justify `interrupt_agent` or `stop_agent`.
|
|
124
124
|
The stale episode is defined by its active request and last qualifying activity;
|
|
125
125
|
first-attention diagnosis is bounded, and repeated reminders do not automatically
|
|
126
126
|
repeat the live capture.
|