[diegosouzapw]

Closes #12783

Root cause

Two compounding bugs in the setup-opencode CLI path:

1. Flag collision: bin/cli/program.mjs registers a top-level --api-key <key> option bound to .env("OMNIROUTE_API_KEY"). Commander parses that flag against the ancestor program regardless of where it appears in argv, so omniroute setup-opencode --remote <url> --api-key sk-... stores the value on program.opts().apiKey, never on setup-opencode's own local --api-key option. The action handler only read its own local opts, so opts.apiKey was always undefined even when the user explicitly passed the flag.
2. Precedence bug: resolveOpencodeTarget() tried the active context's accessToken/apiKey before falling back to process.env.OMNIROUTE_API_KEY. A CLI management token (oma_live_...) has no /v1/* inference scope, so a purely env-var-supplied inference key also lost to the context's management token — causing the reported 401 from /v1/models.

Fix

• registerSetupOpencode's action handler now reads cmd.optsWithGlobals().apiKey (falling back to the local opts.apiKey) so the CLI-supplied value — wherever Commander actually stored it — reaches resolveOpencodeTarget().
• resolveOpencodeTarget() now checks the explicit flag, then OMNIROUTE_API_KEY, and only then the active context's token — matching the explicit > ambient-env > context precedence already documented and used by bin/cli/api.mjs's buildHeaders().

Regression test (TDD)

tests/unit/repro-12783-setup-opencode-apikey.test.ts:

• RED (pre-fix, confirmed via the plan-file's probe worktree): capturedLocalApiKey stayed undefined while program.opts().apiKey held the passed sk-... value.
• GREEN (post-fix): 5/5 tests pass — the CLI-supplied --api-key reaches the action handler, and resolveOpencodeTarget() is unit-tested directly for all three precedence cases (flag > context, env > context, context-only fallback) plus the empty-fallback case.

✔ setup-opencode: --api-key typed AFTER the subcommand name is not stolen by the parent program's global option
✔ resolveOpencodeTarget: (a) explicit --api-key flag wins over an active context's management token
✔ resolveOpencodeTarget: (b) OMNIROUTE_API_KEY env wins over an active context's management token when no flag is passed
✔ resolveOpencodeTarget: (c) the context's token is used only when neither a flag nor the env var is set
✔ resolveOpencodeTarget: falls back to '' when neither a flag, env var, nor a resolvable context is present
ℹ tests 5, pass 5, fail 0

Gates run

• node scripts/check/check-file-size.mjs → OK
• node scripts/check/check-complexity.mjs → OK (2798 violations, baseline 3218)
• node scripts/check/check-cognitive-complexity.mjs → OK (1265 violations, baseline 1437)
• npm run typecheck:core → clean, no errors
• npx eslint --suppressions-location config/quality/eslint-suppressions.json <changed files> → 0 errors (bin/** is globally eslint-ignored in this project; only the new test file is linted)
• New regression test: node --import tsx/esm --test tests/unit/repro-12783-setup-opencode-apikey.test.ts → 5/5 pass
• Existing tests of the touched area: tests/unit/cli/setup-opencode.test.ts, tests/unit/cli-setup-opencode.test.ts, tests/unit/cli/alias-resolver-7791.test.ts, tests/unit/opencode-target-format-alias-11045.test.ts, tests/unit/api/cli-tools/apply-container-guard.test.ts → 41/41 pass
• node scripts/check/check-changelog-integrity.mjs → OK

Scope note

The same local-flag-collides-with-global-flag pattern exists in several other setup-* commands (e.g. setup-claude.mjs), but the plan-file for #12783 scopes this fix to setup-opencode.mjs only — left untouched here to keep the diff surgical to the reported issue.

⚠️ base-red inherited: #12732 — unit #12058, integration codex-cache, package-artifact, tarball-smoke, agent-skills-sync