pi-herdsman 0.1.4 → 0.2.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.
@@ -1,8 +1,8 @@
1
- # `worker` API
1
+ # `agent` API
2
2
 
3
3
  [Documentation index](../README.md) · [supervision reference](supervision.md)
4
4
 
5
- `worker` is the structured model-facing API for managed workers. It has exactly six actions:
5
+ `agent` is the structured model-facing API for managed agents. It has exactly six actions:
6
6
 
7
7
  ```text
8
8
  list
@@ -14,7 +14,7 @@ inspect
14
14
  ```
15
15
 
16
16
  Unknown fields and unsupported selector combinations fail with `invalid_request`.
17
- The tool is registered only for the lead controller and authorized delegating worker
17
+ The tool is registered only for the lead controller and authorized delegating agent
18
18
  controllers.
19
19
 
20
20
  ## `delegate`
@@ -35,12 +35,12 @@ Every variant rejects additional properties.
35
35
 
36
36
  Allowed fields are `action`, `definition`, `task`, optional `label`, `cwd`,
37
37
  `files`, `fork`, and `timeoutMs`. The definition is resolved from
38
- the effective roster and delegating worker controllers may use only their allowlisted
38
+ the effective roster and delegating agent controllers may use only their allowlisted
39
39
  definitions. Project definitions still require trusted project approval.
40
40
  `fork`, when supplied, is an exact saved Pi session path or full UUID used as
41
41
  the source for a new derived context; otherwise a new Pi session is launched.
42
- Each accepted definition delegation creates one worker generation for one
43
- assignment. The terminal result is delivered once and the worker is cleaned up.
42
+ Each accepted definition delegation creates one agent generation for one
43
+ assignment. The terminal result is delivered once and the agent is cleaned up.
44
44
 
45
45
  ### Session
46
46
 
@@ -52,19 +52,26 @@ assignment. The terminal result is delivered once and the worker is cleaned up.
52
52
  }
53
53
  ```
54
54
 
55
- Allowed fields are `action`, `session`, `task`, optional `files`, and
55
+ Allowed fields are `action`, `session`, `task`, optional `label`, `files`, and
56
56
  `timeoutMs`. The exact saved session supplies its cwd, definition identity, and
57
- historical Pi context. Session delegation always creates a new worker generation
58
- for one assignment; it never assigns work to an existing worker. The saved
59
- definition must currently resolve to an enabled, authorized effective
60
- definition, whose current configuration is used for the new generation.
57
+ historical Pi context. Session delegation always creates a new agent generation
58
+ for one assignment with a live label; it never assigns work to an existing
59
+ agent. The saved definition must currently resolve to an enabled, authorized
60
+ effective definition, whose current configuration is used for the new
61
+ generation.
61
62
  Concurrent or otherwise conflicting managed representations of the exact
62
63
  session fail closed. The controller's own active Pi session cannot be delegated
63
64
  to itself; use definition delegation with `fork` when a separate derived
64
65
  context is required.
65
66
 
67
+ `label` is optional on both delegation variants and identifies the live
68
+ generation, not the continuation session. When omitted, Herdsman chooses a
69
+ fresh available label derived from the effective agent definition. An explicit
70
+ label is used exactly as the live label; if that label is occupied, delegation
71
+ fails with `agent_label_exists`.
72
+
66
73
  All successful delegation results use `action: "delegate"` and include
67
- `worker`, `definition`, request, session, and startup evidence where available.
74
+ `agent`, `definition`, request, session, and startup evidence where available.
68
75
  Delegation returns after durable acceptance, not completion. A terminal result
69
76
  also makes the exact session identity prominent so it can be used with a later
70
77
  `delegate.session` call.
@@ -78,54 +85,63 @@ Request:
78
85
  ```
79
86
 
80
87
  No selectors or other fields are accepted. A successful result includes the
81
- effective `agent_definitions` roster and visible worker records.
82
-
83
- Each actionable live worker record includes:
84
-
85
- | Field | Meaning |
86
- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
87
- | `worker` | Exact live logical worker identity to copy into `steer.worker`, `reply.worker`, or `close.worker`. It is not a continuation identity. |
88
- | `state` | Safe lifecycle state for observability. |
89
- | `available_actions` | Snapshot of operations currently eligible for this controller. |
90
- | `workspace_id`, `pane_id`, `tab_id`, `tab_label` | Herdr identity evidence. |
91
- | `cwd`, `pi_session_id`, `pi_session_path` | Worker location and Pi session evidence. |
92
- | `owner_session_id` | Exact direct owner Pi session. |
93
- | `agent_definition` | Effective definition name. |
94
- | `active_request_id`, `last_activity_at`, `stale`, `inactive_ms` | Assignment and advisory activity evidence. |
95
- | `parent_label`, `orphan` | Visible direct-owner ancestry and proven orphan recovery evidence. |
96
- | `cleanup_error`, `result_error`, `diagnostic`, `tokens` | Bounded recovery and presentation evidence when present. |
88
+ effective `agent_definitions` roster and visible agent records.
89
+
90
+ Each actionable live agent record includes:
91
+
92
+ | Field | Meaning |
93
+ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
94
+ | `agent` | Exact live logical agent identity to copy into `steer.agent`, `reply.agent`, or `close.agent`. It is not a continuation identity. |
95
+ | `state` | Safe lifecycle state for observability. |
96
+ | `available_actions` | Snapshot of operations currently eligible for this controller. |
97
+ | `workspace_id`, `pane_id`, `tab_id`, `tab_label` | Herdr identity evidence. |
98
+ | `cwd`, `pi_session_id`, `pi_session_path` | Agent location and Pi session evidence. |
99
+ | `owner_session_id` | Exact direct owner Pi session. |
100
+ | `agent_definition` | Effective definition name. |
101
+ | `active_request_id`, `last_activity_at`, `stale`, `inactive_ms` | Assignment and advisory activity evidence. |
102
+ | `parent_label`, `orphan` | Visible direct-owner ancestry and proven orphan recovery evidence. |
103
+ | `cleanup_error`, `result_error`, `diagnostic`, `tokens` | Bounded recovery and presentation evidence when present. |
97
104
 
98
105
  `available_actions` is authoritative model guidance for the current snapshot.
99
106
  Do not infer eligibility from `state`. Active work may list `steer`; a valid
100
107
  correlated pending `ask_owner` may list `reply`; exact direct ownership may list
101
- `close`. `available_actions` never lists `delegate`: a worker cannot receive a
108
+ `close`. `available_actions` never lists `delegate`: an agent cannot receive a
102
109
  second assignment. Descendant visibility does not grant control. Lead orphan
103
110
  recovery may expose only `close`. Unknown and recovery-only records are
104
111
  non-actionable. Every operation rechecks identity, ownership, mailbox state, and
105
112
  lifecycle immediately before mutation.
106
113
  The public record does not expose `steerable`.
107
114
 
108
- Lead controllers see the complete effective definition roster and workers visible
109
- through their ownership boundary. Delegating workers see only allowed enabled
110
- leaf definitions and their visible workers. Unknown mailbox diagnostics remain
115
+ The session-start instructions include the same complete definition metadata
116
+ projection returned by `list` for that controller. It is a startup snapshot;
117
+ use `list` for live agent state, ownership, or a refreshed definition roster
118
+ after configuration changes. Leaf agents do not receive a definition roster.
119
+
120
+ Lead controllers see the complete effective definition roster and agents visible
121
+ through their ownership boundary. Delegating agents see only allowed enabled
122
+ leaf definitions and their visible agents. Unknown mailbox diagnostics remain
111
123
  non-actionable.
112
124
 
113
125
  ## `inspect`
114
126
 
115
127
  ```json
116
- { "action": "inspect", "worker": "implementer-1" }
128
+ { "action": "inspect", "agent": "implementer-1" }
117
129
  ```
118
130
 
119
- `inspect` accepts only `action` and the exact live worker label. It is available
120
- only to that worker's direct owner, and only when the worker is a current,
121
- unambiguous managed identity. The result is read-only and contains the exact
122
- session/pane identity, a bounded tail of the most recent 40 unwrapped terminal
123
- lines (at most 8 KiB), and advisory foreground process evidence when available.
124
- Its model-facing text includes the worker, session, pane, useful foreground
125
- commands, and recent activity; raw process and recent-output evidence remains
126
- in the structured result details.
131
+ `inspect` accepts only `action` and the exact live agent label. It is available
132
+ only to that agent's direct owner, and only when the agent is a current,
133
+ unambiguous managed identity. The result is read-only live terminal/process
134
+ evidence only: it contains the exact session/pane identity, Herdr's up to 80
135
+ recent-unwrapped terminal lines, and advisory foreground process evidence when
136
+ available. Herdsman applies a local 16 KiB byte cap to the captured terminal
137
+ output. The public `recent_output_truncated` boolean is true only when that
138
+ local byte cap truncates the output and false otherwise; process evidence has
139
+ separate bounds. The result does not expose persisted Pi session-message
140
+ history. Its model-facing text includes the agent, session, pane, useful
141
+ foreground commands, and recent activity; raw process and recent-output
142
+ evidence remains in the structured result details.
127
143
  The identity is checked again after capture; if the pane or Pi session was
128
- replaced, inspection fails closed. Inspection does not change worker state,
144
+ replaced, inspection fails closed. Inspection does not change agent state,
129
145
  mailbox records, lifecycle, or available controls.
130
146
 
131
147
  ## `files` and `timeoutMs`
@@ -137,17 +153,26 @@ when the exact message limit permits. Otherwise they remain canonical references
137
153
 
138
154
  `timeoutMs` is valid on definition and session delegation and must be an integer
139
155
  from `5001` through `300000`. The startup budget reserves one bounded diagnostic
140
- window. Current message limits are governed by effective global/project/default
156
+ window. Current message limits are governed by global/default
141
157
  settings and the fixed mailbox protocol ceiling. Managed mailbox records use
142
- protocol version 3, and control requests use the marker prefix
143
- `__PI_HERDSMAN_WORKER_V3__:`.
158
+ protocol V4 in the `mailboxes-v4` namespace, and control requests use the marker prefix
159
+ `__PI_HERDSMAN_AGENT_V4__:`.
160
+
161
+ Do not attach or mention agent instruction files such as `AGENTS.md`, `CLAUDE.md`,
162
+ `GEMINI.md`, or equivalents merely because they exist. Rely on normal project or
163
+ runtime discovery. Attach one only when the task requires inspecting,
164
+ modifying, comparing, or transmitting it, the user requests it, or its required
165
+ instructions would not otherwise reach the target. Attach a required `SKILL.md`
166
+ only when the task needs it and the selected definition does not already provide
167
+ that skill. Ordinary relevant source, documentation, configuration, and
168
+ evidence files remain attachable.
144
169
 
145
170
  ## `steer`
146
171
 
147
172
  ```json
148
173
  {
149
174
  "action": "steer",
150
- "worker": "implementer-1",
175
+ "agent": "implementer-1",
151
176
  "message": "Also update the focused regression.",
152
177
  "files": [".pi-herdsman/review.md"]
153
178
  }
@@ -161,7 +186,7 @@ current assignment and does not create another final result.
161
186
  ```json
162
187
  {
163
188
  "action": "reply",
164
- "worker": "implementer-1",
189
+ "agent": "implementer-1",
165
190
  "message": "Use option B."
166
191
  }
167
192
  ```
@@ -175,13 +200,13 @@ See [`ask_owner` API](ask-owner.md).
175
200
  ## `close`
176
201
 
177
202
  ```json
178
- { "action": "close", "worker": "implementer-1" }
203
+ { "action": "close", "agent": "implementer-1" }
179
204
  ```
180
205
 
181
- Only `action` and `worker` are accepted. Close requires exact direct ownership,
206
+ Only `action` and `agent` are accepted. Close requires exact direct ownership,
182
207
  or the lead-only evidence-backed orphan recovery condition. Closing abandons a
183
- pending owner question; closing a delegating worker cascades through directly
184
- owned workers first. Cleanup remains fail-closed when exact identity or ownership
208
+ pending owner question; closing a delegating agent cascades through directly
209
+ owned agents first. Cleanup remains fail-closed when exact identity or ownership
185
210
  cannot be proved.
186
211
 
187
212
  ## Result delivery and errors
@@ -189,13 +214,13 @@ cannot be proved.
189
214
  An accepted delegated task remains the internal mailbox `kind: "task"` request
190
215
  and has one correlated final result. Delivery goes to the exact owning Pi
191
216
  session and occurs exactly once. Model-visible completion wording uses
192
- `worker=<worker>`, `definition=<definition>`, `session=<id>`,
193
- `request=<id>`, and status. Details retain durable `workerLabel`,
217
+ `agent=<agent>`, `definition=<definition>`, `session=<id>`,
218
+ `request=<id>`, and status. Details retain durable `agentLabel`,
194
219
  `agentDefinition`, `piSessionId`, `piSessionFile`, result paths, elapsed time,
195
- context usage, truncation, and persistence-error evidence. The worker is cleaned
220
+ context usage, truncation, and persistence-error evidence. The agent is cleaned
196
221
  up after the terminal result is delivered; the Pi session remains available for
197
222
  continuation.
198
223
 
199
224
  Tool failures return structured details for normal public errors. See
200
- [Errors](errors.md), [worker states](worker-states.md), and
201
- [workers and identity](../concepts/workers.md).
225
+ [Errors](errors.md), [agent states](agent-states.md), and
226
+ [agents and identity](../concepts/agents.md).
@@ -2,14 +2,14 @@
2
2
 
3
3
  [Documentation index](../README.md)
4
4
 
5
- `ask_owner` is mandatory managed-worker infrastructure for one direct-owner
5
+ `ask_owner` is mandatory managed agent infrastructure for one direct-owner
6
6
  decision required to continue the current assignment.
7
7
 
8
8
  It is not a generic messaging channel.
9
9
 
10
10
  ## Availability
11
11
 
12
- Every valid managed worker receives the `ask_owner` tool at launch.
12
+ Every valid managed agent receives the `ask_owner` tool at launch.
13
13
 
14
14
  Normal definition `tools`, `excludeTools`, and `noTools` policy cannot remove
15
15
  this infrastructure capability.
@@ -24,42 +24,42 @@ this infrastructure capability.
24
24
  ```
25
25
 
26
26
  `question` must contain non-whitespace text.
27
- `files` supplies supporting evidence using the same rules as `worker`: complete
27
+ `files` supplies supporting evidence using the same rules as `agent`: complete
28
28
  strict UTF-8 text may be embedded, while other files are canonical local
29
- references and are not copied or snapshotted. Relative paths use the worker's
29
+ references and are not copied or snapshotted. Relative paths use the agent's
30
30
  working directory. This does not weaken the sole-final-tool-call rule.
31
31
 
32
32
  ## Turn rule
33
33
 
34
34
  `ask_owner` must be:
35
35
 
36
- - the worker's only tool call in the turn;
36
+ - the agent's only tool call in the turn;
37
37
  - the final tool call of the turn.
38
38
 
39
- The worker then stops and waits.
39
+ The agent then stops and waits.
40
40
 
41
41
  A call made alongside another tool call is rejected.
42
42
 
43
43
  ## Eligibility
44
44
 
45
- A worker can ask only while it has a valid active assignment and:
45
+ An agent can ask only while it has a valid active assignment and:
46
46
 
47
47
  - has no outstanding ask;
48
48
  - has no completed/final result pending;
49
49
  - has no pending state transition;
50
50
  - has no unacknowledged owner request;
51
- - has no ordinary unresolved direct-worker work.
51
+ - has no ordinary unresolved direct-agent work.
52
52
 
53
- A delegation-enabled worker may ask its own owner when its unresolved direct
54
- workers are themselves validly blocked on owner questions. Ordinary active
55
- workers and pending worker results still block escalation.
53
+ A delegation-enabled agent may ask its own owner when its unresolved direct
54
+ agents are themselves validly blocked on owner questions. Ordinary active
55
+ agents and pending agent results still block escalation.
56
56
 
57
57
  ## Durable effect
58
58
 
59
59
  On acceptance, Pi Herdsman creates one correlated ask record and sets
60
60
  `pendingAskId` while preserving the original active assignment request ID.
61
61
 
62
- The tool result tells the worker that the assignment is blocked and returns
62
+ The tool result tells the agent that the assignment is blocked and returns
63
63
  details containing:
64
64
 
65
65
  ```text
@@ -67,7 +67,7 @@ askId
67
67
  assignmentRequestId
68
68
  ```
69
69
 
70
- The worker public state projects as `blocked` after the turn settles.
70
+ The agent public state projects as `blocked` after the turn settles.
71
71
 
72
72
  Final assignment settlement is disabled while the ask remains pending.
73
73
 
@@ -76,20 +76,20 @@ Final assignment settlement is disabled while the ask remains pending.
76
76
  The exact direct owner receives the question through the existing owner-session
77
77
  delivery path.
78
78
 
79
- The system does not automatically forward a worker question through an ownership
79
+ The system does not automatically forward an agent question through an ownership
80
80
  chain.
81
81
 
82
- If a delegating worker needs a lead decision, it independently calls `ask_owner`
82
+ If a delegating agent needs a lead decision, it independently calls `ask_owner`
83
83
  on its own direct ownership edge.
84
84
 
85
85
  ## Reply
86
86
 
87
- The direct owner answers through the `worker` tool:
87
+ The direct owner answers through the `agent` tool:
88
88
 
89
89
  ```json
90
90
  {
91
91
  "action": "reply",
92
- "worker": "<exact worker>",
92
+ "agent": "<exact agent>",
93
93
  "message": "Use option B."
94
94
  }
95
95
  ```
@@ -101,13 +101,13 @@ The reply is correlated to:
101
101
  - run ID;
102
102
  - owner session;
103
103
  - workspace;
104
- - worker label;
104
+ - agent label;
105
105
  - pane;
106
106
  - Pi session.
107
107
 
108
108
  A mismatched or stale reply fails closed.
109
109
 
110
- The worker clears the pending ask, acknowledges the reply request, and resumes
110
+ The agent clears the pending ask, acknowledges the reply request, and resumes
111
111
  the same assignment with the owner answer.
112
112
 
113
113
  ## One outstanding question
@@ -116,18 +116,18 @@ Only one `ask_owner` question may be outstanding per assignment at a time.
116
116
 
117
117
  There is no ask timeout.
118
118
 
119
- The worker must not guess the owner answer and complete while blocked.
119
+ The agent must not guess the owner answer and complete while blocked.
120
120
 
121
121
  Rejected calls identify the known eligibility reason, such as no active
122
122
  assignment, an existing owner question, settling state, a pending control
123
- request, or active direct-worker work.
123
+ request, or active direct-agent work.
124
124
 
125
125
  ## Close
126
126
 
127
- Closing the worker abandons the pending question as part of worker teardown.
127
+ Closing the agent abandons the pending question as part of agent teardown.
128
128
 
129
129
  ## See also
130
130
 
131
- - [`worker` `reply`](worker.md#reply)
131
+ - [`agent` `reply`](agent.md#reply)
132
132
  - [Lifecycle](../concepts/lifecycle.md)
133
133
  - [Delegation](../concepts/delegation.md)
@@ -1,29 +1,30 @@
1
- # `/workers` commands
1
+ # `/agents` commands
2
2
 
3
3
  [Documentation index](../README.md)
4
4
 
5
- `/workers` is the human-facing worker-management command namespace.
5
+ `/agents` is the human-facing agent-management command namespace.
6
6
 
7
- It is separate from the structured model-facing `worker` API.
7
+ It is separate from the structured model-facing `agent` API.
8
8
 
9
9
  Commands require a lead Pi session with UI.
10
10
 
11
11
  ## Usage
12
12
 
13
13
  ```text
14
- /workers
15
- /workers agents
16
- /workers placement [tab|split]
17
- /workers stop
14
+ /agents
15
+ /agents definitions
16
+ /agents placement [tab|split]
17
+ /agents stop
18
18
  ```
19
19
 
20
20
  The plain command opens a native Pi selection menu with `Running`,
21
21
  `Definitions`, `Layout`, `Message limits`, and `Stop all…` destinations. The
22
- Message limits view edits the independent inline attachment and mailbox
23
- payload limits at global or trusted-project scope. It is available only to a
24
- lead Pi session with UI.
22
+ Message limits view edits the independent global inline attachment and mailbox
23
+ payload limits. It is available only to a lead Pi session with UI. Current
24
+ values and presets show a rough token equivalent using four UTF-8 bytes per
25
+ token. The enforced limits are bytes, not tokens.
25
26
 
26
- ## `/workers agents`
27
+ ## `/agents definitions`
27
28
 
28
29
  Opens the native Definitions menu for the effective bundled, project, and
29
30
  global roster. Project definitions are included only when the trusted project
@@ -44,10 +45,10 @@ The details view can show:
44
45
 
45
46
  Bundled implementation paths are intentionally hidden from the human overview.
46
47
 
47
- Structured `worker list` keeps exact deterministic metadata, including exact
48
+ Structured `agent list` keeps exact deterministic metadata, including exact
48
49
  source and skill paths when available.
49
50
 
50
- `/workers agents` does not probe runtime tool availability.
51
+ `/agents definitions` does not probe runtime tool availability.
51
52
 
52
53
  Selecting a definition opens:
53
54
 
@@ -73,49 +74,53 @@ The command edits only the selected top-level `model`, `thinking`, or `enabled`
73
74
  line in the global Markdown override. It preserves unrelated frontmatter and
74
75
  the complete body.
75
76
 
77
+ Details re-resolves the selected definition when opened, so it reflects current
78
+ overlays and body references even if the menu remained open while configuration
79
+ changed.
80
+
76
81
  Changes apply to future definition delegations and session continuations, not
77
- already-running workers or the lead Pi session.
82
+ already-running agents or the lead Pi session.
78
83
 
79
84
  Standalone global definitions are editable too. Removing a field from one uses
80
85
  Pi's normal default; removing a field from a bundled override restores the
81
86
  bundled value.
82
87
 
83
- ## `/workers` Running
88
+ ## `/agents` Running
84
89
 
85
90
  Select a live managed agent from the shared status projection to focus its pane.
86
91
  Pi Herdsman refreshes and verifies the exact label, pane, and session identity
87
- before issuing herdr's focus command. If the worker changed, no focus command
92
+ before issuing herdr's focus command. If the agent changed, no focus command
88
93
  is sent.
89
94
 
90
- ## `/workers placement`
95
+ ## `/agents placement`
91
96
 
92
97
  Selecting Layout opens a native selector showing the effective setting.
93
98
  Explicit values continue to set directly:
94
99
 
95
100
  ```text
96
- /workers placement tab
97
- /workers placement split
101
+ /agents placement tab
102
+ /agents placement split
98
103
  ```
99
104
 
100
105
  See [Configuration](configuration.md).
101
106
 
102
- ## `/workers stop`
107
+ ## `/agents stop`
103
108
 
104
109
  Destructive lead-only emergency control.
105
110
 
106
111
  It aborts the current lead turn and attempts to close the exactly proven owned
107
- worker tree.
112
+ agent tree.
108
113
 
109
114
  It reports discarded active work or durable pending results when present.
110
115
 
111
116
  Cleanup uses existing exact ownership proofs and proceeds conservatively across
112
117
  independent failures.
113
118
 
114
- Use ordinary `worker close` for normal targeted model-driven control.
119
+ Use ordinary `agent close` for normal targeted model-driven control.
115
120
 
116
121
  ## See also
117
122
 
118
123
  - [`/chief` and chief mode](supervision.md)
119
- - [`worker` API](worker.md)
124
+ - [`agent` API](agent.md)
120
125
  - [Configuration](configuration.md)
121
126
  - [Status widget](status-widget.md)
@@ -5,9 +5,9 @@
5
5
  Pi Herdsman intentionally has very little settings state.
6
6
 
7
7
  Agent behavior lives in Markdown definitions. The extension settings currently
8
- own worker placement.
8
+ own agent placement.
9
9
 
10
- ## Worker placement
10
+ ## Agent placement
11
11
 
12
12
  Settings shape:
13
13
 
@@ -32,12 +32,12 @@ Default:
32
32
  tab
33
33
  ```
34
34
 
35
- `tab` places future workers in the managed worker-tab workflow.
35
+ `tab` places future agents in the managed agent-tab workflow.
36
36
 
37
- `split` places future workers by splitting from the caller's tab/pane placement
37
+ `split` places future agents by splitting from the caller's tab/pane placement
38
38
  boundary.
39
39
 
40
- This affects future starts, not existing workers.
40
+ This affects future starts, not existing agents.
41
41
 
42
42
  ## Message limits
43
43
 
@@ -56,13 +56,16 @@ Each accepts an integer from 1024 bytes (1 KiB) through 1048576 bytes (1 MiB)
56
56
  and defaults to 131072 bytes (128 KiB). The inline limit applies per file;
57
57
  eligible complete strict UTF-8 files are embedded in caller order only when
58
58
  the exact serialized mailbox record fits. Other files remain canonical
59
- references. The mailbox limit is the exact serialized `RequestRecord` or
60
- `AskRecord` admission size.
59
+ references. The mailbox limit is the exact serialized `RequestRecord`,
60
+ `AskRecord`, or text-only chief supervision record admission size. Chief
61
+ supervision also has an existing fixed 8 KiB record ceiling, so its effective
62
+ admission limit is the smaller of the configured mailbox limit and 8 KiB.
61
63
 
62
- Valid trusted project values override valid global values. Invalid values are
63
- ignored rather than clamped. Configure these values through `/workers` →
64
- `Message limits`; the fixed 1 MiB protocol safety ceiling remains in force for
65
- reading existing mailbox records.
64
+ Only valid global values affect runtime behavior. Invalid global values are
65
+ ignored rather than clamped, and project-local values for these two keys are
66
+ inert. Configure the global values through `/agents` → `Message limits`; the
67
+ fixed 1 MiB protocol safety ceiling remains in force for reading existing
68
+ mailbox records.
66
69
 
67
70
  ## Settings scope
68
71
 
@@ -84,7 +87,7 @@ A project placement value is effective only when:
84
87
 
85
88
  If no valid trusted project placement is active, the global value is used.
86
89
 
87
- `/workers placement` opens a native selector showing the effective value and
90
+ `/agents placement` opens a native selector showing the effective value and
88
91
  offering `tab` or `split`. Selecting a value writes to the current effective
89
92
  scope and verifies the value after writing; the confirmation reports whether
90
93
  that scope is `project` or `global`.
@@ -126,5 +129,5 @@ identity/restore behavior.
126
129
 
127
130
  ## See also
128
131
 
129
- - [`/workers` commands](commands.md)
132
+ - [`/agents` commands](commands.md)
130
133
  - [Getting started](../getting-started.md)
@@ -2,7 +2,7 @@
2
2
 
3
3
  [Documentation index](../README.md)
4
4
 
5
- Normal public `worker` failures use structured error details.
5
+ Normal public `agent` failures use structured error details.
6
6
 
7
7
  ## Shape
8
8
 
@@ -38,12 +38,12 @@ must not be presented as exhausted cleanup.
38
38
  | Category | Meaning |
39
39
  | -------------------------- | ----------------------------------------------------------------------------------- |
40
40
  | `not_running_inside_herdr` | Required herdr environment is missing. |
41
- | `worker_label_exists` | Requested/generated live label conflicts with an existing worker. |
42
- | `pane_not_ready` | Worker pane/startup did not reach the required readiness boundary. |
41
+ | `agent_label_exists` | Requested/generated live label conflicts with an existing agent. |
42
+ | `pane_not_ready` | Agent pane/startup did not reach the required readiness boundary. |
43
43
  | `target_not_found` | Exact requested identity or ownership evidence was not found. |
44
44
  | `target_ambiguous` | More than one live candidate matched an identity that must be exact. |
45
45
  | `rollback_failure` | Primary operation failed and cleanup did not fully converge. |
46
- | `worker_busy` | Worker state does not allow the requested control action. |
46
+ | `agent_busy` | Agent state does not allow the requested control action. |
47
47
  | `invalid_request` | Request fields, values, definition input, file input, or preconditions are invalid. |
48
48
  | `internal_failure` | An invariant or underlying operation failed outside a narrower public category. |
49
49
 
@@ -58,7 +58,7 @@ Both are fail-closed behavior.
58
58
 
59
59
  ## Rollback
60
60
 
61
- When a worker launch fails, exact resources created by that attempt are cleaned
61
+ When an agent launch fails, exact resources created by that attempt are cleaned
62
62
  only when ownership is proved.
63
63
 
64
64
  A `rollback_failure` can preserve:
@@ -84,4 +84,4 @@ This is output presentation behavior, not an error category.
84
84
  ## See also
85
85
 
86
86
  - [Recovery](../guides/recovery.md)
87
- - [`worker` API](worker.md)
87
+ - [`agent` API](agent.md)