fix(ai): admit capability-bound Codex sessions

crates/graphql-orm-ai/CHANGELOG.md

@@ -18,6 +18,29 @@ checkpoint facts. For the current workspace baseline and active gates, use the
 [implementation status](docs/implementation-status.md) and the central
 [AI production-readiness plan](../../docs/plans/active/ai-production-readiness/README.md).
 
+## [0.88.2] - 2026-08-22
+
+Persistent schema module: **0.63.0** (unchanged from 0.88.1).
+
+### Fixed
+
+- Codex app-server registrations can now admit an exact capability-delivery
+  session binding after validating its model, reasoning effort, and embedded
+  executable/sandbox registration identity. Retained thread creation, resume,
+  failed-bind cleanup, and detached cleanup all recognize that complete
+  binding instead of rejecting it as though it were a raw registration
+  fingerprint.
+
+### Security
+
+- Capability-session admission accepts the validated binding object, never an
+  arbitrary fingerprint. The admitted fingerprint remains bound to the exact
+  delivery mode, capability-index set, static bootstrap tools, provider
+  projection, model, reasoning effort, and immutable Codex registration.
+
+There is no schema, data, protected-payload, GraphQL SDL, backup or restore
+migration in this release.
+
 ## [0.88.1] - 2026-08-22
 
 Persistent schema module: **0.63.0** (unchanged from 0.88.0).

crates/graphql-orm-ai/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "graphql-orm-ai"
-version = "0.88.1"
+version = "0.88.2"
 edition = "2024"
 authors = ["Toby Martin <toby@dastari.net>"]
 description = "Project-agnostic AI agent runtime for graphql-orm applications"

crates/graphql-orm-ai/MIGRATION.md

@@ -19,6 +19,27 @@ they describe. For the current workspace baseline and active delivery gates,
 use [implementation status](docs/implementation-status.md) and the central
 [AI production-readiness plan](../../docs/plans/active/ai-production-readiness/README.md).
 
+## 0.88.1 to 0.88.2: retained capability-session admission
+
+Adopt `graphql-orm-ai` 0.88.2 from one reviewed full monorepo revision. The AI
+schema module remains **0.63.0**. There is no database, data, table, column,
+index, constraint, backfill, GraphQL SDL, protected-payload, backup or restore
+migration.
+
+Codex app-server hosts that persist
+`AiProviderSessionDescriptor::new_with_capability_binding` descriptors must
+install the same exact `AiProviderCapabilitySessionBinding` on the immutable
+`AiCodexAppServerRegistration` before constructing the provider and cleanup
+service. The registration rejects a binding unless its model and reasoning
+effort are admitted and its embedded registration identity equals the exact
+effort-bound executable, sandbox, launch-profile, bootstrap, and adapter
+identity.
+
+The admission overlay deliberately does not alter that underlying identity:
+the binding already incorporates it, avoiding a circular fingerprint. Hosts
+must not accept or reconstruct a bare final fingerprint. Existing raw
+registration descriptors remain compatible.
+
 ## 0.88.0 to 0.88.1: Codex FixedBroker schema projection
 
 Adopt `graphql-orm-ai` 0.88.1 from one reviewed full monorepo revision. The AI

crates/graphql-orm-ai/README.md

@@ -226,12 +226,20 @@ configuration or exact Codex registration, and expose only
 Set the same selected value on `ModelRequest::reasoning_effort` and
 `AiBudgetReservationRequest::reasoning_effort`. The runtime rejects an
 explicit value absent from the active model profile before provider execution.
-For retained Codex sessions, create the provider-session descriptor with
-`registration.provider_session_fingerprint(selected_effort)?`; the app-server
-override affects subsequent turns, so changing effort requires exact cursor
-cleanup and rebind. Effort selection neither enables visible reasoning
-summaries nor grants tools, egress, filesystem, shell, browser, MCP, approval,
-or mutation authority. See the
+For retained Codex sessions without capability delivery, create the
+provider-session descriptor with
+`registration.provider_session_fingerprint(selected_effort)?`. A retained
+capability-delivery host instead constructs the exact
+`AiProviderCapabilitySessionBinding` from that raw fingerprint, installs the
+binding with `registration.with_capability_session_binding(binding.clone())?`,
+and persists a descriptor created by
+`AiProviderSessionDescriptor::new_with_capability_binding`. The adapter
+validates the binding's embedded raw identity and then recognizes its complete
+fingerprint for create, resume, and cleanup. The app-server effort override
+affects subsequent turns, so changing effort requires exact cursor cleanup and
+rebind. Effort selection neither enables visible reasoning summaries nor
+grants tools, egress, filesystem, shell, browser, MCP, approval, or mutation
+authority. See the
 [provider-session guide](docs/provider-sessions-and-hosted-activity.md) and
 [migration guide](MIGRATION.md).
 

crates/graphql-orm-ai/docs/provider-sessions-and-hosted-activity.md

@@ -110,6 +110,44 @@ and bind the new effort fingerprint. Pre-0.80 v3 registration fingerprints
 are accepted only by the deletion adapter for draining; they are never valid
 for a turn or resume.
 
+A retained capability-delivery descriptor persists the complete
+`AiProviderCapabilitySessionBinding::fingerprint()` instead of that raw value.
+Install the exact binding object on the Codex registration before constructing
+the provider and cleanup adapter:
+
+```rust
+let raw_registration =
+    registration.provider_session_fingerprint(selected_effort)?;
+let binding = AiProviderCapabilitySessionBinding::new(
+    delivery_mode,
+    capability_index_set_fingerprint,
+    static_bootstrap_tool_fingerprints,
+    provider_projection_version,
+    logical_model,
+    selected_effort,
+    raw_registration,
+)?;
+let registration = registration
+    .with_capability_session_binding(binding.clone())?;
+let descriptor = AiProviderSessionDescriptor::new_with_capability_binding(
+    ProviderKind::LocalHarness,
+    registration.provider_profile_id(),
+    registration.protocol_version(),
+    policy_fingerprint,
+    &binding,
+)?;
+```
+
+Admission validates the model, effort, delivery mode, and embedded raw
+registration identity; it never accepts a bare final fingerprint. The overlay
+does not change `registration.identity()` because the binding already embeds
+that value. Applying an identity-bearing registration builder afterward clears
+all prior capability admissions, so hosts install the binding last. The same
+exact admission fences empty-thread creation, retained turns, failed-bind
+discard, and detached cleanup. Frozen `EagerExact`, `ProviderDeferred`, and
+`FixedBroker` bindings are representable; `ClientDeferred` cannot freeze later
+definition installation into one Codex thread and remains rejected.
+
 For stateless operation the scope is one ephemeral Codex thread: the actor
 retains the selected effort through `thread/start` and its `turn/start`, then
 clears it only after the terminal turn notification. A later ephemeral thread