Review gateway: admit tool requests by evidence and stop unsafe free replay

CHANGELOG.md

@@ -17,7 +17,9 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
   retries only final synthesis on a ready route. After HTTP 413 retires one
   route, another rate-limited route can still recover. This repair changes
   retry timing, not the Chat Completions JSON-schema request or response
-  fields; explicit model pins and expired budgets remain fail-closed.
+  fields; explicit model pins and expired budgets remain fail-closed. A zero
+  wait budget now limits only an all-cooling pool and does not prevent
+  immediate failover from an explicit 429 to an already-ready sibling.
 - Structured non-stream `/v1/responses` requests now preflight every required
   conduct role for `orchestrator/free`. Image-capable worker-only pools fail
   closed with typed HTTP 400 before template planning instead of surfacing a

contextual_orchestrator/provider_errors.py

@@ -394,6 +394,17 @@ def classify_provider_failure(
         # holding just the classified ProviderUpstreamError -- e.g. _invoke's
         # chat transport -- can still record and wait out the same cooldown.
         extra_detail: dict[str, Any] = {}
+        if status in (404, 410):
+            try:
+                body = _json.loads(provider_error_body(exc))
+            except Exception:  # noqa: BLE001 - provider error bodies are untrusted streams
+                body = None
+            if (
+                isinstance(body, dict)
+                and isinstance(body.get("error"), dict)
+                and body["error"].get("code") == "model_not_found"
+            ):
+                extra_detail["model_refusal_proven"] = True
         if status in (429, 503):
             retry_after = resolve_retry_after_seconds(exc)
             if retry_after is not None:

contextual_orchestrator/review_gateway.py

@@ -77,11 +77,10 @@
 
 @dataclass(frozen=True)
 class ReviewModelAdmission:
-    """Typed, request-scoped provenance for one admitted review-pool model.
+    """Typed catalog provenance for one admitted review-pool model.
 
-    Every field is owner-produced evidence about *why* the candidate is
-    admitted, so a consumer never has to re-derive eligibility, re-probe
-    readiness, or apply its own provider/model/fallback heuristics.
+    These fields explain catalog eligibility. They do not certify that a
+    particular request shape is supported or that the provider is live.
     """
 
     contract_version: str
@@ -118,11 +117,10 @@ def review_model_admission(
 def review_pool_admissions(
     agents: Sequence[Any],
 ) -> list[ReviewModelAdmission]:
-    """Project a built review pool into versioned, consumer-readable provenance.
+    """Project a built review pool into versioned catalog provenance.
 
-    The owner exposes this so a caller can send only the gateway token and
-    ``model: orchestrator/free`` -- no provider/model/fallback parameters,
-    no credential eligibility, no candidate catalog, no probing.
+    The caller sends only the gateway token and ``model: orchestrator/free``;
+    request-specific admission and execution remain gateway responsibilities.
     """
     return [
         ReviewModelAdmission(

docs/doctoring/autonomous_kpi_runbook.md

@@ -139,6 +139,12 @@ owner tests and protected release. See [the evidence receipt](https://github.com
 These are failed deliveries in the accuracy denominator, not measured routing
 decision latencies. Their elapsed times include work beyond initial selection.
 
+## Noema free-pool 429 follow-up, 2026-09-25
+
+Required Noema Review run [36026163711](https://github.com/ContextualWisdomLab/contextual-orchestrator/actions/runs/36026163711), job `107824690321`, used sidecar source `767e67fbc6b881a452761f32abb69b9971b9b03b` for PR #1231. Its `noema-sidecar-evidence` artifact `10844122590` records 19 provider attempts across eight distinct candidates for one request ID. After several NIM attempts, two different OpenRouter free models each explicitly returned 429. The 1197.3-second caller attempt then ended with 429. Thus this run proves cross-candidate routing occurred; it does not prove that another eligible, ready candidate remained after the final rejection. The preflight's six ready routes are earlier liveness evidence, not the request's terminal candidate count.
+
+The Noema workflow scheduled a bounded same-head continuation after 131 seconds, but its `POST /repos/{repo}/dispatches` failed with `Resource not accessible by integration` (403). This is a separate workflow credential/permission blocker. The current gateway code also retried an explicitly 429-rejected candidate before advancing when `tool_retry_attempts` was nonzero; the tool-bearing `orchestrator/free` HTTP regression for this repair asserts one call to that candidate followed by one call to the next eligible candidate. It does not authorize replay of ambiguous transport failures or claim that the pinned sidecar contains this repair. Recheck the exact sidecar source, hosted request trace, and current-head review verdict before release or attribution of a future 429.
+
 ### Structured synthesis 429 follow-up, 2026-09-25
 
 [Noema run 36024200990](https://github.com/ContextualWisdomLab/contextual-orchestrator/actions/runs/36024200990)

docs/product-technical-gap-baseline.md

@@ -254,6 +254,46 @@ environment's missing locked `pytest-asyncio` and inherited deprecated
 `jsonschema.RefResolver` warnings remain explicit. Hosted exact-head gates,
 independent review, protected merge, immutable release, and consumer adoption
 remain required.
+## 2026-09-25 review tool-request admission (#1106, proposed)
+
+The #940 baseline below intentionally allowed a free model with unknown tool
+support to receive a tool request. Issue #1106's later Strix tool-call 404
+shows why plain-chat readiness cannot authorize that request shape. The owner
+now requires positive discovery evidence for review-pool tool calls: the
+existing `tool_call:single|multi` tags determine admission for the actual
+request, and an empty eligible set returns typed 503 before provider send.
+Focused RED reproduced unknown-evidence admission, missing fail-closed
+behavior, and replay after ambiguous failures. The locked local environment
+passed 388 neighboring tests on 2026-09-25. Four provider-reliability tests
+were deselected after reproducing the same failures on unmodified `origin/main`
+at `5665b0ad` (selection-design receipt and provider allowlist classification).
+This is local contract evidence, not live provider readiness, judged review
+quality, protected delivery, or issue #1106 completion. Calibrated allocation,
+immutable release, and the central consumer's preflight removal remain open.
+The follow-up RED showed unsafe review replay after a post-send timeout;
+review-tagged completions now stop on that unknown outcome. A separate RED
+showed that the review route stopped after an explicit provider 429 even with
+another eligible free candidate. The owner now records the rejected candidate's
+cooldown and advances on direct 429, including HTTP tool requests and JSON-schema
+synthesis. An all-429 pool waits only within its configured budget and otherwise
+returns typed 429. A wrapped error with a nested 429 remains sticky because the
+outer send's outcome is unknown. Direct pre-send local-slot failure can still
+advance; HTTP 503 and post-send timeout remain terminal. Synthetic transport
+call counts and typed errors cover these boundaries. This source evidence does
+not establish provider idempotency, a protected release, or Noema approval;
+the observed Noema job used the older `767e67fb` sidecar pin.
+
+Exact-parent follow-up `0b4d2503f1f72aba4dc0cd05ce5f1504425b3e36`
+found that structured synthesis created a zero-duration recovery deadline
+after the first explicit 429, then enforced it before checking whether another
+eligible candidate was already ready. The RED case called only the primary and
+raised `rate_limited_storm`; the same test already proved ordinary-budget 429
+advancement and ambiguous-503 no-replay. GREEN scopes deadline expiry to the
+existing all-candidates-cooling branch, so `rate_limit_wait_seconds=0` still
+permits immediate ready-sibling failover while an all-429 pool returns typed
+429 without replay. The two adjacent owner suites pass 178 tests. This remains
+Proposed pending exact-head hosted checks, independent approval, protected
+integration, immutable release, and consumer adoption.
 
 ## 2026-09-08 item-covariate two-group boundary repair (proposed)
 

docs/research/review-gateway-free-pool-admission.md

@@ -88,6 +88,51 @@ No new routing heuristic is introduced by this change.
 
 ## Executable provenance
 
+### Request-shaped tool admission (2026-09-25, proposed)
+
+For a review-pool `orchestrator/free` Chat Completions request with tools, the
+gateway now uses its existing discovery evidence before sending to a provider.
+`tool_call:multi` admits either one or several tools; `tool_call:single` admits
+a request that does not require parallel calls. A review candidate without
+either positive signal can still serve plain chat, but cannot serve a tool
+request. If no free candidate proves the requested tool shape, the gateway
+returns `503 request_capability_unavailable` with `capability=tool_call` and
+does not send a completion. The same eligible set reaches every conduct role
+and final synthesis when the caller requests an orchestrated response. This
+addresses the plain-chat-ready/tool-404
+counterexample in issue #1106 without a provider-name branch in the consumer.
+
+The signal proves only the probed tool-call contract. It does not prove live
+availability, output quality, a provider idempotency guarantee, or completion
+of a long review. The catalog admission result remains distinct from an
+execution receipt. Calibrated allocation, a released request-scoped contract,
+immutable owner release, and the consumer's deletion of its own preflight
+remain open acceptance conditions for issue #1106.
+
+### Completion replay boundary
+
+For a review-tagged `orchestrator/free` candidate, a read timeout or connection
+reset after the transport began has unknown outcome and stops the request with
+`provider_outcome_unknown`; a second provider is not called. An explicit HTTP
+429 is a quota rejection: the gateway records its cooldown and may try another
+eligible candidate, or wait within its bounded budget when every candidate is
+cooling. A wrapped failure that merely contains a 429 does not establish that
+the outer send was rejected. HTTP 503, 408, 409, and 425 remain terminal for
+the review request. Direct local-slot admission failure
+before the transport call, or a provider response explicitly identifying
+`model_not_found` or a request-size rejection,
+can advance to another eligible candidate. The test counts transport calls
+on each side of the local slot and asserts that an unknown outcome never
+causes a second send. This narrows the earlier virtual-selector failover
+behavior for the review pool; other virtual selectors retain their prior
+contract. The same no-replay rule follows each actual review-tagged candidate
+through route and conduct calls for uncertain outcomes, including a mixed free
+pool. A non-review
+candidate retains its prior retry policy. A bodyless HTTP 404 cannot authorize
+another review send. No provider idempotency agreement has been established.
+This matches the non-idempotent retry boundary in
+[RFC 9110 §9.2.2](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2).
+
 The PR implementing this contract must prove at least the following cases:
 
 - all five required provider credentials may be supplied and registered together;