fix(opencode): preserve bounded provider failure causes

.github/workflows/agent-review-runtime-quality-ci.yml

@@ -14,6 +14,11 @@ on:
       - "docs/doctoring/noema-review-token-lifetime.md"
       - "docs/product-technical-gap-baseline.md"
       - ".github/workflows/opencode-review-dispatch.yml"
+      - "scripts/ci/run_opencode_review_model_pool.sh"
+      - "scripts/ci/opencode_failure_envelope.py"
+      - "tests/test_opencode_model_pool_runner.py"
+      - "tests/test_opencode_failure_envelope.py"
+      - "docs/doctoring/opencode-provider-failure-envelope.md"
       - "scripts/ci/ensure_rust_llvm19.sh"
       - "tests/test_opencode_rust_coverage_toolchain_contract.py"
       - "scripts/ci/materialize_base_javascript_packages.py"
@@ -185,6 +190,11 @@ jobs:
                 noema_suite=true
                 ;;
               .github/workflows/opencode-review-dispatch.yml|\
+              scripts/ci/run_opencode_review_model_pool.sh|\
+              scripts/ci/opencode_failure_envelope.py|\
+              tests/test_opencode_model_pool_runner.py|\
+              tests/test_opencode_failure_envelope.py|\
+              docs/doctoring/opencode-provider-failure-envelope.md|\
               scripts/ci/ensure_rust_llvm19.sh|\
               tests/test_opencode_rust_coverage_toolchain_contract.py|\
               scripts/ci/materialize_base_javascript_packages.py|\
@@ -357,6 +367,24 @@ jobs:
           python -m pytest -q tests/test_javascript_materializer_docstrings.py
           python -m compileall -q scripts/ci/materialize_base_javascript_packages.py tests/test_javascript_materializer_docstrings.py
 
+      - name: Verify OpenCode provider failure envelope
+        if: steps.affected_suites.outputs.opencode == 'true'
+        run: |
+          set -euo pipefail
+          PYTHONPATH=. python -m pytest -q \
+            --cov=scripts.ci.opencode_failure_envelope \
+            --cov-branch \
+            --cov-fail-under=100 \
+            tests/test_opencode_failure_envelope.py \
+            tests/test_opencode_model_pool_runner.py
+          python -m interrogate --fail-under 100 \
+            scripts/ci/opencode_failure_envelope.py
+          python -m compileall -q \
+            scripts/ci/opencode_failure_envelope.py \
+            tests/test_opencode_failure_envelope.py \
+            tests/test_opencode_model_pool_runner.py
+          bash -n scripts/ci/run_opencode_review_model_pool.sh
+
       - name: Verify exact-head path policy and syntax
         if: steps.affected_suites.outputs.strix == 'true'
         env:

.github/workflows/opencode-review-dispatch.yml

@@ -2641,6 +2641,7 @@ jobs:
               ContextualWisdomLab/.github:scripts/ci/pr_head_replay_guard.py | \
               ContextualWisdomLab/.github:scripts/ci/pr_review_merge_scheduler.py | \
               ContextualWisdomLab/.github:scripts/ci/run_opencode_review_model_pool.sh | \
+              ContextualWisdomLab/.github:scripts/ci/opencode_failure_envelope.py | \
               ContextualWisdomLab/.github:scripts/ci/opencode_review_normalize_output.py | \
               ContextualWisdomLab/.github:scripts/ci/strix_quick_gate.sh | \
               ContextualWisdomLab/.github:scripts/ci/validate_opencode_failed_check_review.sh | \
@@ -2649,6 +2650,7 @@ jobs:
               ContextualWisdomLab/.github:tests/test_materialize_base_javascript_packages.py | \
               ContextualWisdomLab/.github:tests/test_opencode_agent_contract.py | \
               ContextualWisdomLab/.github:tests/test_opencode_model_pool_runner.py | \
+              ContextualWisdomLab/.github:tests/test_opencode_failure_envelope.py | \
               ContextualWisdomLab/.github:tests/test_pr_head_replay_guard.py | \
               ContextualWisdomLab/.github:tests/test_pr_review_fix_scheduler_coverage.py | \
               ContextualWisdomLab/.github:tests/test_pr_review_merge_scheduler.py | \

CHANGELOG.md

@@ -1,3 +1,16 @@
+### OpenCode failures retain bounded causal telemetry
+
+- `run_opencode_review_model_pool.sh` now measures each failed invocation and
+  delegates its diagnostic to `opencode_failure_envelope.py`. The parser reads
+  only the bounded OpenCode error event and the gateway's canonical
+  `error.detail` receipt, then emits explicit phase, normalized cause,
+  provider, HTTP status, exception class, duration, and served-model fields.
+  Raw provider messages, bodies, prompts, credentials, headers, and arbitrary
+  nested values remain suppressed; malformed or missing fields become fixed
+  classifications or `unknown`, and review exhaustion remains fail-closed.
+  The dedicated runtime-quality lane now owns the runner, parser, and fixtures
+  with 100% statement/branch and public-doc coverage. Refs #2112.
+
 ### Failed-check finding names the Strix sandbox instead of the gateway
 
 - `opencode-review-dispatch.yml`'s `emit_strix_provider_failure_finding` rendered one fixed finding for every `STRIX_PROVIDER_UNAVAILABLE` line, whose Root cause read "The contextual-orchestrator gateway or its discovered provider pool was unavailable for this run". `#1953` had just given the Strix sandbox bootstrap failure its own second verdict token (`STRIX_SANDBOX_UNAVAILABLE`) precisely because that attribution is wrong for it -- the sandbox container never reaches its Caido proxy, so the run dies before the gateway serves anything -- and this consumer re-applied the wrong attribution one step downstream, into the review findings and the failure census. The emitter now branches on the second token: a sandbox verdict gets a finding that names Strix's sandbox, says the verdict does not name the gateway, and tells the reader not to change gateway or provider configuration on its strength. A `STRIX_PROVIDER_UNAVAILABLE` line without the token keeps its existing text verbatim, so the gateway class has no regression surface. No test covered this finding text at all before (`gateway or its discovered provider pool` matched nothing under `tests/`); `tests/test_opencode_dispatch_strix_sandbox_finding.py` now runs the production emitter from the published run block and pins both directions plus the no-signal case. Refs #1953, #1935.

docs/doctoring/opencode-provider-failure-envelope.md

@@ -0,0 +1,64 @@
+# OpenCode provider-failure envelope
+
+## Problem and exact evidence
+
+On 2026-09-12, `.github` PR
+[`#2106`](https://github.com/ContextualWisdomLab/.github/pull/2106) at exact
+head `24bb6591ab7df23558cb793b4af60c567ff9da97` reached the single required
+`contextual-orchestrator/orchestrator/free` model route in OpenCode run
+[`34693400612`](https://github.com/ContextualWisdomLab/.github/actions/runs/34693400612).
+The request failed after the sidecar and route preflight had succeeded, but the
+only surviving causal evidence was `class=provider-error`, two byte counts,
+and a statement that provider content was suppressed. That was enough to keep
+the review fail-closed, but not enough to distinguish queue admission, HTTP
+429/5xx, request size, malformed JSON, route exhaustion, or missing serving
+identity. Issue
+[`#2112`](https://github.com/ContextualWisdomLab/.github/issues/2112) owns the
+repair.
+
+## Constraints
+
+- OpenCode, Noema, and Strix keep the single `orchestrator/free` gateway route;
+  no provider/model/group override or paid fallback is introduced.
+- Telemetry is diagnostic only. It cannot produce approval, clean evidence, a
+  retry, a timeout, or a merge bypass.
+- Provider-controlled messages, bodies, prompts, credentials, headers, source
+  text, and arbitrary nested payloads never reach stdout, status text, or
+  annotations.
+- Values that survive are bounded scalar identifiers or validated HTTP status
+  numbers. Missing or invalid fields are explicit `unknown` values.
+
+## Alternatives and decision
+
+Keeping the previous byte-count-only line was rejected because it preserves
+secrecy at the cost of causal attribution. Printing the raw OpenCode event or
+gateway response was rejected because public `pull_request_target` logs cannot
+safely carry provider-controlled text. Adding caller-side retries or an
+elapsed-time diagnosis was rejected because the gateway owns routing and the
+observed five-second failure did not prove a timeout.
+
+The selected design adds a small standard-library parser at the OpenCode
+adapter boundary. It reads at most 65,537 bytes from each failure artifact and
+accepts only an OpenCode `type=error` event. From the gateway response it reads
+only the canonical `error.detail`/`error_detail` receipt and its last bounded
+attempt. The emitted line preserves class, phase, normalized reason, provider,
+HTTP status, exception class, elapsed seconds, served model, and artifact byte
+counts. Malformed JSON and malformed Unicode fail closed to bounded metadata.
+
+## Executable evidence, risks, and effects
+
+The production launcher fixtures cover HTTP 429/queue capacity, provider 503,
+non-JSON response bodies, HTTP 413 request admission, no eligible route, absent
+served-model metadata, and secret-bearing ignored fields. Unit tests cover all
+parser statements and branches, and the consolidated runtime-quality workflow
+selects this suite whenever the launcher, parser, fixture, or this authority
+record changes.
+
+The remaining risk is semantic drift in the gateway receipt. Unknown fields
+are deliberately not guessed or copied; a future versioned schema change must
+add a failing fixture before extending the allowlist. Operators can now route a
+429/queue failure to capacity policy, a 5xx to the gateway/provider boundary,
+a 413 to request admission, and malformed JSON to the response adapter without
+reading secret-bearing bodies. Until exact-head hosted checks, independent
+review, protected-main integration, and an unchanged-head replay of #2106 are
+complete, this repair remains Proposed rather than released evidence.

docs/product-technical-gap-baseline.md

@@ -3353,3 +3353,28 @@ queries the check-runs API at its own time, order-independently. The implementin
 their change was safe because they had scoped it narrowly, not because they had checked for the name
 collision — which is the more useful lesson: **a job name is unique only within one workflow file, and the
 same name in another file can carry the opposite safety property.**
+
+## OpenCode provider-failure causal envelope — 2026-09-12
+
+**Status: Proposed; owner repair implemented on the issue branch, not yet
+protected or released.** `.github#2106@24bb6591ab7df23558cb793b4af60c567ff9da97`
+had five exact-head security/runtime checks succeed, then OpenCode run
+`34693400612` exhausted after emitting only `class=provider-error` and byte
+counts. The absence of safe phase/provider/status/model evidence made the
+failure causally ambiguous; it did not prove the separate timeout defect.
+
+Issue `.github#2112` now has an executable RED→GREEN owner repair. The OpenCode
+adapter parses only a bounded error event and canonical gateway receipt, emits
+explicit class/phase/reason/provider/status/exception/duration/served-model
+scalars, suppresses raw provider content, and remains fail-closed. Production
+fixtures cover 429, 5xx, malformed JSON, 413, pool exhaustion, missing serving
+identity, and secret-bearing ignored fields. The previously missing CI
+ownership is also repaired: launcher/parser/test/doc changes select the
+dedicated runtime-quality suite, which enforces 100% parser statement/branch
+and public-doc coverage.
+
+**Remaining action:** obtain exact-head hosted checks and independent review,
+merge normally to protected `main`, then replay #2106 unchanged. Only that
+consumer replay can show whether the next real failure contains enough bounded
+causal evidence; this Proposed branch is not immutable release or production
+proof.