pi-herdsman 0.7.4 → 0.8.1

package/docs/concepts/agents.md

@@ -71,10 +71,11 @@ A lead Pi session owns its direct agents.
 A delegating agent may own direct agents when its effective definition has
 allowed `agents`.
 
-Public list visibility follows this ownership boundary. Durable descendants
+Public list visibility follows this ownership boundary. A lead sees only
+generations whose durable owner chain resolves to that lead. Durable descendants
 remain attached to their recorded parent even when that parent is lost or
-physically unresolved; missing durable ancestry is shown as non-actionable
-recovery evidence.
+physically unresolved. Missing, ambiguous, or cyclic durable ancestry is not
+attributed to a herd.
 
 ## Authority boundaries
 

package/docs/reference/agent-states.md

@@ -66,8 +66,8 @@ failed inventory never proves `lost`; relocated or conflicting evidence is
 | `lost`    | `close` only.                                                                   |
 | `unknown` | None.                                                                           |
 
-Descendants remain visible through durable ancestry but do not gain direct
-control from that visibility.
+Owned descendants remain visible through proven durable ancestry but do not gain
+direct control from that visibility.
 
 ## Inactivity fields
 

package/docs/reference/agent.md

@@ -89,8 +89,9 @@ Request:
 No selectors or other fields are accepted. A successful result includes the
 effective `agent_definitions` roster and visible agent records.
 
-Each valid durable generation remains visible, including unresolved `unknown`
-and proven `lost` records. Each actionable live agent record includes:
+Each valid durable generation in the controller's proven ownership projection
+remains visible, including physically unresolved `unknown` and proven `lost`
+records. Each actionable live agent record includes:
 
 | Field                                                           | Meaning                                                                                                                           |
 | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
@@ -122,10 +123,11 @@ projection returned by `list` for that controller. It is a startup snapshot;
 use `list` for live agent state, ownership, or a refreshed definition roster
 after configuration changes. Leaf agents do not receive a definition roster.
 
-Lead controllers see the complete effective definition roster and agents visible
-through their ownership boundary. Delegating agents see only allowed enabled
-leaf definitions and their visible agents. Unknown mailbox diagnostics remain
-non-actionable.
+Lead controllers see the complete effective definition roster and agents whose
+durable ownership chain resolves to that lead. Delegating agents see only allowed
+enabled leaf definitions and their direct agents. Unrooted, ambiguous, or cyclic
+durable ancestry is not attributed to the current controller. Unknown mailbox
+diagnostics remain non-actionable.
 
 ## `inspect`
 

package/docs/reference/errors.md

@@ -71,8 +71,10 @@ A `rollback_failure` can preserve:
 
 Inspect these fields before another destructive attempt.
 
-Model-facing error text surfaces available identity, stage, primary cause,
-cleanup cause, and next action without discarding the structured details.
+Model-facing error text surfaces operation, rollback and retry state, available
+identity, stage, primary cause, cleanup cause, and next action. Complete
+structured error details remain available in tool-result details for UI and
+logging.
 
 ## Model-visible truncation
 

package/docs/reference/status-widget.md

@@ -13,9 +13,10 @@ overview, peek, and focus behavior is documented in the
 [supervision reference](supervision.md). The two widgets are never combined.
 
 The ambient supervision rows use `├─` for non-final visible leads and `└─` for the
-final visible lead. Lead state glyphs remain separate (`◐` needs you, `●`
-working, and `○` ordinary/idle). Workspace labels are presentation text inside
-each lead row, not additional hierarchy nodes. The widget always retains
+final visible lead. Lead state glyphs remain separate (`◐` needs you, `●` lead
+working, `◉` idle/done with working descendants, and `○` otherwise). Workspace
+labels are presentation text inside each lead row, not additional hierarchy
+nodes. The widget always retains
 attention leads, caps ordinary leads, and shows omitted leads in a final
 `└─ … N more · /chief` row.
 
@@ -91,8 +92,9 @@ Header refresh staleness is not agent inactivity.
 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 agent label
-separately. Recovery-only ancestry evidence is retained by structured status
-paths but is not included in this human projection.
+separately. The tree contains only agents in the controller's proven ownership
+projection; unrooted, ambiguous, or cyclic durable ancestry is not attributed to
+the herd.
 
 Rows share globally aligned columns for state, elapsed time, compact model,
 thinking, context percentage, and optional inactivity. Context is shown as a
@@ -112,9 +114,9 @@ overridden. A starting row is removed when its exact request becomes active or
 terminal, its local runtime is removed, startup fails or rolls back, the
 controller session restarts, or shutdown clears transient state.
 
-The normal widget retains `lost` and fail-closed `unknown` rows because they
-represent durable unresolved generations whose physical state is either proven
-gone or not safely provable. `Running` inspection excludes `lost` and
+The normal widget retains owned `lost` and fail-closed `unknown` rows because
+they represent durable unresolved generations whose physical state is either
+proven gone or not safely provable. `Running` inspection excludes `lost` and
 fail-closed `unknown` rows because they are not safely focusable targets; it
 otherwise shows authoritative live agent rows and excludes presentation-only
 starting rows. A terminal result is followed by cleanup; the widget does not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdsman",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "type": "module",
   "description": "Asynchronous Pi subagents and agent fleet orchestration with nested delegation, parallel execution, and supervision in herdr.",
   "license": "Apache-2.0",