[Moseyuh333]

⚠️ base-red inherited: #15306 (release/v3.8.52 is not release-green — the full unit suite and the package-artifact gates exceed their ceilings and one MCP vitest file fails on the base tip). None of those failures come from this branch; the focused suites listed below are green on it.

What

OpenCode Free (opencode, alias oc) and the free models of OpenCode Zen (opencode-zen) currently only work when the caller is the OpenCode CLI. A standalone OmniRoute install (plain OpenAI client, no OpenCode client headers, no tools) is answered:

403 {"error":{"type":"FreeTierError","message":"... OpenCode's free tier can only be used from within OpenCode"}}

Both providers share https://opencode.ai/zen/v1, and on that surface the upstream validates the request against the OpenCode client's own contract. Two of its four legs were missing here:

1. The tools list is a fingerprint, not a non-empty check. The upstream inspects the declared names and their casing. Measured live on 2026-10-02/03 over /chat/completions and /responses across 9 gated free models: an empty list, a lone _noop placeholder (what OmniRoute sent), a single client tool and the capitalised Bash spelling are all answered 403; the lowercase quartet bash, glob, grep, read is answered 200. Order is irrelevant and extra tools beside the quartet are accepted.
2. The x-opencode-session value is decoded, not just shape-checked. The 12 hex digits are read through the client's Identifier.descending() layout, where the low 12 bits carry 0xFFF - counter (counter is the within-millisecond sequence, 0-63), so only a low-12 landing in 0xFC0-0xFFF passes (measured 2026-10-13/14). OmniRoute's previous render — 12 arbitrary hex digits — satisfied the regex and was still refused.

How

• open-sse/executors/opencodeFreeTierContract.ts — OPENCODE_FREE_TIER_FINGERPRINT_TOOLS is added to every gated body when the caller's own list does not spell the four names exactly. The caller's entries are never renamed or dropped: a client that spells one differently (Bash from Claude Code) keeps its own entry and gains the canonical one next to it, which is what the measurement allows. The refusal-retry merge (mergeClientToolsWithObserved) restores the quartet too, and addsNothingBeyondFirstDispatch counts it as already sent so no request is wasted re-sending a shape the upstream just refused.
• open-sse/utils/opencodeHeaders.ts — canonicalId("ses_") now renders the hex half in the client's own descending layout (~(timestamp36 << 12 | counter), counter pinned to 1, timestamp taken from the conversation hash). It stays a pure function of the conversation seed, so prompt-cache affinity is preserved. forwardOpencodeClientHeaders({ reencodeSession }) re-mints a caller-supplied value that only matched the shape, deterministically from that value.
• open-sse/executors/opencode.ts — passes reencodeSession: gatedScope, i.e. only for the zen surface + non-premium model.

Live validation (executor driven against the real upstream, no mocks)

Both providers were exercised through the patched OpencodeExecutor from a standalone process (no OpenCode CLI in the loop, no credentials):

Provider	Model	Result	Request observed on the wire
opencode	deepseek-v4.1-flash-free	200, "OK"	POST https://opencode.ai/zen/v1/chat/completions, stream: true, tools bash,glob,grep,read,_noop, x-opencode-session: ses_…ffe…
opencode-zen	big-pickle	200, "OK"	same shape

The outgoing request was also compared against the one the real client sends: OpenCode CLI 1.19.0 was installed and pointed at a local logging proxy, and its captured request matches this branch's wire shape on every leg (endpoint, stream: true, session layout, x-opencode-client: desktop, x-opencode-project: global, x-opencode-request, User-Agent: opencode/<version>). The CLI additionally sends Authorization: Bearer public and x-opencode-session-id; neither is required for the upstream verdict — a request without them still answered 200 after a 12-minute idle window from the same egress, and the tool-less control in the same batch answered 403 — so they are deliberately not sent.

One honest caveat from that session: the gate answered 403 to every shape for a window of a few minutes — including shapes it answered 200 to minutes later and that the CLI itself accepts — while the tools rule held throughout (a tool-less body was refused before, during and after that window). So the upstream verdict is stable in the "what must be declared" dimension and evidently transient in another; the fix targets the former.

Scope boundaries (deliberate)

• No endpoint change. fix(opencode): follow the published endpoint and the client's own headers #16608 reports the client catalog moving to https://opencode.ai/inference/v1; that is a separate change with its own blast radius and stays out of this PR. (The live capture confirms the client uses that path, while both paths currently answer identically.)
• No catalog-driven free-model classification. isPremiumOpencodeModel keeps the -free suffix + known-set rules. Making it read the synced catalog means importing src/lib/* from open-sse/executors/*, which is exactly the coupling scripts/quality/measure-boundary.mjs tracks as "should trend to zero" for v4 — the right home is a follow-up that passes the classification into the engine from the app layer. fix(providers): mint OpenCode free-tier sessions with the client's descending Identifier encoding #16598 already carries that half.
• opencode-go and paid models untouched (go refuses requests carrying tools — upstream Zen API: x-preview-f-free / ox-alpha-free fails with "Endpoint is unavailable" for any request containing tools anomalyco/opencode#44300/#44382), and non-OpenAI body formats still only get stream: true (the tool shapes are unmeasured there).
• The bare probe path is unchanged. It is the store's adaptive attempt at a tool-less shape; the quartet is injected on the tools shape only.

Tests

TDD: tests/unit/opencode-standalone-free-tier-16571.test.ts was written first and ran red (10 of 12 failing; the 2 green ones are the negative controls that must keep passing), then the fix made it green (14/14). It covers both providers, both surfaces (/chat/completions + /responses), the client-tool-preservation rule, idempotence, the retry merge, the re-mint determinism, the opencode-go exclusion, and one end-to-end execute() assertion that the outgoing request carries all four legs.

Existing suites touched by the new baseline were updated, never weakened (per-file assertion counts are equal or higher):

node --import tsx/esm --test tests/unit/opencode-standalone-free-tier-16571.test.ts   # 14 pass
node --import tsx/esm --test <all tests/unit/opencode-*.test.ts>                      # 865 pass, 0 fail
node --import tsx/esm --test tests/unit/{db-proxies-ventilated,refactor-opencodeHeaders,session-affinity-generic-7274}.test.ts  # 49 pass
npm run typecheck:core                                                                # clean
npx eslint <changed files>                                                            # clean
npm run check:docs-all                                                                # pass
npm run check:changelog-integrity                                                      # OK
node scripts/check/check-test-masking.mjs   # OK — nothing weakened

The two failures this branch's npm run test:vitest run reports (tests/unit/autoCombo/tieredRotation.test.ts, open-sse/services/autoCombo/__tests__/pipeline-router-taskfitness-mismatch.test.ts) are timeouts under a loaded machine — they pass when re-run on their own — and belong to the base-red set tracked in #15306, not to this change, which touches no autoCombo path.

Overlap with in-flight PRs (no code copied, independent implementation)

• fix(providers): mint OpenCode free-tier sessions with the client's descending Identifier encoding #16598 — session value encoding + catalog classification. The encoding is a measured fact, so the two implementations necessarily agree on it; ours differs in structure (it re-encodes only on the gated path via an option instead of at every mint) and does not duplicate the classification half.
• fix(opencode): declare the free-tier tool fingerprint the upstream requires #15322 — tool fingerprint. It also renames the caller's entries and restores them on the response; this PR stays additive (which the measurement allows) and touches no response path.
• fix(opencode): follow the published endpoint and the client's own headers #16608 — endpoint change, deliberately out of scope.

Closes #16571, #16328.

Changelog

changelog.d/fixes/0000-opencode-free-tier-standalone.md

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Moseyuh333]

Closing as superseded — release/v3.8.52 now serves the standalone free-tier path itself.

What landed elsewhere (all merged 2026-10-16):

• fix(providers): mint OpenCode free-tier sessions with the client's descending Identifier encoding #16598 — session minting/re-encode through the client's Identifier.descending() encoding (reencodeSession).
• fix(opencode): serve the gated free tier from /inference/v1 and give placeholder tools non-empty schemas #16826 — gated free tier served from /inference/v1, placeholder tools with non-empty parameter schemas.
• fix(providers): use genuine tool name for opencode free-tier contract (#13935) #16858 — genuine tool name for the free-tier contract.

Live check today against the release tip (3c3edb9e) — fresh process, no OpenCode CLI headers, no credentials, OpencodeExecutor called directly:

• opencode + big-pickle → 200 OK, session ses_…ffe…, UA opencode/1.18.31, endpoint /inference/v1/chat/completions, tools ["read"].
• opencode-zen + big-pickle → 200 OK.
• Declared-tool shapes: none / capitalised Bash,Glob,Grep,Read (Claude Code style) / lowercase quartet / single custom tool / empty schemas / entries without parameters → 7/7 × 200.

The remaining delta in this PR was the tool-fingerprint quartet measured on 2026-10-02/03; the current gate is satisfied by the release branch's single read placeholder with a real schema, so this PR is redundant. Thanks for moving the fix through.