fix(supervise): a retained child's settlement names why it is pending, as a value

CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.235.0
+
+**A retained child's settlement says WHY it is pending, as a value (#1204).** One reason string —
+`retained provider execution requires reconciliation before replacement` — covered two situations
+that call for opposite operator responses: an execution whose status genuinely cannot be
+determined, where refusing to replace it is correct and the operator must reconcile before
+retrying or pay twice for one turn; and a provider that broke its contract, where nothing needs
+reconciling and the right response is to fix or report the provider. Six exhibits in three days
+wore the first name for the second fault, and the runtime itself made it worse: it minted one
+`RetainedRunProviderContractError` class both when the provider answered wrongly and when a read
+of the provider merely failed.
+
+- `RetainedExecutionPendingError` now carries `pendingCause: RetainedPendingCause` —
+  `'unobservable'` (the safety refusal), `'provider-contract'`, `'request-rejected'`,
+  `'transport'`, `'nested-recovery'` — and its message names which one. The cause is classified
+  from the typed error's STRUCTURE (class name, `code`, HTTP `status`, a Zod issue list, the
+  members of an `AggregateError`), never from message text: the provider is not a dependency of
+  this package and its messages are not a contract.
+- Classification is **phase-aware**. A 4xx, a not-found, or a client deadline hit AFTER admission
+  means the provider cannot resolve what it admitted — exhibit 4's situation — and stays
+  `'unobservable'`; `'request-rejected'` is named only at admission. A schema failure after
+  admission is the runtime refusing the provider's answer, `'provider-contract'`.
+- A `RetainedRunProviderContractError` whose code says a READ failed
+  (`RETAINED_RESULT_READ_FAILED`, `RETAINED_CONTROL_REF_READ_FAILED`, and the new
+  `RETAINED_EVENT_STREAM_READ_FAILED`, split off `RETAINED_EVENT_STREAM_INVALID` so the
+  runtime's own stream checks keep their verdict) is a wrapper: what it wraps decides. The live
+  stream's event-binding check now mints `RETAINED_EVENT_BINDING_INVALID`, so an event bound to
+  another run classifies as the contract violation it is. Every `driverExecutor` throw that is a
+  nested-recovery failure says so instead of being inferred from whatever the driver threw.
+- `retainedPendingCause` rides beside `retainedExecution` everywhere that field goes: `Settled`'s
+  down arm, the `reconciled` and terminal journal records (through the one shared field spread,
+  so the released record — written live or healed on resume — carries it forward), `NodeSnapshot`
+  live and materialized, replay, both `agent.child` payloads, and `PursuitNodeProjection`. A
+  reader never splits the population on the reason's wording.
+- **Not covered, stated rather than faked:** #1204's exhibits 3 (`Tangle session event arrived
+  without a stable id`) and 6 (`value exceeds its JSON bound`) are thrown by agent-provider-tangle
+  as plain `Error`s with no code, so a structure-only classifier cannot name them; they land on
+  `'unobservable'`, the safe side, until the provider types them. Where they arrive as an
+  observation failure beside a failed result read, the read decides.
+- The refusal behaviour is unchanged: every cause still settles the child `down`, `infra: true`,
+  retained-pending, and counts in `fleetYield.releasedUnrecovered` once released. The cause says
+  what to do next, not whether the fleet lost the child. Journals written before this release
+  carry no cause; a reader treats absence as unknown, not as unobservable.
+
 ## 0.234.0
 
 **A resume heals the 0.233.0 crash window.** The `reconciled` record now carries the settlement

api-surface.json

@@ -505,7 +505,7 @@
       "PursuitNodeCost": "type 2ae084b090ba",
       "PursuitNodePlacement": "type 744e7b45dc01",
       "PursuitNodePlatform": "type 1d5dc2e2dd89",
-      "PursuitNodeProjection": "type 6d2b6c593df9",
+      "PursuitNodeProjection": "type a17725838ecf",
       "PursuitNodeTiming": "type 8cb37b8dca25",
       "PursuitNodeUsage": "type 951e957775ab",
       "PursuitProjection": "type 8d4e8a08d707",
@@ -1044,7 +1044,7 @@
       "NoWinnerError": "type adcf245eb125",
       "NodeExecutionIdentity": "type 76b27bc384d1",
       "NodeId": "type ba5552a40a12",
-      "NodeSnapshot": "type 7a1dd9177e44",
+      "NodeSnapshot": "type 881433f52643",
       "NodeStatus": "type 2073c1387091",
       "Observation": "type c276b53b9eb0",
       "ObservationAnalysis": "type b23fcc6368fb",
@@ -1150,6 +1150,7 @@
       "RetainedInteractiveRunHandle": "type dca0bd0f359f",
       "RetainedInteractiveStartMaterial": "type 82f6c8325ca2",
       "RetainedInteractiveStartedAdmission": "type 58531f291358",
+      "RetainedPendingCause": "type 9aefb24afb94",
       "RetainedRunAdmission": "type b1333206214a",
       "RetainedRunAdmissionHook": "type aa9c0342cbfc",
       "RetainedRunCancelOptions": "type c9bf674c803e",
@@ -1211,13 +1212,13 @@
       "SessionCapableBox": "type 9db08b40cab8",
       "SessionMessageLike": "type 726215634de7",
       "SessionTraceBox": "type b8d989093064",
-      "Settled": "type 24da40c1d786",
+      "Settled": "type d79f74b03f4d",
       "ShapeBudget": "type a1cb1a8d0995",
       "ShapeContext": "type a266c1b7e746",
       "ShapeRegistry": "type b567a5be55ec",
       "Shell": "type c676fe970f79",
       "ShotSpec": "type bf645fd74234",
-      "SpawnEvent": "type 1497e8b7c300",
+      "SpawnEvent": "type cf743d02f97e",
       "SpawnForest": "type 7308f34da226",
       "SpawnForestEvent": "type 230e369c6548",
       "SpawnForestInDoubtNode": "type 4e4bddd6a7d9",

docs/api/durable.md

@@ -1041,6 +1041,12 @@ Recorded by Runtime on the `agent.child` payload: `'pending'` at a retained chil
  fold overwrites in observed order; that event's `settledAt` is the original settlement, so
  `settledAt` and `timing` do not move.
 
+##### retainedPendingCause?
+
+> `readonly` `optional` **retainedPendingCause?**: [`RetainedPendingCause`](runtime.md#retainedpendingcause-1)
+
+Why a retained child has no accepted result; see `RetainedPendingCause`.
+
 ##### releasedAt?
 
 > `readonly` `optional` **releasedAt?**: `number`

docs/api/primitive-catalog.md

@@ -7,7 +7,7 @@
 
 # Primitive catalog — the never-stale anti-reinvention inventory
 
-> **GENERATED** from `@tangle-network/agent-runtime@0.234.0` and `@tangle-network/agent-eval@0.182.0` by `scripts/gen-primitive-catalog.mjs`. Do NOT hand-edit — run `pnpm run docs:api`. This is the mechanical companion to the JUDGMENT in `canonical-api.md` (§2 decision table + §1.5 AgentProfile law): that doc says WHICH primitive to reach for and what NOT to build; this catalog proves WHAT exists. Per-symbol signatures + `file:line` live in the per-module pages under `docs/api/`.
+> **GENERATED** from `@tangle-network/agent-runtime@0.235.0` and `@tangle-network/agent-eval@0.182.0` by `scripts/gen-primitive-catalog.mjs`. Do NOT hand-edit — run `pnpm run docs:api`. This is the mechanical companion to the JUDGMENT in `canonical-api.md` (§2 decision table + §1.5 AgentProfile law): that doc says WHICH primitive to reach for and what NOT to build; this catalog proves WHAT exists. Per-symbol signatures + `file:line` live in the per-module pages under `docs/api/`.
 
 ## 1. agent-runtime — own public surface
 
@@ -423,7 +423,7 @@ Import from `@tangle-network/agent-runtime/intelligence` — 167 exports.
 
 ### Execution kernel — recursive atom, supervision, executors, round-synchronous loop
 
-Import from `@tangle-network/agent-runtime/kernel` — 956 exports.
+Import from `@tangle-network/agent-runtime/kernel` — 957 exports.
 
 | Symbol | Kind | Summary |
 |---|---|---|
@@ -1160,6 +1160,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 956 exports.
 | `RetainedInteractiveAdmission` | type | Durable records for one exact native coding-agent process. |
 | `RetainedInteractiveAdmissionHook` | type | Persist each exact interactive record before the runtime proceeds. |
 | `RetainedInteractiveEnvironmentInput` | type | Environment and exact AgentProfile used to start one native coding-agent process. |
+| `RetainedPendingCause` | type | Why a retained execution has no accepted terminal result, classified where the cause is still |
 | `RetainedRunAdmission` | type | One detached-run admission record the runtime persists before creation or dispatch proceeds. |
 | `RetainedRunAdmissionHook` | type | Awaited durability hook for retained admission records. |
 | `RetainedRunEffect` | type | Effect recorded for one retained control operation. |