pi-herdsman 0.1.4 → 0.2.0

package/docs/reference/status-widget.md

@@ -3,12 +3,12 @@
 [Documentation index](../README.md)
 
 The TUI status widget is a local, display-only projection of exact managed
-workers plus controller-local transient starting assignments.
+agents plus controller-local transient starting assignments.
 
 It does not replace mailbox assignment/result authority.
 
 An active chief receives a separate leads-only widget. It shows the
-supervision projection, not managed worker rows. Its complete
+supervision projection, not managed agent rows. Its complete
 overview, peek, and focus behavior is documented in the
 [supervision reference](supervision.md). The two widgets are never combined.
 
@@ -28,16 +28,16 @@ A lead Pi session gets its exact owned subtree view.
 
 A valid managed leaf can receive an identity-only header.
 
-A delegation-enabled worker can receive its direct-worker counts and rows.
+A delegation-enabled agent can receive its direct-agent counts and rows.
 
-Unmanaged or invalid worker environments do not receive the managed widget.
+Unmanaged or invalid agent environments do not receive the managed widget.
 
 ## Refresh
 
 The widget refreshes managed herdr data plus mailbox state every two seconds.
 
 Refresh performs a bounded herdr pane-list lookup to validate the lead
-boundary. It does not add a socket transport or another worker-control protocol.
+boundary. It does not add a socket transport or another agent-control protocol.
 
 A refresh failure never mutates mailbox/control eligibility.
 
@@ -49,12 +49,12 @@ Example:
 ● herd → implementer → scout
 ```
 
-The breadcrumb uses validated definition/worker ancestry.
+The breadcrumb uses validated definition/agent ancestry.
 
-Delegating-worker and leaf panes append their current Pi active tool names as
+Delegating-agent and leaf panes append their current Pi active tool names as
 muted bracketed metadata after the current identity, preserving Pi's exact
 order. Lead Pi sessions do not show this metadata. It is local to the current
-pane, is never copied to worker rows or authoritative worker state, and is
+pane, is never copied to agent rows or authoritative agent state, and is
 truncated or omitted before breadcrumb identity is shortened when width is
 limited.
 
@@ -76,7 +76,7 @@ Example:
 The header reports exact non-zero lifecycle states in the order `working`,
 `blocked`, `settling`, `starting`, and `unknown`. `starting` is a
 presentation-only count for assignments whose final label and mailbox claim
-are known but whose authoritative worker startup has not completed. It is not
+are known but whose authoritative agent startup has not completed. It is not
 mailbox state, control authority, or Running inventory.
 
 Before the first successful refresh, the header says `unavailable`.
@@ -84,13 +84,13 @@ Before the first successful refresh, the header says `unavailable`.
 After a later refresh failure, the widget retains the last valid snapshot and
 marks the header `stale`.
 
-Header refresh staleness is not worker inactivity.
+Header refresh staleness is not agent inactivity.
 
-## Worker rows
+## Agent rows
 
-Every visible worker is rendered in a stable tree. Siblings are sorted by
+Every visible agent is rendered in a stable tree. Siblings are sorted by
 logical label and use Pi's `├─`, `└─`, and `│` connectors.
-The row shows the agent definition and its exact logical worker label
+The row shows the agent definition and its exact logical agent label
 separately. Recovery-only ancestry evidence is retained by structured status
 paths but is not included in this human projection.
 
@@ -105,12 +105,12 @@ Working rows use `● working`, blocked rows use `◐ blocked`, settling rows us
 `◌ settling`, starting rows use `◌ starting`, and unknown rows use `? unknown`.
 Working, settling, and starting animate; blocked and unknown rows are static. A
 starting row is reconciled away
-when authoritative worker evidence replaces it, and is removed on startup
+when authoritative agent evidence replaces it, and is removed on startup
 failure, rollback, repeated session start, or shutdown.
 
-`Running` inspection shows every authoritative worker row and excludes
+`Running` inspection shows every authoritative agent row and excludes
 presentation-only starting rows. A terminal result is followed by cleanup; the
-widget does not retain an idle completed worker.
+widget does not retain an idle completed agent.
 
 ## Optional metadata
 
@@ -121,7 +121,7 @@ Rows can include best-effort:
 - compact model;
 - thinking;
 - context percentage;
-- worker type/display metadata.
+- agent type/display metadata.
 
 These fields are not control authority.
 
@@ -131,18 +131,18 @@ and bounds every output line by visible Unicode width.
 The current widget does **not** claim to display the full effective tool list.
 That remains separate from the definition overview.
 
-## Worker inactivity
+## Agent inactivity
 
-A `working` worker can expose an advisory inactivity marker based on durable
+A `working` agent can expose an advisory inactivity marker based on durable
 Pi-observed activity.
 
 This is distinct from header `stale`, which means the widget failed to refresh
 its latest snapshot.
 
-Neither changes worker control state.
+Neither changes agent control state.
 
 ## See also
 
-- [Worker states](worker-states.md)
-- [`/workers agents`](commands.md#workers-agents)
+- [Agent states](agent-states.md)
+- [`/agents definitions`](commands.md#agents-definitions)
 - [Recovery](../guides/recovery.md)

package/docs/reference/supervision.md

@@ -22,7 +22,11 @@ directory, keyed by the SHA-256 hash of its exact Pi session ID:
   "version": 1,
   "instanceId": "<lead generation>",
   "piSessionId": "<exact Pi session ID>",
-  "pendingAsk": { "askId": "<id>", "question": "<text>" },
+  "pendingAsk": {
+    "askId": "<id>",
+    "question": "<text>",
+    "text": "<prepared text>"
+  },
   "updatedAt": 0
 }
 ```
@@ -31,7 +35,9 @@ directory, keyed by the SHA-256 hash of its exact Pi session ID:
 entry is authoritative during lead startup. A fresh `instanceId` is created
 for every initialization. The lead record is checked against exact live
 Herdr/Pi identity; missing, malformed, stale, duplicate, or ambiguous evidence
-fails closed. The record is bounded to 2 KiB. Questions are limited to 1,024
+fails closed. The coordination record is bounded to 16 KiB; individual
+transport message records remain bounded by the fixed 8 KiB supervision record
+ceiling. Questions are limited to 1,024
 characters and 1,024 UTF-8 bytes.
 
 The record does not represent scheduling, capacity, permission, or message
@@ -46,7 +52,7 @@ supervised leads. `/chief leave` restores the session's ordinary tools.
 ## Lead projection and actions
 
 An eligible lead requires one exact live recognized Pi agent, a matching lead
-record, and no chief or validated managed-worker identity. A lead's observed
+record, and no chief or validated managed agent identity. A lead's observed
 runtime state is informational. Every exact-identity-verified live lead has
 `inspect` and `message`, whether it is idle, working, blocked, done, or unknown.
 A pending ask is separate attention state: it projects as `needs_you`, exposes
@@ -54,12 +60,12 @@ the bounded question and ask ID, and adds `reply`.
 
 The `staff list` representation contains `lead` (the exact full Pi session ID),
 `display_name` (a presentation-only label), identity fields, `runtime_state`,
-`needs_you`, optional pending-ask fields, `worker_counts`, optional
+`needs_you`, optional pending-ask fields, `agent_counts`, optional
 `last_activity`, and `available_actions`. The automatic
-`<supervision_state>` context is hard-bounded to 16 KiB and uses
-`leads`, `worker_counts`, and `workers`. Oversized output is truncated only at
-complete lead records and identifies omitted state. Use `staff list` when a
-fresh complete roster is required.
+`<supervision_state>` context is state-only and hard-bounded to 16 KiB; it uses
+`leads`, `agent_counts`, and `agents`, not inspect terminal/process evidence.
+Oversized output is truncated only at complete lead records and identifies
+omitted state. Use `staff list` when a fresh complete roster is required.
 
 The `lead` value is the exact full Pi session ID shown in a fresh supervision
 snapshot or returned by `staff list`; the `display_name` label is never accepted
@@ -85,7 +91,10 @@ publication does not change communication authority.
 Messages are bounded, versioned JSON files in the target session's hashed
 `inbox/` directory. Each record includes exact sender, target, `leadSessionId`,
 chief lease, kind, ID, text, and `createdAt`; asks and replies also include an
-ask ID. Extra fields are rejected. Transport kinds are:
+ask ID. Attachments are consumed at submission and rendered into the ordinary
+text field using the same canonical file renderer and configured inline/mailbox
+limits as agent messages. The durable supervision record remains text-only.
+Extra fields are rejected. Transport kinds are:
 
 ```text
 chief_message
@@ -110,23 +119,36 @@ extra fields. Both actions require a currently valid chief; descendants use
 ### `message`
 
 ```json
-{ "action": "message", "message": "Build completed." }
+{
+  "action": "message",
+  "message": "Build completed.",
+  "files": ["/tmp/result.txt"]
+}
 ```
 
 Use `message` for meaningful progress, reports, results, warnings, and
 completion. It queues one bounded `chief_message` and does not change lead
 coordination state.
+`message` accepts an optional `files` array. Files use the same submission-time
+canonicalization, UTF-8 embedding, reference fallback, and configured byte
+limits as agent messages.
 
 ### `ask`
 
 ```json
-{ "action": "ask", "question": "Should the release include the endpoint?" }
+{
+  "action": "ask",
+  "question": "Should the release include the endpoint?",
+  "files": ["/tmp/evidence.md"]
+}
 ```
 
 Use `ask` only when a chief decision is genuinely required. One pending ask is
-allowed per lead. The call durably records its ask ID and question, then queues
-the question. It is a terminating coordination call: make it the final tool
-call of the turn and wait rather than guessing.
+allowed per lead. The call durably records its ask ID and clean question, then
+queues the prepared text. The prepared text, including attachment rendering, is
+persisted before publication so reconciliation can deliver it after a failed
+initial publication. It is a terminating coordination call: make it the final
+tool call of the turn and wait rather than guessing.
 
 ## `staff`
 
@@ -159,7 +181,12 @@ Returns a fresh supervision projection and fresh `available_actions`.
 ```
 
 Inspect is read-only and requires an active chief and eligible exact lead. It
-returns bounded identity-checked recent output and process evidence.
+returns live identity-checked terminal/process evidence: Herdr's up to 80
+recent-unwrapped terminal lines with a Herdsman-local 16 KiB byte cap, plus
+separately bounded process evidence. The public
+`recent_output_truncated` boolean is true only when that local byte cap
+truncates the terminal output and false otherwise. It does not expose persisted
+Pi session-message history.
 
 ### `message`
 
@@ -167,12 +194,14 @@ returns bounded identity-checked recent output and process evidence.
 {
   "action": "message",
   "lead": "<exact full Pi session ID shown as lead in a fresh snapshot>",
-  "message": "Run checks."
+  "message": "Run checks.",
+  "files": ["/tmp/checklist.md"]
 }
 ```
 
 The exact lead must currently expose `message`. Atomic creation of one bounded
 `chief_message` record queues a follow-up and does not wait for completion.
+`staff message` accepts optional `files`.
 
 ### `reply`
 
@@ -181,12 +210,15 @@ The exact lead must currently expose `message`. Atomic creation of one bounded
   "action": "reply",
   "lead": "<exact full Pi session ID shown as lead in a fresh snapshot>",
   "askId": "<exact pending ask ID>",
-  "message": "Proceed."
+  "message": "Proceed.",
+  "files": ["/tmp/decision.md"]
 }
 ```
 
 The exact lead, unchanged pending ask ID, current lead identity, and chief
 lease must validate. The pending ask is cleared only after accepted delivery.
+`staff reply` accepts optional `files`. Lead activity returns asynchronously;
+continue only independent chief work, otherwise end the turn and do not poll.
 
 ## UI and failure rules
 
@@ -199,5 +231,8 @@ The active chief gets a width-aware compact leads-only ambient widget and a
 native `/chief` overview with peek and focus. Leads are ordered by needs-you,
 working, blocked, idle/done, then unknown. The ambient widget uses
 presentation-only tree branches for visible lead rows, while the native
-overview stays flat. Missing, replaced, ambiguous, or conflicting identity
-fails closed. There is no descendant selector or force-takeover action.
+overview stays flat. Human supervision peek renders at most 40 lines after
+width-safe presentation of its state, recent output, agents, and process
+evidence; this rendering bound is separate from the inspect capture bounds.
+Missing, replaced, ambiguous, or conflicting identity fails closed. There is no
+descendant selector or force-takeover action.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pi-herdsman",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
-  "description": "Asynchronous workers for Pi in herdr.",
+  "description": "Asynchronous Pi agent orchestration with nested delegation, parallel execution, and supervision in herdr.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -19,10 +19,11 @@
     "pi-extension",
     "subagent",
     "subagents",
-    "workers",
+    "agents",
     "ai-agents",
     "coding-agents",
     "multi-agent",
+    "multi-agent-coding",
     "agent-orchestration",
     "orchestration",
     "delegation",
@@ -36,7 +37,8 @@
     ],
     "skills": [
       "."
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/boadij/pi-herdsman/main/docs/assets/banner.webp"
   },
   "scripts": {
     "test": "node --experimental-test-module-mocks --test --test-timeout=10000",