pi-herdsman 0.6.2 → 0.7.1

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/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.

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

@@ -61,6 +61,12 @@ session fail closed. The controller's own active Pi session cannot be continued
 to itself; use `delegate` with `fork` when a separate derived context is
 required.
 
+When `contextRetirement` is enabled, `continue` is rejected for a retired
+managed-agent session. A `delegate` with `fork` is also rejected when its
+source is a retired managed-agent session; delegate a fresh agent and pass the
+previous handoff/resultRef and relevant files instead. Retired results
+explicitly instruct the controller to delegate a fresh agent.
+
 The saved session's logical label is inherited exactly for the continued
 generation. A caller cannot provide a continuation label; if the inherited
 label is occupied, continuation fails with `agent_label_exists`.
@@ -83,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                                                                                                                           |
 | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
@@ -95,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.
@@ -103,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
@@ -203,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/commands.md

@@ -19,7 +19,8 @@ plain `/agents` remains available as a setup diagnostic.
 ```
 
 The plain command opens a native Pi selection menu with `Running`,
-`Definitions`, `Layout`, `Message limits`, and `Stop all…` destinations. The
+`Definitions`, `Layout`, `Context retirement  on|off`, `Message limits`, and
+`Stop all…` destinations. The
 Message limits view edits the user-wide inline attachment and mailbox payload
 limits. It is available only to a lead Pi session with UI. Current
 values and presets show a rough token equivalent using four UTF-8 bytes per

package/docs/reference/configuration.md

@@ -26,6 +26,7 @@ schema is:
 ```json
 {
   "spawnPlacement": "subtree",
+  "contextRetirement": true,
   "inlineAttachmentLimitBytes": 131072,
   "mailboxPayloadLimitBytes": 131072
 }
@@ -36,6 +37,7 @@ An absent file means these defaults:
 | Field                        |            Default | Allowed values                                    |
 | ---------------------------- | -----------------: | ------------------------------------------------- |
 | `spawnPlacement`             |          `subtree` | `tab`, `subtree`, `split`                         |
+| `contextRetirement`          |               true | boolean                                           |
 | `inlineAttachmentLimitBytes` | `131072` (128 KiB) | integer from 1024 (1 KiB) through 1048576 (1 MiB) |
 | `mailboxPayloadLimitBytes`   | `131072` (128 KiB) | integer from 1024 (1 KiB) through 1048576 (1 MiB) |
 
@@ -49,6 +51,14 @@ files remain canonical references. `mailboxPayloadLimitBytes` limits the exact
 serialized request, ask, or chief message record. Chief messages also retain
 their fixed 8 KiB protocol ceiling.
 
+When `contextRetirement` is enabled, automatic context pressure retires a
+managed-agent session. Herdsman suppresses preventive threshold compaction
+while the assignment finalizes and leaves Pi's overflow recovery available.
+The session receives a finalization instruction, and its result requires a
+fresh agent for follow-up. Disabling it bypasses retirement completely,
+including existing retirement markers, and leaves Pi's native compaction and
+session reuse behavior untouched.
+
 Placement affects future starts, not existing agents. `tab` uses one lead-owned
 agents tab, `subtree` gives each lead-direct agent its own tab, and `split`
 splits from the caller's pane. Nested delegation always splits in its owner's

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.6.2",
+  "version": "0.7.1",
   "type": "module",
   "description": "Asynchronous Pi subagents and agent fleet orchestration with nested delegation, parallel execution, and supervision in herdr.",
   "license": "Apache-2.0",