pi-herdsman 0.1.4 → 0.2.0

package/docs/development/documentation.md

@@ -56,7 +56,7 @@ Do not turn it into a structured API reference.
 
 Reading order and first-use orientation for model and agent-facing coordination.
 
-Link to the exact `worker`, `ask_owner`, lifecycle, delegation, handoff, state,
+Link to the exact `agent`, `ask_owner`, lifecycle, delegation, handoff, state,
 and error owners instead of restating their full contracts.
 
 ### Concepts
@@ -94,7 +94,7 @@ It does not own product API schemas or runtime behavior.
 
 Pi Herdsman has one deliberate instruction duplication.
 
-The runtime controller and managed-worker instructions are the authoritative,
+The runtime controller and managed agent instructions are the authoritative,
 self-contained operational contract. Root `SKILL.md` intentionally mirrors
 those mandatory operational instructions so loading the skill can reinforce
 them in a long model context.
@@ -148,8 +148,8 @@ When implementation and existing prose disagree:
 2. current accepted runtime evidence can clarify integration behavior;
 3. stale prose should be deleted, not preserved as an alternative contract.
 
-Particularly verify the runtime implementation for `worker`, `ask_owner`,
-`/workers`, `/chief`, `staff`, states, definition schema/composition, text-file snapshots,
+Particularly verify the runtime implementation for `agent`, `ask_owner`,
+`/agents`, `/chief`, `staff`, states, definition schema/composition, text-file snapshots,
 state projection, error categories, and presentation behavior;
 
 - `package.json` for supported Pi versions and package resources.

package/docs/development/smoke-testing.md

@@ -5,7 +5,7 @@
 These are maintainer acceptance checks for behavior that benefits from a real
 Pi/herdr boundary.
 
-Use disposable workers and exact-ID cleanup. Do not disturb unrelated user
+Use disposable agents and exact-ID cleanup. Do not disturb unrelated user
 workspaces or agents.
 
 ## Preconditions
@@ -31,21 +31,21 @@ Run the repository validation gate first.
 ## Current mailbox contract
 
 For a current managed run, inspect the persisted state, request, ask, and
-result records and verify they use protocol version `3` and contain no lifetime
-field. Control prompts use the `__PI_HERDSMAN_WORKER_V3__:` marker prefix.
+result records and verify they use protocol version `4` and contain no lifetime
+field. Control prompts use the `__PI_HERDSMAN_AGENT_V4__:` marker prefix.
 
 ## One-shot definition and session continuation
 
 Delegate a small deterministic read-only task to the `scout` definition. Record
-the returned worker, request, session, and pane identities.
+the returned agent, request, session, and pane identities.
 
 Verify:
 
-- one managed worker starts;
+- one managed agent starts;
 - the task is acknowledged;
-- the worker completes with exactly one result reaching the owner;
+- the agent completes with exactly one result reaching the owner;
 - the terminal result identifies the exact session;
-- cleanup removes the worker, pane, mailbox, and runtime;
+- cleanup removes the agent, pane, mailbox, and runtime;
 - the exact Pi session remains available.
 
 Use the exact returned session ID or path for a follow-up assignment:
@@ -61,17 +61,17 @@ Use the exact returned session ID or path for a follow-up assignment:
 Verify:
 
 - the same Pi session and session file are used;
-- a new worker generation, run ID, request ID, and pane are created;
+- a new agent generation, run ID, request ID, and pane are created;
 - the saved conversation context is available;
 - the current effective definition configuration is used;
 - exactly one result reaches the owner;
-- cleanup removes the second worker, pane, mailbox, and runtime.
+- cleanup removes the second agent, pane, mailbox, and runtime.
 
 While the continuation assignment is active, submit another
 `delegate.session` request for the same exact session. Verify it fails with
-`worker_busy`, creates no duplicate worker or pane, and leaves the active
-assignment unchanged. After both assignments finish, `worker list` must show
-no completed idle worker.
+`agent_busy`, creates no duplicate agent or pane, and leaves the active
+assignment unchanged. After both assignments finish, `agent list` must show
+no completed idle agent.
 
 ## Historical session delegation
 
@@ -81,7 +81,7 @@ Verify:
 
 - saved definition and cwd are respected;
 - session delegation uses the saved cwd;
-- current effective agent override values are used for the new worker
+- current effective agent override values are used for the new agent
   generation;
 - the exact session continues.
 
@@ -91,23 +91,23 @@ Delegate to a definition with `fork` pointing to an exact saved session.
 
 Verify:
 
-- a new worker/session is created;
+- a new agent/session is created;
 - the fork source is explicit;
 - the current controller session is not implicitly used.
 
 ## Inferred delegation
 
-Use a bundled delegating worker definition whose source `tools` list does not explicitly
-contain `worker`, such as the current `implementer`.
+Use a bundled delegating agent definition whose source `tools` list does not explicitly
+contain `agent`, such as the current `implementer`.
 
 Ask it to delegate one bounded scout task.
 
 Verify:
 
-- the real Pi worker can call `worker`;
-- worker result reaches the delegating worker;
-- delegating worker integrates it once;
-- all one-shot workers clean up.
+- the real Pi agent can call `agent`;
+- agent result reaches the delegating agent;
+- delegating agent integrates it once;
+- all one-shot agents clean up.
 
 This proves effective-definition inference reaches Pi launch policy rather than
 only metadata.
@@ -118,7 +118,7 @@ Create a temporary global definition with a whole-line body reference:
 
 ```markdown
 ---
-name: worker
+name: generalist
 bodyMode: append
 ---
 
@@ -127,50 +127,50 @@ bodyMode: append
 
 Use a distinctive instruction in the referenced file.
 
-Verify the worker obeys that instruction through the expanded private prompt.
+Verify the agent obeys that instruction through the expanded private prompt.
 
 Afterward remove the temporary definition and referenced file, confirm discovery
 no longer lists the temporary definition, and verify no repository file changed.
 
 ## `ask_owner` round trip
 
-Give a worker a task whose correct continuation requires an owner choice.
+Give an agent a task whose correct continuation requires an owner choice.
 
 Verify:
 
-1. worker calls `ask_owner` alone;
+1. agent calls `ask_owner` alone;
 2. owner receives one question;
-3. worker becomes `blocked`;
-4. owner replies with exact `worker reply`;
+3. agent becomes `blocked`;
+4. owner replies with exact `agent reply`;
 5. reply continues the same assignment;
-6. worker produces exactly one final result;
-7. no worker/mailbox leak remains.
+6. agent produces exactly one final result;
+7. no agent/mailbox leak remains.
 
-## Delegating-worker natural waiting
+## Delegating-agent natural waiting
 
-Ask a delegating worker to delegate required reconnaissance when no useful independent
+Ask a delegating agent to delegate required reconnaissance when no useful independent
 local work remains.
 
-Inspect the actual transcript and verify the delegating worker:
+Inspect the actual transcript and verify the delegating agent:
 
 - ends its turn normally after the assignment;
-- does not poll `worker list`;
+- does not poll `agent list`;
 - does not sleep or use a separate wait mechanism;
-- wakes when the worker result is delivered;
-- integrates the result into one final delegating worker outcome.
+- wakes when the agent result is delivered;
+- integrates the result into one final delegating agent outcome.
 
 ## Useful concurrency
 
-Give a delegating worker one delegated task A and independent local task B.
+Give a delegating agent one delegated task A and independent local task B.
 
 Verify it can work on B while A is active, then ends its turn when no useful
 independent work remains and integrates A after result delivery.
 
-## Lead `/workers` commands
+## Lead `/agents` commands
 
 In a lead session with UI:
 
-### `/workers agents`
+### `/agents definitions`
 
 Verify the native Definitions selector shows:
 
@@ -183,7 +183,7 @@ Verify the native Definitions selector shows:
 - `Use default` for model and thinking;
 - narrow panes remain width-safe.
 
-Structured `worker list` should still retain exact deterministic metadata.
+Structured `agent list` should still retain exact deterministic metadata.
 
 Select a disposable bundled, project, or global definition and change its
 model, thinking, and enabled state. Confirm that project discovery requires a
@@ -192,16 +192,16 @@ write global overrides only, not project files.
 
 Verify unrelated frontmatter and body remain unchanged, `Use default` removes
 only the selected field, fresh definition delegations and session continuations
-use the current effective value, and running workers are not mutated.
+use the current effective value, and running agents are not mutated.
 
-### `/workers placement`
+### `/agents placement`
 
 Open the native selector, change to the alternate value, verify, then restore
 the original value.
 
-### `/workers stop`
+### `/agents stop`
 
-With disposable owned workers, verify the owned tree closes while an unrelated
+With disposable owned agents, verify the owned tree closes while an unrelated
 herdr agent remains untouched.
 
 ## Failure diagnostics
@@ -213,13 +213,13 @@ Verify startup failure:
 - settles within the bounded budget;
 - reports the stage and best available diagnostic;
 - performs exact ownership-safe rollback;
-- does not leave a false successful worker.
+- does not leave a false successful agent.
 
 ## Cleanup checklist
 
 After every smoke:
 
-- `worker list` has no unintended managed workers;
+- `agent list` has no unintended managed agents;
 - temporary global definitions are removed;
 - temporary prompt/body files are removed;
 - disposable herdr resources are closed by exact ID;
@@ -233,23 +233,23 @@ substitutes for these checks.
 
 | Scenario                                                                                                                             | Result  |
 | ------------------------------------------------------------------------------------------------------------------------------------ | ------- |
-| Normal lead has `worker` and `chief`, not `staff`                                                                                    | NOT RUN |
+| Normal lead has `agent` and `chief`, not `staff`                                                                                     | NOT RUN |
 | Active Chief has exactly `staff`, not lead controller tools                                                                          | NOT RUN |
 | Persisted Chief resume collision becomes suspended                                                                                   | NOT RUN |
 | Ordinary losing `/chief` collision remains a lead with its tools and offers Focus/Cancel                                             | NOT RUN |
-| Delegating worker and worker retain their current role tools                                                                         | NOT RUN |
+| Delegating agent and agent retain their current role tools                                                                           | NOT RUN |
 | Activate one Chief with `/chief`                                                                                                     | NOT RUN |
-| Activation refuses a lead with owned or unresolved worker work                                                                       | NOT RUN |
+| Activation refuses a lead with owned or unresolved agent work                                                                        | NOT RUN |
 | Two exact simultaneous Chief claims have one winner                                                                                  | NOT RUN |
 | Stale exact lease recovery                                                                                                           | NOT RUN |
 | Malformed role, lead state, lease, or descriptor fails closed; coordination publication invalidates stale state and disables actions | NOT RUN |
 | Discover leads across multiple workspaces                                                                                            | NOT RUN |
-| Exclude managed workers and the active Chief from leads                                                                              | NOT RUN |
-| Worker exclusion uses the production validated snapshot and stale/ambiguous generations fail closed                                  | NOT RUN |
+| Exclude managed agents and the active Chief from leads                                                                               | NOT RUN |
+| Agent exclusion uses the production validated snapshot and stale/ambiguous generations fail closed                                   | NOT RUN |
 | Herdr `agent_status ?? status` lifecycle normalization is reflected                                                                  | NOT RUN |
-| Nested worker aggregation attaches only to the proven lead                                                                           | NOT RUN |
-| A blocked worker does not mark its lead `needs you`                                                                                  | NOT RUN |
-| Duplicate live agents, coordination records, or worker evidence fail closed                                                          | NOT RUN |
+| Nested agent aggregation attaches only to the proven lead                                                                            | NOT RUN |
+| A blocked agent does not mark its lead `needs you`                                                                                   | NOT RUN |
+| Duplicate live agents, coordination records, or agent evidence fail closed                                                           | NOT RUN |
 | Target disappearance or replacement between list and action is rejected                                                              | NOT RUN |
 | Inspect a lead and compare bounded peek evidence                                                                                     | NOT RUN |
 | Focus a lead after exact revalidation                                                                                                | NOT RUN |

package/docs/getting-started.md

@@ -3,7 +3,7 @@
 [Documentation index](README.md) · [Agent coordination API](agent-api.md) · [Pi Herdsman](concepts/supervision.md)
 
 This is the shortest human-facing path from installation to useful Pi Herdsman
-orchestration. You do not need to type structured `worker` requests for this
+orchestration. You do not need to type structured `agent` requests for this
 path.
 
 ## 1. Check requirements
@@ -29,14 +29,14 @@ pi install npm:pi-herdsman
 ```
 
 Pi reads the package manifest and loads the extension plus the optional
-`workers` skill.
+`agents` skill.
 
 ## 2. Start the lead Pi session inside herdr
 
 The lead Pi session must run inside herdr. A lead Pi session started outside herdr
-cannot safely manage herdr workers.
+cannot safely manage herdr agents.
 
-The extension distinguishes a lead Pi session, valid managed workers, and
+The extension distinguishes a lead Pi session, valid managed agents, and
 unmanaged or invalid environments. Only supported managed environments receive
 Pi Herdsman controls and status UI.
 
@@ -45,18 +45,18 @@ Pi Herdsman controls and status UI.
 Ask the lead Pi agent in ordinary language, for example:
 
 ```text
-Use an implementer worker to implement the approved change.
+Use an implementer agent to implement the approved change.
 ```
 
 Pi Herdsman starts the work asynchronously. Once the assignment is accepted, the
 lead Pi session remains the session you interact with instead of waiting for the
-worker to finish.
+agent to finish.
 
-While workers work, you can continue discussing or planning with the
+While agents work, you can continue discussing or planning with the
 lead Pi session, delegate other independent work, inspect active work, or focus a
-managed worker pane.
+managed agent pane.
 
-You do not need to poll for completion. Results and worker questions are
+You do not need to poll for completion. Results and agent questions are
 delivered back to the owning controller when they need attention.
 The exact semantics are owned by [Lifecycle](concepts/lifecycle.md).
 
@@ -64,12 +64,12 @@ Pi Herdsman is opinionated about coordination, not workflow. Use the agent roles
 tools, extensions, and process that fit your project; the lead agent handles the
 structured coordination API internally.
 
-## 4. Open the workers menu
+## 4. Open the agents menu
 
 In the lead Pi TUI, run:
 
 ```text
-/workers
+/agents
 ```
 
 The native menu contains:
@@ -88,7 +88,7 @@ trusted project setting `piHerdsman.projectAgents` is `true`; effective preceden
 is bundled < project < global. `Layout` controls whether newly started agents
 use tabs or splits. `Stop all…` is destructive emergency control.
 
-See [`/workers` commands](reference/commands.md) for exact behavior.
+See [`/agents` commands](reference/commands.md) for exact behavior.
 
 ## 5. Configure definitions and layout
 
@@ -100,7 +100,7 @@ expand the resolved definition instructions with Pi's native `Ctrl+O`
 behavior. These edits always write global overrides, never project files.
 
 Use `Layout` to choose the current `tab` or `split` placement for newly started
-workers.
+agents.
 
 For complete configuration ownership, see:
 
@@ -112,12 +112,12 @@ For complete configuration ownership, see:
 ## 6. Watch and focus work
 
 The status widget shows active managed work and transient `starting` activity.
-Workers exist for one assignment only. After a terminal result is delivered,
-Pi Herdsman cleans up the worker; the exact Pi session remains available for
+Agents exist for one assignment only. After a terminal result is delivered,
+Pi Herdsman cleans up the agent; the exact Pi session remains available for
 continuation. The `Running` menu shows the complete authoritative inventory of
 live or unresolved lifecycle work.
 
-Managed worker panes show their validated breadcrumb identity. Their own active
+Managed agent panes show their validated breadcrumb identity. Their own active
 Pi tool names can appear as compact bracketed metadata on that breadcrumb.
 
 See [Status widget](reference/status-widget.md) for exact state, refresh, and
@@ -125,14 +125,14 @@ rendering behavior.
 
 To continue a completed assignment with its existing conversational context,
 use the exact `session_id` returned with its result in a new `delegate.session`
-request. This starts a new worker generation with the saved session and current
+request. This starts a new agent generation with the saved session and current
 effective definition configuration.
 
 ## 7. Recover only when needed
 
 Normal coordination and targeted cleanup belong to the agent API. Use
 `Stop all…` only when you deliberately want lead-level emergency cleanup of the
-proven owned worker tree.
+proven owned agent tree.
 
 For failure diagnosis and conservative cleanup, see [Recovery](guides/recovery.md).
 
@@ -145,7 +145,7 @@ eligible lead can become the chief with:
 /chief
 ```
 
-This is optional and does not change worker ownership. In a UI session, use
+This is optional and does not change agent ownership. In a UI session, use
 `/chief leave` to leave after reviewing its confirmation, which reports
 known outstanding supervised lead asks and leaves them pending. Cancellation
 does nothing; an unavailable count is reported as unknown. Without a UI, leave
@@ -162,7 +162,7 @@ workspace-local Pi work.
 ## Next steps
 
 - Keep delegating naturally through the lead Pi session.
-- Use [`/workers` commands](reference/commands.md) when you need human control.
+- Use [`/agents` commands](reference/commands.md) when you need human control.
 - Configure [agent definitions](guides/agent-definitions.md).
 - Read [Agent coordination API](agent-api.md) only when you need the model and
   agent-facing contracts.

package/docs/guides/agent-definitions.md

@@ -2,7 +2,7 @@
 
 [Documentation index](../README.md)
 
-Agent definitions describe a worker's capabilities, not a required
+Agent definitions describe an agent's capabilities, not a required
 workflow. They are Markdown files containing strict frontmatter plus an optional
 prompt body.
 
@@ -69,15 +69,15 @@ enabled: false
 ---
 ```
 
-The lead effective roster and `/workers agents` output keep disabled rows and
-show their disabled status so the source can be re-enabled. A delegating worker
-does not receive disabled workers in its definition list. A delegating worker referencing
-a disabled worker can remain discoverable, but is rejected during assignment or
-fresh worker startup with an explicit disabled-worker reason rather than silently
-dropping that worker.
+The lead effective roster and `/agents definitions` output keep disabled rows and
+show their disabled status so the source can be re-enabled. A delegating agent
+does not receive disabled definitions in its definition list. A delegating agent
+referencing a disabled definition can remain discoverable, but is rejected during
+assignment or fresh agent startup with an explicit disabled-definition reason
+rather than silently dropping that definition.
 
 Definition and session delegations reject disabled definitions with an
-actionable error. An already active worker may finish and remains controllable
+actionable error. An already active agent may finish and remains controllable
 according to its current available actions; disabling a definition does not
 mutate that assignment.
 
@@ -85,11 +85,11 @@ mutate that assignment.
 
 ### `implementer`
 
-Focused source-edit worker for an explicitly approved implementation.
+Focused source-edit agent for an explicitly approved implementation.
 
 ### `researcher`
 
-Focused current/external research worker. Read-only local policy. It also
+Focused current/external research agent. Read-only local policy. It also
 allows the default web tool names exposed by `pi-web-access`:
 `web_search`, `fetch_content`, `get_search_content`, and `source_check`.
 Web access is optional. Install it with:
@@ -114,9 +114,9 @@ Independent read-only reviewer.
 
 Fast read-only codebase reconnaissance.
 
-### `worker`
+### `generalist`
 
-General-purpose scoped execution worker.
+General-purpose scoped execution agent.
 
 The bundled definitions are portable defaults, not required workflow stages.
 Project definitions are for repository-specific policy; global definitions are
@@ -151,23 +151,23 @@ does not need extension-provided capabilities.
 The `name` is authoritative; the filename itself is not the public definition
 name.
 
-## Allow direct workers
+## Allow direct agents
 
 ```markdown
 ---
 name: coordinator
 tools: ["read", "bash"]
-workers: ["scout", "researcher"]
+agents: ["scout", "researcher"]
 ---
 
-Coordinate the assigned analysis and integrate direct worker results.
+Coordinate the assigned analysis and integrate direct agent results.
 ```
 
-The effective roster is validated atomically. Every `workers` name must exist.
+The effective roster is validated atomically. Every `agents` name must exist.
 Bundled role descriptions and bodies describe role behavior only; orchestration
 guidance comes from the active controller contract.
 
-With a non-empty explicit `tools` allowlist, `worker` is inferred unless
+With a non-empty explicit `tools` allowlist, `agent` is inferred unless
 explicitly denied. See [Delegation](../concepts/delegation.md).
 
 ## Add body files
@@ -190,10 +190,15 @@ Supported forms:
 @./relative.md
 @../relative.md
 @/absolute/path.md
+@~/home-relative.md
 ```
 
 References are resolved from the Markdown file that declares them.
 
+The bundled definitions are `generalist`, `implementer`, `researcher`,
+`reviewer`, and `scout`. The session-start agent-definition roster and the
+`agent list` result use the same metadata projection.
+
 For exact expansion, deduplication, and caller-file precedence, see
 [Handoffs and files](handoffs.md).
 
@@ -202,7 +207,7 @@ For exact expansion, deduplication, and caller-file precedence, see
 A lead Pi session can use:
 
 ```text
-/workers agents
+/agents definitions
 ```
 
 or the model can use:
@@ -230,5 +235,5 @@ See [Customizing bundled agents](customizing-agents.md).
 ## See also
 
 - [Agent-definition schema](../reference/agent-definition-schema.md)
-- [`/workers` commands](../reference/commands.md)
+- [`/agents` commands](../reference/commands.md)
 - [Configuration](../reference/configuration.md)

package/docs/guides/customizing-agents.md

@@ -40,11 +40,9 @@ enabled: false
 ```
 
 The disabled row remains visible to the lead Pi session, while owner-visible
-definition lists omit it. A delegating worker referencing a disabled worker can remain
-discoverable, but is rejected during assignment or fresh worker startup with an
-explicit disabled-worker reason.
-
-There is no compatibility layer or second definition registry.
+definition lists omit it. A delegating agent referencing a disabled agent can remain
+discoverable, but is rejected during assignment or fresh agent startup with an
+explicit disabled-agent reason.
 
 ## Body composition
 
@@ -98,7 +96,7 @@ prompt.
 `systemPromptMode: append` appends the effective body to Pi's normal system
 prompt.
 
-Managed workers additionally receive shared herdr worker guidance at launch,
+Managed agents additionally receive shared herdr agent guidance at launch,
 including the `ask_owner` contract. This shared guidance is infrastructure and
 is not copied into every bundled role body.
 
@@ -116,10 +114,14 @@ bodyMode: append
 The path is resolved relative to the declaring project or global file before
 body composition, so each layer preserves its own declaring-file provenance.
 
-References expand when each new worker generation is constructed. A session
+References expand when each new agent generation is constructed. A session
 continuation keeps the saved Pi history but uses the current effective
 definition configuration for its new generation.
 
+The Definitions details view re-resolves the selected name when opened, so
+metadata and body references reflect current overlays even if configuration
+changes while the menu is open.
+
 See [Handoffs and files](handoffs.md).
 
 ## Local tools, skills, and extensions
@@ -157,10 +159,10 @@ setting.
 
 An explicit `tools` list controls selection even when `noTools` or
 `noBuiltinTools` also selects restrictive defaults, while `excludeTools` wins
-over the list. Managed workers retain `ask_owner` as mandatory infrastructure
+over the list. Managed agents retain `ask_owner` as mandatory infrastructure
 and remove it from explicit exclusions; this exception does not apply to
 unmanaged Pi launches. Same-named tools cannot be permissioned by source, and
-collision winner ordering is not promised. Launcher-injected worker and
+collision winner ordering is not promised. Launcher-injected agent and
 Herdr-state extensions are separate from definition extensions and remain
 available when `noExtensions` disables ordinary discovery.
 
@@ -192,7 +194,7 @@ references, herdr does not resolve them relative to the definition file.
 Lead Pi sessions with UI can use:
 
 ```text
-/workers agents
+/agents definitions
 ```
 
 The native Definitions menu lists bundled, project, and global participation.
@@ -229,10 +231,10 @@ declares it.
 
 Changes affect future definition delegations and session continuations, whose
 runtime configuration comes from the current effective definition. They do not
-mutate an already-running worker or the lead Pi session.
+mutate an already-running agent or the lead Pi session.
 
 ## See also
 
 - [Agent-definition schema](../reference/agent-definition-schema.md)
-- [`/workers` commands](../reference/commands.md)
+- [`/agents` commands](../reference/commands.md)
 - [Agent definitions](agent-definitions.md)