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 | \

.gitleaks.toml

@@ -16,3 +16,13 @@ regexes = [
   '''gh[pousr]_(?:1234567890abcdef(?:1234)?|abcdef1234567890abcdef1234567890abcdef|installation_token_value|user_token_value|server_token_value|runner_token_value|placeholder_token_with_underscores_123|[a-z]{16}|[a-z]{20}|[a-z]{30}|[a-z]{38})''',
   '''github_pat_11AAAAA_(?:abcdefg|abcdefg1234567890|[A-Za-z]{7}_[a-z]{7}|[A-Za-z]{7}_[a-z]{17})''',
 ]
+
+[[allowlists]]
+description = "OpenCode synthetic unknown-provenance token used only by confidentiality regressions."
+condition = "AND"
+regexTarget = "secret"
+paths = [
+  '''(^|/)tests/test_opencode_failure_envelope\.py$''',
+  '''(^|/)tests/test_opencode_model_pool_runner\.py$''',
+]
+regexes = ['''^BYTEZ_TEST_SECRET_[1]234567890$''']

CHANGELOG.d/20260912-opencode-provider-failure-telemetry.md

@@ -0,0 +1 @@
+Preserve bounded phase, reason, HTTP status, and duration evidence for OpenCode gateway failures while suppressing raw provider content and unverified provider/model identifiers and capping failure input.

CHANGELOG.md

@@ -1,3 +1,19 @@
+### 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 final 16 KiB of the OpenCode error stream and up to 16 KiB of the gateway's
+  canonical `error.detail` receipt. Failure class comes only from allowlisted
+  structured status/reason semantics and validated HTTP status. Phase uses a
+  fixed public enum; provider, exception, and served model remain `unknown`
+  until an immutable CO receipt/catalog proves their provenance. Raw prose and
+  lexically valid unknown identifiers cannot influence or enter diagnostics.
+  Oversized, contradictory, deeply nested, malformed, or missing fields fail
+  closed; a malformed canonical body also suppresses outer status/reason
+  authority, and review exhaustion remains nonzero.
+  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/adr/0003-contextual-orchestrator-vendored-free-zdr.md

@@ -282,3 +282,21 @@ all five, and auto-optimize routing by cost.
   per-agent attempt; it changes only *which* agent gets tried next, never any
   per-attempt timeout, consistent with the 2026-08-31 amendment above. No
   other contextual-orchestrator behavior changes with this pin advance.
+
+- **2026-09-12 proposed amendment: preserve redaction-safe OpenCode failure
+  provenance.** The OpenCode model-pool adapter must keep the gateway-owned
+  canonical `error.detail` receipt useful after suppressing raw provider
+  content. For a bounded structured error it emits only allowlisted phase,
+  normalized reason, HTTP status, and caller-measured duration. Provider and
+  served-model identifiers remain `unknown` until a versioned CO-issued
+  non-secret identifier contract can be validated locally. Unknown, malformed,
+  and absent fields become fixed `unknown`/`malformed_response`
+  values; arbitrary
+  messages, response bodies, headers, credentials, and unbounded identifiers
+  never reach public Actions logs. The adapter reads at most the final 16 KiB
+  of the JSONL failure stream, suppresses unverified identifier values, and
+  parses at most 16 KiB from the nested canonical gateway body. Larger gateway
+  bodies and deeply nested envelopes fail closed to the fixed malformed state.
+  This does not add a retry, timeout, provider choice, or model policy
+  to `.github`; contextual-orchestrator remains the owner of discovery,
+  routing, and failover.

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

@@ -0,0 +1,74 @@
+# 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.
+- Only exact allowlisted phase/reason enums and validated HTTP status numbers
+  may enter causal output. Lexically valid but unproven identifiers are not
+  evidence of non-secret provenance. Provider, model, and exception identities
+  remain `unknown` until an immutable CO receipt/catalog proves them.
+
+## 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 the final 16 KiB of each failure artifact,
+drops an incomplete leading line, and accepts only an OpenCode `type=error`
+event within an explicit 64-level structural-depth limit. From the gateway response it parses
+at most 16 KiB and reads only the canonical `error.detail`/`error_detail`
+receipt and its last bounded attempt. Only allowlisted structured status/reason
+pairs determine failure class; contradictory pairs become `provider-error`.
+Phase is emitted only when it matches a fixed public enum. Provider, exception,
+and served model remain `unknown` because this consumer has no immutable CO
+catalog proof that can authenticate dynamic identities. Raw
+event/stderr bytes are represented only by presence and byte counts, never
+passed to the causal classifier. Oversized gateway bodies, deeply nested or
+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, contradictory structured causes, raw prose pollution,
+unproven identifier provenance, 16 KiB overflow, excessive JSON depth, 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 and missing identity provenance in the
+gateway receipt. Unknown fields are deliberately not guessed or copied; a
+future immutable CO schema/catalog change must add a failing fixture before an
+identity or enum enters 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,35 @@ 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.** `ContextualWisdomLab/.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 `ContextualWisdomLab/.github#2112` now has an executable RED→GREEN owner repair. The OpenCode
+adapter parses only the final 16 KiB error-event stream and at most 16 KiB of the canonical
+gateway receipt. Only allowlisted structured status/reason pairs determine
+failure class; fixed enums bound phase/reason, while provider, exception, and
+served model remain `unknown` until an immutable CO receipt/catalog contract
+authenticates them. Raw text, lexically valid unknown identifiers,
+contradictory evidence, bodies over 16 KiB, and 10,000-level JSON all fail
+closed. A malformed canonical body also suppresses outer `data.code` and HTTP
+status authority instead of allowing either to override the fixed malformed
+state. Production fixtures cover 429, 5xx, malformed JSON with conflicting
+outer authority, 413, pool exhaustion, unproven identity, causal pollution,
+and credential-shaped 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,
+define and release the versioned CO identity-provenance contract before exposing
+provider/model identity, 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.