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/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
 
@@ -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 `close_agent` while those actions are listed
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 `close_agent` only when abandoning the assignment is intended.
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
- `close_agent` or stop may preserve a versioned owner-history receipt for
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. `close_agent` is the operation that
255
- abandons the managed generation.
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
@@ -18,7 +18,7 @@ continue_agent
18
18
  steer_agent
19
19
  interrupt_agent
20
20
  reply_agent
21
- close_agent
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 without retiring its assignment, and can request
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
- `npm run format` applies formatting; `npm run format:check` verifies it without
28
- changing files. Both use the locally installed Prettier version pinned by the
29
- lockfile. `npm run check` runs the bounded behavioral test suite,
30
- `npm run validate` composes formatting verification, tests, build, and package
31
- audit, and `git diff --check` checks Git whitespace.
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. The 240-second suite deadline remains unchanged. Runner
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
@@ -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
- In your project directory, start Herdr, then Pi in its pane:
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@your-host
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
- That's it.
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
- Start with the Tailscale sidecar:
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
- TS_AUTHKEY=tskey-auth-... \
49
- SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" \
50
- docker compose \
51
- -f compose.yaml \
52
- -f compose.tailscale.yaml \
53
- up -d
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
- Connect:
115
+ Verify Tailscale has authenticated:
57
116
 
58
117
  ```sh
59
- ssh herdsman@pi-herdsman
118
+ docker compose exec tailscale tailscale status
60
119
  ```
61
120
 
62
- Add it to Herdr:
121
+ After successful registration, stop passing the bootstrap key and apply the
122
+ key-free configuration:
63
123
 
64
124
  ```sh
65
- herdr machine add ssh://herdsman@pi-herdsman --label my-herd
125
+ unset TS_AUTHKEY
126
+ docker compose up -d
66
127
  ```
67
128
 
68
- Use another hostname:
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
- TAILSCALE_HOSTNAME=my-herd \
72
- TS_AUTHKEY=tskey-auth-... \
73
- SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" \
74
- docker compose \
75
- -f compose.yaml \
76
- -f compose.tailscale.yaml \
77
- up -d
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
- Set the same IDs in `.env`:
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
- Create `compose.bind-mount.yaml` to replace the home volume with the host
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
- ```yaml
132
- services:
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
- Start with both Compose files:
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
 
@@ -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 `close_agent` only when abandoning the assignment is intended.
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 `close_agent` to abandon the lost generation. When
178
- `close_agent` is listed, use it before replacing it or continuing its saved session.
179
- If `close_agent` is absent, resolve the condition blocking its close preflight first.
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 close, the direct owner may explicitly continue the exact
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
- ## Close failure
274
+ ## Agent stop failure
274
275
 
275
- Normal `close_agent` targets one exact directly owned live agent or a directly
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
- Closing a delegating agent cascades through its owned agents first. If a
280
- agent cannot be proved or closed safely, the delegating agent remains rather
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 close
325
- its exact live agent when abandoning it, then retry. Do not delegate another
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`, `close_agent`, `inspect_agent`, and
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
- `close_agent` means exact direct ownership and the current applicable close
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 `close_agent` when the applicable close
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 `close_agent` to abandon the unresolved generation when the
94
- applicable close preflight succeeds. Lost attention may repeat for the direct
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 `close_agent` when the applicable close preflight succeeds. |
107
- | `lost` | eligible `read_agent_transcript` and `close_agent` when the applicable close preflight succeeds. |
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 `close_agent`.
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.