pi-herdsman 0.7.0 → 0.7.2

package/docs/concepts/agents.md

@@ -71,9 +71,10 @@ 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. Lead recovery may expose
-a proven orphan descendant only when durable ownership and exact absence of its
-former delegating agent are established.
+Public list visibility follows this ownership boundary. 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.
 
 ## Authority boundaries
 

package/docs/concepts/delegation.md

@@ -84,21 +84,35 @@ Do not:
 
 - delegate overlapping writers to one worktree;
 - delegate review before the writer finishes;
-- duplicate supplied reconnaissance;
-- continue dependent work while a required agent is active.
+- repeat work already assigned to an active agent;
+- delegate substantially overlapping work to multiple active agents;
+- continue work that depends on an active agent result;
+- inspect, list, or steer active agents merely to check progress or completion.
 
-A useful pattern is:
+Direct ownership grants lifecycle and control authority. It does not make the
+owner a second executor of an active delegated assignment.
+
+A useful parallel pattern is:
 
 ```text
-delegating agent
-├── scout: bounded reconnaissance
-└── local independent analysis
+controller
+├── agent A: independent reconnaissance
+├── agent B: separate independent analysis
+└── local: bounded independent controller work
+
+local work becomes sufficiently complete
+↓
+controller ends its turn
 
-agent result arrives
+agent result or attention resumes the controller
 ↓
-delegating agent integrates both
+controller integrates and reassesses
 ```
 
+Parallelism is optional. Do not create additional assignments or local side work
+merely to keep the controller active. For the full turn-navigation model, see
+[Asynchronous orchestration](lifecycle.md#asynchronous-orchestration).
+
 ## Clarification across ownership edges
 
 An agent may ask its exact direct owner through `ask_owner`.

package/docs/concepts/lifecycle.md

@@ -23,6 +23,13 @@ cleanup
 gone
 ```
 
+If the expected pane, Pi session, and run-scoped alias are all absent from a
+coherent Herdr inventory before a durable result resolves the assignment, the
+assignment projects as `lost`. The mailbox remains the durable owner of that
+generation until the direct owner explicitly closes it; physical disappearance
+does not mean completion or task failure. Moved, conflicting, or incomplete
+evidence remains `unknown`.
+
 The authoritative final result is correlated to the accepted assignment request
 ID.
 
@@ -52,6 +59,7 @@ The public states are:
 - `blocked`
 - `settling`
 - `unknown`
+- `lost`
 
 See [Agent states](../reference/agent-states.md) for their exact control
 meaning.
@@ -69,26 +77,49 @@ restart recovery. 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. Agent completion or an
-`ask_owner` question is delivered back to that same owner when attention is
-required.
+Each active delegated assignment has one executor: that agent. The owner retains
+lifecycle and control authority but does not repeat the delegated assignment
+locally or assign substantially overlapping work elsewhere.
+
+After starting an agent assignment or receiving an agent result or attention
+event, the owner reassesses the remaining work:
+
+1. Handle required agent control when needed.
+2. Delegate another concrete, necessary objective when it is independent of
+   active assignments and an authorized agent is the right owner.
+3. Continue concrete, necessary independent work locally when the owner is the
+   right owner and doing it now materially advances the task.
+4. Otherwise end the turn.
+
+After control, delegation, or local parallel work, the owner reassesses again.
+Once further useful progress depends on active agents, or no other concrete,
+necessary independent work remains, it ends the turn. Agent results,
+clarifications, and recovery attention resume the session automatically.
+
+The owner does not invent side work merely because agents are running. It does
+not poll, sleep, inspect merely for progress, send status steering, or use
+another mechanism to keep the turn alive.
 
 Conceptually:
 
 ```text
-assignment accepted
-       ↓
-owner remains available
-       ↓
-agent runs independently
-       ↓
-result or question returns to the owner
+assignment or agent event
+          ↓
+reassess remaining work
+    ↙        ↓        ↘
+ control   parallel   no useful
+            work      action
+          ↙     ↘        ↓
+      delegate  local  end turn
+          \      /        ↓
+           reassess   agent event resumes
 ```
 
-This is asynchronous but not fire-and-forget. The owner retains explicit
-assignment ownership, can steer eligible active work, receives clarification
-requests, and remains responsible for result delivery and lifecycle control.
+This is asynchronous but not fire-and-forget. The owner retains lifecycle and
+control authority: it can steer eligible active work when the assignment
+actually changes, receives clarification requests, and remains responsible for
+result delivery and cleanup. The delegated agent remains the executor of its
+active assignment.
 
 ## Exactly-once assignment result
 

package/docs/development/smoke-testing.md

@@ -155,25 +155,42 @@ Verify:
 6. agent produces exactly one final result;
 7. no agent/mailbox leak remains.
 
-## Delegating-agent natural waiting
+## Delegating-agent turn ending
 
-Ask a delegating agent to delegate required reconnaissance when no useful independent
-local work remains.
+Ask a delegation-enabled controller to delegate required reconnaissance when no
+other concrete, necessary independent work is known.
 
 Inspect the actual transcript and verify the delegating agent:
 
-- ends its turn normally after the assignment;
+- ends its turn after the assignment when nothing else useful is independently actionable;
+- does not repeat the delegated reconnaissance locally;
+- does not manufacture adjacent analysis merely to remain active;
+- does not delegate substantially overlapping reconnaissance to another agent;
 - does not poll `agent list`;
-- does not sleep or use a separate wait mechanism;
-- wakes when the agent result is delivered;
+- does not use `agent inspect` or `agent steer` merely to check progress;
+- does not send "finish", "status", or equivalent progress nudges to a healthy
+  agent;
+- does not sleep or use another mechanism to keep the turn alive;
+- the agent result resumes the controller session;
 - integrates the result into one final delegating agent outcome.
 
 ## Useful concurrency
 
-Give a delegating agent one delegated task A and independent local task B.
+Delegate bounded task A and give the controller concrete, necessary 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.
+Verify:
+
+- B proceeds while A is active;
+- B does not repeat A's assigned scope;
+- once B is sufficiently complete, the controller reassesses instead of
+  manufacturing more work;
+- if further useful progress depends on A, the controller ends its turn;
+- A's result resumes the controller and is integrated.
+
+Also verify a controller with two already-known independent delegated objectives
+may delegate A and B before ending its turn. It must not create a third
+assignment merely to increase concurrency.
 
 ## Lead `/agents` commands
 

package/docs/guides/recovery.md

@@ -47,6 +47,16 @@ Do not guess from pane IDs, process appearance, elapsed time, or stale metadata.
 Refresh `list` and resolve the identity/lifecycle condition. If a cleanup or
 recovery error is present, inspect its exact details.
 
+## Agent is `lost`
+
+`lost` means the expected physical execution is proven gone before a durable
+terminal result resolved the assignment. The durable mailbox remains owned and
+the assignment remains unresolved; loss is not completion or task failure.
+Only the direct owner may use `close` to abandon the lost generation. Close it
+before replacing it or continuing its saved session. Herdsman never
+redelegates or continues it automatically. Moved or conflicting evidence is
+`unknown`, not `lost`, and remains fail-closed.
+
 ## Inactivity advisory
 
 A `working` agent with an exact active assignment can become advisory `stale`
@@ -106,7 +116,9 @@ uncertain.
 
 ## Close failure
 
-Normal `agent close` targets one exact directly owned live agent.
+Normal `agent close` targets one exact directly owned live agent or a directly
+owned generation proven `lost` by fresh absence evidence. Unknown presence
+fails closed.
 
 Closing a delegating agent cascades through its owned agents first. If a
 agent cannot be proved or closed safely, the delegating agent remains rather

package/docs/reference/agent-states.md

@@ -5,20 +5,21 @@
 The public state is a safe-control projection built from live lifecycle and
 durable assignment/convergence evidence. It is not a raw herdr lifecycle string.
 
-| State      | Meaning                                                                                              |
-| ---------- | ---------------------------------------------------------------------------------------------------- |
-| `working`  | An assignment is active.                                                                             |
-| `blocked`  | Active assignment waits for owner attention or another condition.                                    |
-| `settling` | Assignment handoff, completion/result delivery, launch, direct-agent gate, or cleanup is converging. |
-| `unknown`  | Exact safe control state cannot be proved.                                                           |
+| State      | Meaning                                                                                                  |
+| ---------- | -------------------------------------------------------------------------------------------------------- |
+| `working`  | An assignment is active.                                                                                 |
+| `blocked`  | Active assignment waits for owner attention or another condition.                                        |
+| `settling` | Assignment handoff, completion/result delivery, launch, direct-agent gate, or cleanup is converging.     |
+| `unknown`  | Exact safe control state cannot be proved.                                                               |
+| `lost`     | Physical execution is proven absent before a durable terminal result; the assignment remains unresolved. |
 
 ## `available_actions` is authoritative
 
 A live agent record in `agent list` includes an `available_actions` snapshot.
 Use only operations currently listed there; do not infer control eligibility
 from `state` alone. `steer` means active work accepts steering, `reply` means a
-correlated pending `ask_owner` is valid, and `close` means exact ownership or
-approved orphan recovery permits teardown. `available_actions` never includes
+correlated pending `ask_owner` is valid, and `close` means exact direct ownership
+permits teardown. `available_actions` never includes
 `delegate`; an agent generation handles one assignment only. Every operation
 revalidates identity, ownership, mailbox state, and lifecycle immediately before
 mutation.
@@ -26,6 +27,9 @@ mutation.
 A delegating agent may be blocked while direct agent work is pending and still accept
 steering when `steer` is listed. Descendant visibility does not imply authority;
 records outside the controller's direct ownership can have an empty action list.
+Directly owned live records may expose the applicable live controls, including
+`close`; directly owned proven `lost` records expose `close` only. Unknown
+records and non-direct descendants remain fail-closed with no mutation actions.
 
 ## `blocked` and owner questions
 
@@ -45,6 +49,26 @@ or validation-failing mailbox state is reported with a bounded diagnostic and an
 empty `available_actions` list. Do not substitute pane idleness, elapsed time,
 model metadata, missing activity, a guessed session, or an old agent identity.
 
+`lost` is different: a coherent Herdr inventory proves the expected pane,
+session, and run-scoped alias are absent. It is not completion or task failure;
+use direct-owner `close` to abandon the unresolved generation.
+
+## Result precedence and actions
+
+A durable terminal result or `result_error` takes precedence over physical
+absence and projects as `settling` while delivery or recovery converges. A
+failed inventory never proves `lost`; relocated or conflicting evidence is
+`unknown`.
+
+| Record    | Direct-owner actions                                                            |
+| --------- | ------------------------------------------------------------------------------- |
+| `live`    | Existing live controls, including `inspect` and eligible `steer`, plus `close`. |
+| `lost`    | `close` only.                                                                   |
+| `unknown` | None.                                                                           |
+
+Descendants remain visible through durable ancestry but do not gain direct
+control from that visibility.
+
 ## Inactivity fields
 
 A qualifying `working` agent may also report `stale`, `inactive_ms`, and

package/docs/reference/agent.md

@@ -89,7 +89,8 @@ Request:
 No selectors or other fields are accepted. A successful result includes the
 effective `agent_definitions` roster and visible agent records.
 
-Each actionable live agent record includes:
+Each valid durable generation remains visible, including unresolved `unknown`
+and proven `lost` records. Each actionable live agent record includes:
 
 | Field                                                           | Meaning                                                                                                                           |
 | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
@@ -101,7 +102,7 @@ Each actionable live agent record includes:
 | `owner_session_id`                                              | Exact direct owner Pi session.                                                                                                    |
 | `agent_definition`                                              | Effective definition name.                                                                                                        |
 | `active_request_id`, `last_activity_at`, `stale`, `inactive_ms` | Assignment and advisory activity evidence.                                                                                        |
-| `parent_label`, `orphan`                                        | Visible direct-owner ancestry and proven orphan recovery evidence.                                                                |
+| `parent_label`                                                  | Durable parent assignment when the parent is visible.                                                                             |
 | `cleanup_error`, `result_error`, `diagnostic`, `tokens`         | Bounded recovery and presentation evidence when present.                                                                          |
 
 `available_actions` is authoritative model guidance for the current snapshot.
@@ -109,10 +110,11 @@ Do not infer eligibility from `state`. Active work may list `steer`; a valid
 correlated pending `ask_owner` may list `reply`; exact direct ownership may list
 `close`. `available_actions` never lists `delegate` or `continue`: these are
 controller operations, not controls on an already-live agent. An agent cannot
-receive a second assignment. Descendant visibility does not grant control. Lead orphan
-recovery may expose only `close`. Unknown and recovery-only records are
-non-actionable. Every operation rechecks identity, ownership, mailbox state, and
-lifecycle immediately before mutation.
+receive a second assignment. Directly owned live agents may expose the
+applicable live controls, including `close`; directly owned proven `lost`
+records expose `close` only. Unknown records and non-direct descendants expose
+no mutation actions. Every operation rechecks identity, ownership, mailbox
+state, and lifecycle immediately before mutation.
 The public record does not expose `steerable`.
 
 The session-start instructions include the same complete definition metadata
@@ -209,11 +211,12 @@ See [`ask_owner` API](ask-owner.md).
 { "action": "close", "agent": "implementer-1" }
 ```
 
-Only `action` and `agent` are accepted. Close requires exact direct ownership,
-or the lead-only evidence-backed orphan recovery condition. Closing abandons a
+Only `action` and `agent` are accepted. Close requires exact direct ownership.
+Closing abandons a
 pending owner question; closing a delegating agent cascades through directly
 owned agents first. Cleanup remains fail-closed when exact identity or ownership
-cannot be proved.
+cannot be proved. A direct owner may also close a proven `lost` generation
+after a fresh absence proof; `unknown` presence remains non-actionable.
 
 ## Result delivery and errors
 

package/docs/reference/status-widget.md

@@ -74,7 +74,7 @@ Example:
 ```
 
 The header reports exact non-zero lifecycle states in the order `working`,
-`blocked`, `settling`, `starting`, and `unknown`. `starting` is a
+`blocked`, `settling`, `starting`, `unknown`, and `lost`. `starting` is a
 presentation-only count for controller-local assignments that have begun
 startup but have not yet become active or terminal. It is not mailbox state,
 control authority, or Running inventory.
@@ -102,8 +102,9 @@ every row. The task is the rightmost elastic field and is kept only when it has
 useful room before it is truncated.
 
 Working rows use `● working`, blocked rows use `◐ blocked`, settling rows use
-`◌ settling`, starting rows use `◌ starting`, and unknown rows use `? unknown`.
-Working, settling, and starting animate; blocked and unknown rows are static.
+`◌ settling`, starting rows use `◌ starting`, unknown rows use `? unknown`, and
+lost rows use `× lost` with the theme's attention/error styling. Working,
+settling, and starting animate; blocked, unknown, and lost rows are static.
 While a controller-local start remains pending, an authoritative `settling`
 row is presented as `starting` so launch and request handoff remain visually
 continuous. `working`, `blocked`, and `unknown` authoritative states are never
@@ -111,9 +112,13 @@ 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.
 
-`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 agent.
+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
+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
+retain an idle completed agent.
 
 ## Optional metadata
 

package/package.json

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