pi-herdsman 0.1.4 → 0.2.0

package/docs/README.md

@@ -4,7 +4,7 @@
 
 This directory is the canonical product documentation for `pi-herdsman`.
 
-Pi Herdsman is built around asynchronous orchestration: managed workers can continue
+Pi Herdsman is built around asynchronous orchestration: managed agents can continue
 independently while the lead Pi session remains the user's interactive session.
 The exact lifecycle semantics live on [Lifecycle](concepts/lifecycle.md).
 
@@ -25,7 +25,7 @@ without reading the structured model-facing API first.
 
 Continue with:
 
-- [`/workers` commands](reference/commands.md)
+- [`/agents` commands](reference/commands.md)
 - [Status widget](reference/status-widget.md)
 - [Configuration](reference/configuration.md)
 - [Agent definitions](guides/agent-definitions.md)
@@ -38,18 +38,18 @@ Continue with:
 Start with [Agent coordination API](agent-api.md).
 
 This path is for model and agent coordination behavior: non-blocking assignment,
-exact worker identity, lifecycle, delegation, owner clarification, handoffs, and
+exact agent identity, lifecycle, delegation, owner clarification, handoffs, and
 failure handling.
 
 Continue with:
 
-- [`worker` API](reference/worker.md)
+- [`agent` API](reference/agent.md)
 - [`ask_owner` API](reference/ask-owner.md)
-- [Workers and identity](concepts/workers.md)
+- [Agents and identity](concepts/agents.md)
 - [Lifecycle](concepts/lifecycle.md)
 - [Delegation](concepts/delegation.md)
 - [Handoffs and files](guides/handoffs.md)
-- [Worker states](reference/worker-states.md)
+- [Agent states](reference/agent-states.md)
 - [Errors](reference/errors.md)
 
 For chief supervision of independent leads, read [Supervision](concepts/supervision.md)
@@ -75,22 +75,22 @@ before choosing the material relevant to them.
 | Human UI first use                    | [Getting started](getting-started.md)                           |
 | Agent/API first use                   | [Agent coordination API](agent-api.md)                          |
 | Asynchronous orchestration            | [Lifecycle](concepts/lifecycle.md)                              |
-| Worker identity                       | [Workers and identity](concepts/workers.md)                     |
+| Agent identity                        | [Agents and identity](concepts/agents.md)                       |
 | State transitions                     | [Lifecycle](concepts/lifecycle.md)                              |
 | Delegation model                      | [Delegation](concepts/delegation.md)                            |
 | Creating definitions                  | [Agent definitions](guides/agent-definitions.md)                |
 | Overrides and prompt composition      | [Customizing bundled agents](guides/customizing-agents.md)      |
 | `files`, body references, and results | [Handoffs and files](guides/handoffs.md)                        |
 | Operator recovery                     | [Recovery](guides/recovery.md)                                  |
-| `worker` request contract             | [`worker` API](reference/worker.md)                             |
+| `agent` request contract              | [`agent` API](reference/agent.md)                               |
 | `ask_owner` contract                  | [`ask_owner` API](reference/ask-owner.md)                       |
 | Pi Herdsman supervision concept       | [Supervision](concepts/supervision.md)                          |
 | Chief and staff tools                 | [Supervision reference](reference/supervision.md)               |
 | Frontmatter fields                    | [Agent-definition schema](reference/agent-definition-schema.md) |
-| Public worker states                  | [Worker states](reference/worker-states.md)                     |
-| `/workers` human commands             | [`/workers` commands](reference/commands.md)                    |
+| Public agent states                   | [Agent states](reference/agent-states.md)                       |
+| `/agents` human commands              | [`/agents` commands](reference/commands.md)                     |
 | Settings                              | [Configuration](reference/configuration.md)                     |
-| TUI worker widget                     | [Status widget](reference/status-widget.md)                     |
+| TUI agent widget                      | [Status widget](reference/status-widget.md)                     |
 | Error categories                      | [Errors](reference/errors.md)                                   |
 | Repository checks                     | [Validation](development/validation.md)                         |
 | Live acceptance                       | [Smoke testing](development/smoke-testing.md)                   |

package/docs/agent-api.md

@@ -25,14 +25,14 @@ must run inside [herdr](https://github.com/herdrdev/herdr).
 
 ## First use
 
-The exact controller contract is the [`worker` API](reference/worker.md).
-Start by inspecting the current roster and authoritative visible workers:
+The exact controller contract is the [`agent` API](reference/agent.md).
+Start by inspecting the current roster and authoritative visible agents:
 
 ```json
 { "action": "list" }
 ```
 
-Then delegate to a fresh worker by definition:
+Then delegate to a fresh agent by definition:
 
 ```json
 {
@@ -42,45 +42,45 @@ Then delegate to a fresh worker by definition:
 }
 ```
 
-`delegate` is non-blocking orchestration. It returns after the worker has accepted
-the assignment, not when the worker finishes.
+`delegate` is non-blocking orchestration. It returns after the agent has accepted
+the assignment, not when the agent finishes.
 
 The owner remains free to make useful progress, coordinate other independent
-work, or end its turn normally. It must not poll the worker. Completion or an
+work, or end its turn normally. It must not poll the agent. Completion or an
 `ask_owner` question is delivered back to the exact owner asynchronously.
 
 The detailed lifecycle contract, including result delivery, one-assignment
-cleanup, blocked work, settling, and delegating-worker completion, is owned by
+cleanup, blocked work, settling, and delegating-agent completion, is owned by
 [Lifecycle](concepts/lifecycle.md).
 
 The examples above establish the first-use path only. Use the
-[`worker` API](reference/worker.md) for exact accepted fields, validation,
+[`agent` API](reference/agent.md) for exact accepted fields, validation,
 control eligibility, session continuation, fork behavior, and return shapes.
 
-## Understand worker identity
+## Understand agent identity
 
-Read [Workers and identity](concepts/workers.md) for the identity model behind
-controller operations. The logical worker identity is exposed as `worker` for
+Read [Agents and identity](concepts/agents.md) for the identity model behind
+controller operations. The logical agent identity is exposed as `agent` for
 live control; physical herdr and Pi identifiers are validation evidence.
 
 For the exact public state vocabulary, see
-[Worker states](reference/worker-states.md).
+[Agent states](reference/agent-states.md).
 
 ## Delegate deliberately
 
-Read [Delegation](concepts/delegation.md) for lead and delegating-worker
+Read [Delegation](concepts/delegation.md) for lead and delegating-agent
 ownership and delegation limits.
 
-A worker that genuinely needs an owner decision uses the separate
+An agent that genuinely needs an owner decision uses the separate
 [`ask_owner` API](reference/ask-owner.md). The exact owner answers through the
-controller's `reply` action; ordinary active worker work is not an owner
+controller's `reply` action; ordinary active agent work is not an owner
 question.
 
 ## Pass evidence through handoffs
 
 Read [Handoffs and files](guides/handoffs.md) for `files`, result paths, body
 references, and coordination artifacts. That guide owns the evidence-transfer
-workflow; the `worker` reference owns the accepted request fields.
+workflow; the `agent` reference owns the accepted request fields.
 
 ## Handle failures conservatively
 
@@ -91,11 +91,11 @@ observations.
 
 ## Human UI is a separate surface
 
-The lead TUI exposes `/workers`, the status widget, definition
+The lead TUI exposes `/agents`, the status widget, definition
 configuration, layout selection, focus navigation, and emergency Stop all.
 Those are human-facing surfaces and are documented separately:
 
-- [`/workers` commands](reference/commands.md)
+- [`/agents` commands](reference/commands.md)
 - [Status widget](reference/status-widget.md)
 - [Configuration](reference/configuration.md)
 - [Getting started](getting-started.md)

package/docs/concepts/{workers.md → agents.md}

@@ -1,26 +1,26 @@
-# Workers and identity
+# Agents and identity
 
 [Documentation index](../README.md)
 
-A managed worker is a Pi session whose physical lifecycle is owned by herdr and
+A managed agent is a Pi session whose physical lifecycle is owned by herdr and
 whose assignment lifecycle is coordinated through the extension mailbox.
 
 ## The identities are intentionally different
 
 ### Agent definition
 
-The **agent definition** selects the worker's model, reasoning policy, tools,
+The **agent definition** selects the agent's model, reasoning policy, tools,
 skills, extensions, prompt body, context inheritance, and allowed direct
-workers.
+agents.
 
 Example: `reviewer`.
 
-Definitions are configuration, not live worker identity.
+Definitions are configuration, not live agent identity.
 
-### Logical worker identity
+### Logical agent identity
 
-The internal label is projected publicly as the `worker` identity for a live
-worker.
+The internal label is projected publicly as the `agent` identity for a live
+agent.
 
 Examples:
 
@@ -30,9 +30,9 @@ reviewer-2
 my-review
 ```
 
-Use the exact `worker` value from `worker list` only for
-`steer.worker`, `reply.worker`, or `close.worker` while those actions are listed
-in `available_actions`. A worker label is the live execution identity for one
+Use the exact `agent` value from `agent list` only for
+`steer.agent`, `reply.agent`, or `close.agent` while those actions are listed
+in `available_actions`. An agent label is the live execution identity for one
 assignment, not a continuation handle.
 
 Labels must begin with a lowercase letter, contain only lowercase letters,
@@ -40,34 +40,37 @@ digits, `_`, or `-`, and be at most 32 characters.
 
 ### Pi session identity
 
-Every managed worker has an exact Pi session. The list may expose the session
+Every managed agent has an exact Pi session. The list may expose the session
 ID and path for correlation.
 
 A session path or full UUID can be supplied as `delegate.session` to continue
-historical work. It is the continuation identity, not a live-control identity.
-Session delegation creates a new worker generation for one new assignment and
-uses the saved session's cwd and historical context. An exact active or
-unresolved managed representation blocks concurrent activation of that session.
+historical work. Session delegation creates a new agent generation for one new
+assignment and uses the saved session's cwd and historical context. With
+`delegate.session`, omitting `label` chooses a fresh available label derived
+from the saved definition; supplying one chooses the exact live label for that
+generation. The Pi session remains the continuation identity, not a
+live-control identity. An exact active or unresolved managed representation
+blocks concurrent activation of that session.
 
 ### herdr identities
 
 Workspace, tab, pane, generated herdr-agent alias, run ID, and process evidence
 exist to prove physical ownership and safe cleanup.
 
-They are not public alternatives to the `worker` identity.
+They are not public alternatives to the `agent` identity.
 
 ## Ownership
 
-Each worker has one exact direct owner Pi session.
+Each agent has one exact direct owner Pi session.
 
-A lead Pi session owns its direct workers.
+A lead Pi session owns its direct agents.
 
-A delegating worker may own direct workers when its effective definition has
-allowed `workers`.
+A delegating agent may own direct agents when its effective definition has
+allowed `agents`.
 
 Public list visibility follows this ownership boundary. Lead recovery may expose
 a proven orphan descendant only when durable ownership and exact absence of its
-former delegating worker are established.
+former delegating agent are established.
 
 ## Authority boundaries
 
@@ -78,31 +81,31 @@ Different systems answer different questions:
 | herdr         | Physical process/pane lifecycle, placement, live agent observations                      |
 | Mailbox       | Assignment acknowledgement, active/completed request identity, pending ask, final result |
 | Pi            | Session history, turns, messages, model interaction                                      |
-| Logical label | Internal durable worker identity, projected publicly as `worker`                         |
+| Logical label | Internal durable agent identity, projected publicly as `agent`                           |
 
 The mailbox `ResultRecord` is the persisted completion record and carries the
-identity needed to match its worker state. The owner-session delivery entry is
+identity needed to match its agent state. The owner-session delivery entry is
 a separate, wider record: it also carries delivery metadata such as `cwd` and
 the Pi session file. Those records are checked against their respective
 identity requirements; `ResultRecord` is not intended to mirror the complete
 delivery-entry shape.
 
-If a result cannot be persisted after bounded retries, the worker state carries
+If a result cannot be persisted after bounded retries, the agent state carries
 a correlated `result_error` recovery condition instead of becoming assignable.
 
 A safe control operation requires these sources to agree. Missing or conflicting
 evidence fails closed rather than guessing.
 
-## Worker generations and continuation
+## Agent generations and continuation
 
-Every managed worker generation executes exactly one delegated assignment. Its
-terminal result is delivered once, then the worker's pane, process, mailbox,
+Every managed agent generation executes exactly one delegated assignment. Its
+terminal result is delivered once, then the agent's pane, process, mailbox,
 and runtime state are cleaned up. Failed assignments follow the same terminal
 cleanup path.
 
-The Pi session remains available after worker cleanup. To continue the same
+The Pi session remains available after agent cleanup. To continue the same
 conversational context, delegate a new assignment with the exact session ID or
-session path returned with the result. This creates a new worker generation,
+session path returned with the result. This creates a new agent generation,
 which uses the current effective authorized configuration for the saved agent
 definition. To derive a separate context instead, use `fork` on a definition
 delegation.
@@ -112,7 +115,7 @@ The identities are therefore:
 ```text
 agent definition → configuration for new work
 Pi session       → durable conversational context and continuation identity
-worker label     → live control identity for one assignment
+agent label     → live control identity for one assignment
 ```
 
 ## See also
@@ -120,5 +123,5 @@ worker label     → live control identity for one assignment
 - [Pi Herdsman](supervision.md) for the separate supervision model.
 - [Lifecycle](lifecycle.md)
 - [Delegation](delegation.md)
-- [Worker states](../reference/worker-states.md)
-- [`worker` API](../reference/worker.md)
+- [Agent states](../reference/agent-states.md)
+- [`agent` API](../reference/agent.md)

package/docs/concepts/delegation.md

@@ -10,43 +10,43 @@ The lead Pi session may delegate to any discovered effective agent definition.
 The lead retains architecture, global scope, acceptance, integration, and final
 decision authority.
 
-## Delegating worker
+## Delegating agent
 
-A lead-launched worker becomes delegation-enabled when its effective definition
-has a non-empty `workers` list and its tool policy permits the `worker` tool.
-The worker receives only the definitions named by its effective `workers` list.
+A lead-launched agent becomes delegation-enabled when its effective definition
+has a non-empty `agents` list and its tool policy permits the `agent` tool.
+The agent receives only the definitions named by its effective `agents` list.
 
-A delegating worker:
+A delegating agent:
 
-- delegates only to its permitted worker definitions;
-- owns only its direct workers;
-- integrates direct worker results into its own assignment;
+- delegates only to its permitted agent definitions;
+- owns only its direct agents;
+- integrates direct agent results into its own assignment;
 - remains subordinate to the lead's approved objective.
 
-Worker-started workers are leaves. Their effective metadata and launch policy
-remove the `workers` allowlist and `worker` capability. This keeps the supported
+Agent-started agents are leaves. Their effective metadata and launch policy
+remove the `agents` allowlist and `agent` capability. This keeps the supported
 structure bounded:
 
 ```text
 lead
-└── delegating worker
-    └── worker
+└── delegating agent
+    └── agent
 ```
 
-A lead may have many direct workers, and each direct worker that is explicitly
-delegation-enabled may have its own direct workers. A delegation-capable worker
-remains a worker at every depth; it is not a separate public role.
+A lead may have many direct agents, and each direct agent that is explicitly
+delegation-enabled may have its own direct agents. A delegation-capable agent
+remains an agent at every depth; it is not a separate public role.
 
-## Inferred `worker` capability
+## Inferred `agent` capability
 
-A non-empty `workers` field implies the `worker` tool when the definition uses
+A non-empty `agents` field implies the `agent` tool when the definition uses
 an explicit non-empty `tools` allowlist. An omitted tool allowlist keeps Pi's
-default tool policy rather than creating a `worker`-only list.
+default tool policy rather than creating an `agent`-only list.
 
 Explicit denial wins:
 
-- `excludeTools: ["worker"]` prevents inference.
-- `noTools: true` prevents inferred `worker` unless `worker` is explicitly
+- `excludeTools: ["agent"]` prevents inference.
+- `noTools: true` prevents inferred `agent` unless `agent` is explicitly
   present in `tools`.
 - An explicit exclusion wins over an explicit allow.
 
@@ -55,7 +55,7 @@ The exact field semantics live in the
 
 ## Parallelism
 
-Delegate genuinely independent or context-heavy work. Prefer workers for broad
+Delegate genuinely independent or context-heavy work. Prefer agents for broad
 file inspection, large logs or command output, and dataset analysis. Keep small,
 tightly coupled work local.
 
@@ -64,34 +64,34 @@ Do not:
 - delegate overlapping writers to one worktree;
 - delegate review before the writer finishes;
 - duplicate supplied reconnaissance;
-- continue dependent work while a required worker is active.
+- continue dependent work while a required agent is active.
 
 A useful pattern is:
 
 ```text
-delegating worker
+delegating agent
 ├── scout: bounded reconnaissance
 └── local independent analysis
 
-worker result arrives
+agent result arrives
 ↓
-delegating worker integrates both
+delegating agent integrates both
 ```
 
 ## Clarification across ownership edges
 
-A worker may ask its exact direct owner through `ask_owner`.
+An agent may ask its exact direct owner through `ask_owner`.
 
-A delegating worker may ask its own direct owner when its unresolved direct
-workers are themselves validly blocked on owner questions. Ordinary active
-worker work or an undelivered worker result still blocks escalation. Questions
+A delegating agent may ask its own direct owner when its unresolved direct
+agents are themselves validly blocked on owner questions. Ordinary active
+agent work or an undelivered agent result still blocks escalation. Questions
 are not automatically forwarded through an ownership chain.
 
 ## Closing
 
-Closing a delegating worker cascades through its directly owned workers first.
-Cleanup remains ownership-safe: if a required worker cannot be proved or
-closed, the delegating worker is preserved rather than destructively guessing.
+Closing a delegating agent cascades through its directly owned agents first.
+Cleanup remains ownership-safe: if a required agent cannot be proved or
+closed, the delegating agent is preserved rather than destructively guessing.
 
 ## See also
 

package/docs/concepts/lifecycle.md

@@ -14,7 +14,7 @@ accepted
   ↓
 working
   ↓
-worker completes
+agent completes
   ↓
 settling
   ↓ result delivered once
@@ -28,7 +28,7 @@ ID.
 
 ## Clarification flow
 
-A worker that requires an owner decision stays on the same assignment:
+An agent that requires an owner decision stays on the same assignment:
 
 ```text
 working
@@ -53,23 +53,23 @@ The public states are:
 - `settling`
 - `unknown`
 
-See [Worker states](../reference/worker-states.md) for their exact control
+See [Agent states](../reference/agent-states.md) for their exact control
 meaning.
 
 Raw herdr lifecycle alone is insufficient. Mailbox handoff, pending result
-delivery, pending owner questions, and cleanup may make a worker unsafe to
+delivery, pending owner questions, and cleanup may make an agent unsafe to
 control until convergence is complete.
 
 ## Asynchronous orchestration
 
-Delegation does not suspend the owning controller until a worker finishes.
+Delegation does not suspend the owning controller until an agent finishes.
 
-`delegate` returns after the task has been durably accepted. The worker then runs
+`delegate` returns after the task has been durably accepted. The agent then runs
 independently in its managed Pi session while the owner remains available for
 other useful work and, for a lead Pi session, continued user interaction.
 
 The owner must not poll for completion. It may continue with work that does not
-depend on the result or end its turn normally. Worker completion or an
+depend on the result or end its turn normally. Agent completion or an
 `ask_owner` question is delivered back to that same owner when attention is
 required.
 
@@ -80,7 +80,7 @@ assignment accepted
        ↓
 owner remains available
        ↓
-worker runs independently
+agent runs independently
        ↓
 result or question returns to the owner
 ```
@@ -92,18 +92,18 @@ requests, and remains responsible for result delivery and lifecycle control.
 ## Exactly-once assignment result
 
 Each accepted task request maps to one final assignment result. Each managed
-worker generation receives exactly one assignment; a completed worker is not
+agent generation receives exactly one assignment; a completed agent is not
 available for another task.
 
-Result publication and cleanup are separate convergence steps. A worker may
+Result publication and cleanup are separate convergence steps. An agent may
 therefore appear `settling` after its model has finished. Cleanup follows
 exactly-once delivery for both completed and failed terminal results.
 
 ## Session continuation
 
-Worker cleanup does not delete the Pi session. To continue completed context,
+Agent cleanup does not delete the Pi session. To continue completed context,
 use the exact returned session with `delegate.session`; Pi Herdsman starts a new
-worker generation for the new assignment. The continuation uses the saved cwd
+agent generation for the new assignment. The continuation uses the saved cwd
 and session history together with the current effective authorized definition
 configuration. Use `delegate.definition` with `fork` when a separate derived
 session is required.
@@ -113,37 +113,37 @@ session is required.
 `steer` changes the current active assignment. It does not create an independent
 result.
 
-Steering is at-least-once at the worker boundary: a worker can apply a steer
+Steering is at-least-once at the agent boundary: an agent can apply a steer
 before its acknowledgement write becomes durable. If that acknowledgement
 write fails, retrying the same request may apply the steer again.
 
-Use `steer` only when `worker list` reports `steer` in `available_actions`.
+Use `steer` only when `agent list` reports `steer` in `available_actions`.
 
-## Delegating worker completion
+## Delegating agent completion
 
-Direct worker work is a completion gate for a delegating worker.
+Direct agent work is a completion gate for a delegating agent.
 
-A delegating worker cannot publish its own final result while:
+A delegating agent cannot publish its own final result while:
 
-- a direct worker has ordinary active work; or
-- a completed direct-worker result has not yet been delivered to the delegating worker.
+- a direct agent has ordinary active work; or
+- a completed direct-agent result has not yet been delivered to the delegating agent.
 
-This completion gate does not create a separate public delegating-worker state.
-The delegating worker's own state projection remains authoritative.
+This completion gate does not create a separate public delegating-agent state.
+The delegating agent's own state projection remains authoritative.
 
 ## Restart and recovery
 
-Durable mailbox state allows exact managed workers to be reconstructed after a
+Durable mailbox state allows exact managed agents to be reconstructed after a
 controller restart. Live metadata can be rebuilt only when exact herdr and Pi
 identity still match.
 
 Unknown evidence remains `unknown`; recovery never rebinds stale metadata to a
-different worker generation.
+different agent generation.
 
 ## See also
 
-- [Pi Herdsman](supervision.md) for lead supervision that does not alter worker
+- [Pi Herdsman](supervision.md) for lead supervision that does not alter agent
   assignment ownership.
-- [Workers and identity](workers.md)
-- [Worker states](../reference/worker-states.md)
+- [Agents and identity](agents.md)
+- [Agent states](../reference/agent-states.md)
 - [Recovery](../guides/recovery.md)

package/docs/concepts/supervision.md

@@ -3,23 +3,24 @@
 [Documentation index](../README.md) · [Supervision reference](../reference/supervision.md)
 
 Pi Herdsman supervision lets one chief observe and communicate with independent
-lead sessions. Each lead owns one herd: itself and its complete worker tree.
-The chief supervises leads but never takes ownership of their workers.
+lead sessions. Each lead owns one herd: itself and its complete agent tree.
+The chief supervises leads but never takes ownership of their agents.
 
 ## Authority and lead state
 
 Herdr proves live process, pane, workspace, and native Pi session identity.
-Pi Herdsman's validated worker snapshots prove managed-worker identity and
+Pi Herdsman's validated agent snapshots prove managed agent identity and
 ownership. A supervised lead must be one exact live Pi agent with a matching
-private lead-coordination record; it must not be the chief or a managed worker.
+private lead-coordination record; it must not be the chief or a managed agent.
 Missing, stale, duplicate, or ambiguous evidence fails closed.
 
 Each lead has one private atomic record under the supervision runtime, keyed by
 the SHA-256 hash of its exact Pi session ID. The latest matching
 `pi-herdsman-lead-state` session entry supplies its persisted coordination
 state. A fresh `instanceId` on initialization protects against stale writers
-and publication races. The record is bounded to 2 KiB; its optional pending
-question is limited to 1,024 characters and 1,024 UTF-8 bytes.
+and publication races. The coordination record is bounded to 16 KiB, while
+individual transport message records retain the fixed 8 KiB ceiling. Its
+optional pending question is limited to 1,024 characters and 1,024 UTF-8 bytes.
 
 The record does not represent scheduling, capacity, permission, or message
 readiness. Herdr lifecycle observation is normalized to
@@ -31,7 +32,7 @@ authority, or message authority.
 
 ## Chief mode
 
-Chief is a mode of an ordinary lead session, not a separate worker identity.
+Chief is a mode of an ordinary lead session, not a separate agent identity.
 The persisted `pi-herdsman-role` entry contains either `role: "lead"` or
 `role: "chief"`. Chief mode is workspace-neutral and supervision-only. Its
 model exposes exactly the `staff` tool and excludes project/workspace context
@@ -57,16 +58,19 @@ chief list, inspect, message, and reply to supervised leads. A lead's message
 does not require an automatic chief reply. A `lead_ask` requires the exact
 correlated `staff reply`; a reply clears the pending ask only after accepted
 follow-up delivery. A replacement chief can answer an existing ask using its
-current lease and unchanged ask ID.
+current lease and unchanged ask ID. Chief and staff message actions accept
+files; their text is prepared with the same canonical attachment renderer and
+configured global byte limits as agent messages, while durable supervision
+records remain text-only.
 
 ## Supervision state
 
 The automatic `<supervision_state>` provider context is ephemeral, bounded, and
 state-only. It contains `leads`, with each lead's exact session ID,
-presentation `display_name`, runtime observation, `worker_counts`, `workers`,
+presentation `display_name`, runtime observation, `agent_counts`, `agents`,
 and available actions. The `staff list` result uses the same presentation field,
-`display_name`. The `workers` collection represents all validated descendants
-assigned to that lead, not only direct workers. Its values and metadata are
+`display_name`. The `agents` collection represents all validated descendants
+assigned to that lead, not only direct agents. Its values and metadata are
 untrusted observations and cannot authorize an action.
 
 Use the exact full session ID in a lead's `lead` field when calling `staff`.