feat(orchestrator): Add OpenCode 2 provider support

[mwolson]

Summary

• Add OpenCode 2.x as a preview provider alongside the existing OpenCode 1.x
  provider, using a separate opencode2 driver/runtime/adapter and
  @opencode-ai/sdk-next/v2 (this branch is the sole consumer of the pin
  npm:@opencode-ai/sdk@0.0.0-beta-202608061351).
• Cover the provider end to end across server orchestration, text generation,
  provider settings, model selection, reasoning variants, Build/Plan mode,
  permissions, questions, Queue, Stop, background work, subagents, lineage,
  replay, web, desktop, and mobile.
• Keep incomplete startup catalogs private until a bounded settlement check has
  observed a complete, stable inventory.
• Dual-normalize a moving upstream wire: next-16916 short event names
  (session.step.*, session.text.*, tools, session.execution.interrupted)
  plus earlier beta session.next.* aliases, including tool call keys from
  data.id when callID is absent.
• Prefer an exact CLI pin while the OpenCode 2 API is in flux. Verified against
  opencode2 v0.0.0-next-16916 (@opencode-ai/cli@0.0.0-next-16916), not a
  floating @next install. Channel advisories for @opencode-ai/cli@next remain
  available for recognized package managers, but operators should pin the binary
  they validate against.

This draft targets t3code/codex-turn-mapping.

Problem and Fix

Problem and Why it Happened	Fix
OpenCode 2 changed its startup banner, mandatory server authentication, HTTP routes, SDK, and event vocabulary. Treating it as another binary path for the existing OpenCode driver would conflate incompatible protocols.	Add a separate opencode2 driver, runtime, adapter, provider layer, and text-generation backend using @opencode-ai/sdk-next/v2. OpenCode 1.x remains unchanged and both providers can be configured together.
The ready banner can arrive before plugins and authenticated model integrations finish loading, so the first non-empty inventory can be incomplete.	Read models, agents, and integrations concurrently; observe stable snapshots behind a 500ms minimum window; require quiet confirmation before publication; fall back to the latest confirmed deadline snapshot rather than a final one-off change.
Provider-native background work and subagents outlive ordinary turns and can be stopped from a settled parent or projected child thread. Generic run-only cancellation cannot identify those targets safely.	Project native lineage and shell ownership, preserve post-settlement waiting and wake behavior, and route Stop to the exact active child or shell while excluding siblings.
OpenCode 2 exposes reasoning as model variants, owns Build/Plan as native agents, and asks questions on the question / question.v2 wire (not the removed form API).	Map questions through the existing question surface with truthful single- and multi-answer shapes on web and mobile, validate variants against the settled catalog, and map the shared interaction-mode toggle to native Build/Plan agents while retaining custom-agent selection.
Generic provider advisories query npm's stable latest channel, while OpenCode 2 ships on next and the wire moves between next builds; blindly floating @next can break the adapter, and an npm update may not own the configured executable.	Resolve advisories from the npm next dist-tag with a channel-isolated cache key. Offer one-click updates only for recognized npm, Bun, pnpm, and Vite Plus paths; keep custom paths and external servers manual-only. Document and prefer an exact CLI pin (currently 0.0.0-next-16916) for environments that need a known contract.
The provider must remain truthful on every client while its first inventory check is pending and while Queue or Stop changes durable orchestration state.	Add provider metadata, icons, settings, instance-aware model picker behavior, mobile composer support, Queue controls, Stop presentation, and replay-backed projections across shared client state.

Defensive Fixes

Risk	Fix
A failed, interrupted, or timed-out spawned server could leave child processes behind, including descendants that outlive their wrapper.	Register scoped process-group cleanup atomically with spawn, keep output drained, detect parent replacement, verify the whole process group during bounded escalation, and terminate abandoned or control-channel-broken reaper sidecars.
An unknown reasoning variant is accepted by the server but can silently swallow the next prompt.	Clamp explicit variants against the settled catalog and fall back to the server default when the selection cannot be validated.
The npm package ships opencode2.exe as a placeholder that requires postinstall replacement, and Bun blocks dependency lifecycle scripts unless the package is trusted.	Mark the package as lifecycle-dependent, use Bun's --trust and pnpm's package-scoped build approval, and preserve the default script-running behavior for npm and Vite Plus.
OpenCode's prerelease identifiers contain a second hyphen, which the shared semver normalizer previously truncated before comparison.	Preserve the complete prerelease suffix so development builds such as next-16691 and next-16694 produce the correct advisory state.
Late, replayed, or out-of-order native events could duplicate wakes, reflect stale interaction mode, revive stopped work, or collide across threads.	Claim delayed replay events before waiting, scope reflection receipts by thread, retain terminal ownership state, and cover delayed completion, recovery ordering, sibling isolation, and retired sessions.
Startup and SDK diagnostics can contain credentials or conflate an HTTP 404 with a missing executable.	Use schema-backed errors with bounded operations and safe categories; retain package, authentication, and network guidance without copying raw causes or the minted server password into Settings or logs.
A failed startup, widely separated banner credentials, or shared remembered permissions could retain the wrong process or authority boundary.	Give each startup an eagerly closed child scope, retain URL and password facts independently of the bounded diagnostic buffer, and key remembered grants by native session with wildcard normalization.
Replay terminal state and delayed SDK failures could strand concurrent consumers or let a poisoned controller consume more transcript entries.	Fan successful exit out to every subscriber, claim delayed failures until their delay completes, and reject outbound frames immediately after any stored replay failure.
A shared text-generation server could exit after startup while its cached URL remained reusable, and a continuously changing startup catalog has no truthful settled snapshot.	Check cached process liveness under the shared-server mutex and replace dead children once; fail provider settlement with a static typed error only when no inventory fingerprint ever becomes quiet.
Provider-owned form keys and custom answers can use names inherited from ordinary JavaScript objects, such as __proto__, constructor, and toString.	Build option lookups and form replies as null-prototype records, and require own lookup properties, so arbitrary names remain serializable data and custom text cannot resolve through Object.prototype.
A child that exits before startup readiness has a typed exit code but no underlying thrown failure.	Keep the exit code structural and omit the duplicate synthetic error cause; focused coverage asserts both facts.
Shared multiselect question support was complete below the Grok adapter, but that adapter replaced every extracted value with false.	Preserve normalized native multiplicity at the adapter boundary and prove a Grok multiselect request reaches the shared user-input surface as multiselect.
An external OpenCode 2 server could report an older next build and bypass the adapter's verified protocol floor.	Apply the same minimum build to local and external servers, with package-manager guidance locally and configured-server guidance remotely.
The thread-deletion replay described an idle release before detach but only asserted that both events existed.	Compare their event indices so the fixture proves its stopped update precedes provider-session detach.
The queued-subagent replay accepted a terminal first update because its empty prefix check passed vacuously.	Require a pending or running update before the first terminal child status.
Missing double-wrapped SDK payloads threw inside Effect callbacks and became defects instead of typed provider failures.	Make response unwrapping effectful and consume it with yield* or Effect.flatMap at every adapter and test boundary.
Live-test layer aliases obscured the new Effect service module namespace and left its consumers inconsistent.	Preserve the OpenCode2Runtime namespace across all seven PR-owned live-test consumers and qualify its layer, service tag, helper, and tagged error exports.
The automatic permission-reply warning routed a typed OpenCode 2 error through a free-form diagnostic helper.	Log bounded category and operation fields directly, preserving useful diagnostics without coupling the log to an error message or nested provider cause.
A snapshot-build wrapper still copied arbitrary cause text into caller-visible provider detail.	Keep the public detail static and preserve the complete diagnostic only in the structured cause chain.
A healthy server with a never-stable inventory was reported as a CLI health-check failure.	Classify inventory-settlement exhaustion explicitly and report the catalog instability without incorrect health-check guidance.
A complete startup banner could win its deferred race after the process tree had already exited.	Recheck process-tree liveness before returning credentials, using process-group liveness on POSIX and direct-child liveness on Windows.
Three transient initial reaper sidecar spawn failures could leave a still-tracked workload unprotected indefinitely.	Pause for the crash-loop window, reset the initial spawn budget, and retry the same tracked workload after the cooldown.

UI Changes

Before this change, T3 Code had no OpenCode 2 provider entry. After the change,
OpenCode 2 appears as a distinct Preview provider in Settings and the model
picker, with its own icon, provider instances, reasoning selector, Build/Plan
mapping, Queue controls, Stop states, provider-native child lineage, and the
shared one-click update action when its executable belongs to a recognized
package manager. Its icons use OpenCode's blue dev treatment because OpenCode
2 is distributed on OpenCode's development release track.

Baseline settlement:

• Scenario 1: Tool turn settles with its output
• Scenario 2: Follow-up settles on a distinct run

Queue:

• Scenario 1: Queued follow-up waits for natural settlement
• Scenario 2: Queue a follow-up, then Stop on mobile
• Scenario 3: Manage and reorder multiple queued messages
• Scenario 4: Promote a queued message to Steer

Subagents and background work:

• Scenario 1: Background subagent launch and post-settle wake
• Scenario 2: Queued follow-up overlaps background work
• Scenario 3: Foreground subagent honors Full access
• Scenario 4: Supervised subagent permission resumes once
• Scenario 5: Concurrent children isolate lifecycle and rate limits
• Scenario 6: Stop while a foreground subagent command runs
• Scenario 7: Stop a detached child from the settled parent
• Scenario 8: Stop a detached child from its own thread
• Scenario 9: Stop one detached child without stopping its sibling
• Scenario 10: Stop a nested child from its direct parent

Direct Stop and recovery:

• Scenario 1: Stop while a command is running
• Scenario 2: First recovery lands on a new run
• Scenario 3: Second recovery remains distinct

The linked guide contains copyable prompts and expected UI outcomes for desktop,
web, and mobile. Packaged desktop verification covered provider setup, the
settled authenticated catalog, Queue to Steer, and multi-item Queue editing and
reordering. The Stop and nested-child rows are backed by the automated and
headless coverage below; their packaged UI prompts remain in the guide for the
draft review pass.

Startup Performance

Historical cold-start numbers measured with opencode2 v0.0.0-next-16694
(earlier than the current verified pin 0.0.0-next-16916) using isolated,
test-owned process groups, ephemeral ports, and empty temporary working
directories:

• 20 cold starts reached server-banner readiness in 577ms median, 625ms p95, and
  630ms maximum.
• The complete usable catalog appeared 522ms median, 537ms p95, and 556ms
  maximum after banner readiness.
• All 20 runs converged to the same 108-model, 7-agent catalog with two
  connected integrations. Every inventory accepted by the production 500ms floor
  and matching-snapshot rule matched the inventory observed at 5.5 seconds; the
  latest acceptance was 649ms after banner readiness.
• 10 full source-level provider checks completed in 1.722s to 1.859s, with a
  1.779s median. Every check reported ready with all 108 models.

These measurements did not read T3 userdata or interact with a running desktop
application.

Validation

• vp check: pass, with pre-existing warnings only

• vp run typecheck: reaches all 15 tasks; the only error is in unchanged base
  apps/server/src/httpCompression/HttpResponseCompression.ts:33

• vp run build:desktop: pass

• vp run test: pass across all 14 test packages; server result was 2,157
  passed with 16 environment-gated skips

• node scripts/release-smoke.ts: pass

• Focused orchestration Stop coverage: 242 tests pass

• Changed-surface regression run: 505 tests pass with 10 environment-gated skips

• Focused provider-maintenance, OpenCode 2 driver/provider, and shared semver
  coverage: 52 tests pass across four files

• Review-repair regression coverage: 150 focused tests pass across eight files
  with three real-binary adapter cases gated; seven selected replay fixtures
  also pass

• Round B review-repair coverage: 143 focused tests pass across 13 files,
  including multiselect forms on web and mobile, replay concurrency, Stop
  targeting, stale refresh rejection, and reaper failure handling

• Round C review-repair coverage: 254 focused tests pass across 12 server, web,
  and mobile files, including direct tagged-error status formatting, the
  generic unparseable-health diagnostic, all 98 replay integration scenarios,
  and the replay transcript contract

• Round D review-repair coverage: 109 focused tests pass across five directly
  affected files, all 98 replay integration scenarios pass, and eight replay
  transcript contract and NDJSON tests pass

• Round E review-repair coverage: 52 focused tests pass across the OpenCode 2
  runtime, text-generation, and provider files, including concurrent dead-server
  replacement and inventory deadline stability

• Round F review-repair coverage: all seven form helper tests pass, including
  hostile field keys, inherited-name custom answers, and JSON serialization

• Round G review-repair coverage: 25 OpenCode 2 runtime and form tests pass;
  32 focused form, model-picker, and composer tests pass on the rebased base

• Round H review-repair coverage: all 16 OpenCode 2 agent-selection and provider
  cache tests pass for complete, Build-only, and Plan-only inventories

• Rounds I and J review-repair coverage: 101 focused Grok adapter, xAI
  extractor/encoder, and OpenCode 2 provider-status tests pass

• Round K review-repair coverage: the focused OpenCode 2 thread-deletion replay
  passes with an explicit stopped-before-detach assertion

• Round L review-repair coverage: all 152 OpenCode 2 adapter and replay tests
  pass, including typed missing-payload failures and the queued-subagent
  launch-acknowledgement invariant

• Round M review-repair coverage: all seven affected live-test modules import
  successfully; three tests pass and ten real-runtime tests remain gated by
  their existing environment flags

• Round N review-repair coverage: both automatic permission-reply failure
  replays pass with bounded structural warning annotations

• Rounds O and P review-repair coverage: 118 focused OpenCode 2 driver,
  provider, runtime, reaper, and registry tests pass, including inventory
  instability, dead-after-banner startup, bounded snapshot diagnostics, and
  same-workload recovery after the reaper cooldown

• Current-head Macroscope Effect Service Conventions reports All clear, and
  Correctness reports no issues after reviewing 445 code objects

• PR-wide TypeScript AST ternary audit: all 170 changed JavaScript and
  TypeScript files parsed; zero PR-added nested conditional expressions remain
  at depth 2 or greater, including zero at depth 3 or greater

• Full typecheck was run on the rebased tree and reaches all 15 tasks; the only
  error is in unchanged updated-base
  apps/server/src/httpCompression/HttpResponseCompression.ts:33

• CI Release Smoke and Mobile Native Static Analysis pass

• CI Test reports 1,820 passing web tests and two locally reproduced failures
  in unchanged updated-base ProjectScriptsControl.test.tsx

• Current-head CI Check passes; an earlier head reached only the known Vite+
  warning-output panic with Resource temporarily unavailable (os error 11)

• Isolated Bun-managed spawned-server runtime: pass with fresh HOME and XDG
  directories under the parent workspace tmp/

• Real Bun 1.3.14 isolated-global update: opencode2 advanced from next-16691
  to next-16694 with bun add -g --trust @opencode-ai/cli@next; the resulting
  package bin is the platform ELF executable, not the shell placeholder

• Real OpenCode 2 Queue packs pass for multi-item controls and Queue promotion
  to Steer; packaged command logs confirm durable edit and reorder receipts

• Real OpenCode 2 Stop coverage passes for direct Stop, queued recovery,
  foreground-child Stop, settled-parent child Stop, direct-child Stop, sibling
  exclusion, background shell Stop, recovery ordering, and nested depth-2 Stop

• Nested depth-2 verification uses only inline
  OPENCODE_CONFIG_CONTENT={"experimental":{"subagent_depth":2}} on a private
  test server; it does not change global OpenCode configuration

• Published manual UI guide and live scenario matrix

• 2026-08-06 currency (04eefae87 through e98b4febf; tip also has empty CI
  retrigger 8763ab36a):

  • Live private-serve with exact opencode2 v0.0.0-next-16916 and
    T3_MODEL=opencode/glm-5.2: opencode2-settlement and
    opencode2-interrupt-direct-stop pass (tool ids real, not
    tool:undefined)
  • Focused unit coverage for step-finish gating, startup absorb stream
    boundaries, and managed auth seed: 86 tests pass
  • Macroscope Correctness and Effect Service Conventions pass on e98b4febf
  • Local vp check pass; server typecheck clean. Monorepo typecheck still
    hits known base apps/mobile/vite.config.ts excessive stack depth on some
    trees
  • GitHub Actions Check/Test/Release Smoke were not scheduled on recent tips
    during a platform outage window; last Actions run on 37ff24db9 cancelled
    without runners (not a source failure on the current tip)

Known Limitations

• OpenCode 2 is still an upstream preview line and the API/event contract moves
  between next builds. This driver intentionally has no default instance.
  Pin an exact CLI version rather than floating @opencode-ai/cli@next.
  Current verified pin: opencode2 v0.0.0-next-16916
  (@opencode-ai/cli@0.0.0-next-16916), with
  autoupdate: false recommended for local installs that must match this
  adapter. Authenticate with opencode2 auth connect, then add an OpenCode 2
  provider instance explicitly. One-click channel updates remain available for
  recognized package-managed paths when you intentionally advance the pin;
  custom paths stay manual.
• This branch pins @opencode-ai/sdk-next to
  npm:@opencode-ai/sdk@0.0.0-beta-202608061351 as its sole consumer. The
  adapter dual-normalizes next-16916 short events and earlier beta
  session.next.* names; a newer unpinned binary can still diverge.
• External OpenCode 2 servers must supply their own server password and enable
  experimental background subagents themselves. T3-owned servers receive the
  required environment flag from provider settings and seed host credentials
  into an isolated managed data home (sessions are not shared with a desktop
  opencode2 serve --service).
• OpenCode currently defaults provider-native subagent depth to 1. The nested
  Stop topology is therefore harness-only unless a server opts into depth 2.

Model: GPT-5 Codex, with Grok 4.5, GPT-5.6 Sol, and Terra review passes
Harness: T3 Code

Note

Add OpenCode 2 as a built-in provider with full orchestration and UI support

• Introduces an opencode2 provider driver with its own settings schema (OpenCode2Settings), runtime (OpenCode2RuntimeLive), orchestration adapter (OpenCode2AdapterV2), and text generation implementation (makeOpenCode2TextGeneration).
• Adds a SpawnedProcessReaper service with a sidecar process that ensures managed OpenCode 2 server subprocesses are cleaned up on parent exit, on both POSIX and Windows.
• Extends the orchestrator to handle provider-native background work: threads now expose hasInterruptibleProviderNativeBackgroundWork, Stop commands can target provider-native threads without a run ID, and the composer surfaces a secondary Stop button when background work is active.
• Provider maintenance resolution supports npm dist-tag (next) and per-channel version caching; parseSemver is fixed to preserve full prerelease identifiers containing hyphens (e.g. 0.0.0-next-16339).
• Adds an OpenCode2Icon to the icon registry and surfaces OpenCode 2 in the model picker, settings UI, and mobile composer with distinct blue-themed visuals.
• Wires replay test fixtures and integration tests covering background subagents, child stop/recovery, compaction, shell terminals, thread deletion, and permissions.
• Risk: the production server layer now unconditionally starts OpenCode2RuntimeLive and SpawnedProcessReaper; any misconfiguration in the sidecar respawn logic could affect process cleanup for all managed providers.

📊 Macroscope summarized 6c8f5a0. 121 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

(Automatic summaries will resume when PR exits draft mode or review begins).

🗂️ Filtered Issues

No issues evaluated.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bfb355c3-fd52-4c70-9a21-4a216c733afa

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect service conventions review of the new OpenCode 2 service modules. Two findings; everything else (namespace effect/* imports, TextGeneration["Service"] usage, Context.Reference + layer in ProviderInteractionModeReflections.ts, scoped layer wiring) looks consistent with the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Effect service conventions review of the new OpenCode 2 service modules. Six findings, all in newly added service code (runtime service module, reaper service, text-generation implementation). The adapter/driver wiring, ProviderInteractionModeReflections, and the client-runtime/mobile changes look consistent with the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One convention finding on the new OpenCode 2 service module. Everything flagged in earlier runs (inline Context.Service interfaces, structured OpenCode2RuntimeError/SpawnedProcessReaperError attributes, no raw server output or credential text in detail, retry classification on a structural category) is addressed in this head.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One finding on the new OpenCode 2 provider probe: the probe wrapper copies its cause's message into a detail field and builds the caller-visible status message from it.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One finding on the new OpenCode 2 provider probe: the probe wrapper copies its cause's message into a detail field and builds the caller-visible status message from it.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Reviewed the new Effect service modules (opencode2Runtime.ts, SpawnedProcessReaper.ts, ProviderInteractionModeReflections.ts) and the OpenCode 2 provider/adapter/text-generation call sites against the service conventions. The earlier findings are resolved: both new service modules now declare their interface inline in Context.Service and export make/layer, OpenCode2RuntimeError carries a structured operation + category with a message derived from them (plus export const isOpenCode2RuntimeError = Schema.is(...)), and OpenCode2TextGeneration uses static detail strings with the real cause preserved and retries on the structural category instead of message text.

One small residual item on error construction is noted inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One finding: a newly added single-tag recovery uses Effect.catch with a hand-rolled schema predicate instead of Effect.catchTags. Everything previously flagged in this check (canonical make/layer in opencode2Runtime.ts, inline Context.Service interfaces, structured OpenCode2RuntimeError/SpawnedProcessReaperError attributes, static wrapper details with preserved cause, structural retry classification) now looks resolved.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One convention issue found: the new opencode2Runtime service module is imported with an aliased layer in several wiring/test files, which erases the module namespace that the rest of the PR uses.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One finding: a warning log in the new OpenCode 2 adapter copies arbitrary provider error text into a detail log field, while every other log site in the same file uses the sanitized errorTag/structural fields. Everything else in the new Effect service surface (provider/opencode2Runtime.ts, provider/SpawnedProcessReaper.ts, orchestration-v2/ProviderInteractionModeReflections.ts and its worker) follows the canonical module order, inline Context.Service interfaces, make + layer exports, environment-based dependency acquisition, Schema.TaggedErrorClass failures with structural attributes and preserved causes, and Effect.catchTags for known tags.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Reviewed the new Effect service modules (provider/opencode2Runtime.ts, provider/SpawnedProcessReaper.ts, orchestration-v2/ProviderInteractionModeReflections.ts), the OpenCode 2 driver/provider/adapter/text-generation code, and the mechanically updated layer wiring and call sites. The canonical make/layer exports, inline Context.Service interfaces, Foo["Service"] references, structured Schema.TaggedErrorClass failures with bounded category/operation attributes, Schema.is predicates, and Effect.catchTags usage all match the conventions now. One remaining wrapper still builds its detail from the cause's message.

^{Posted via Macroscope — Effect Service Conventions}