[Tech debt]: opencode and opencode2 run the same OpenCode build in two different server topologies, split only for pane identity #22855

Operating system

Not OS-specific; the split is in Orca's launch configuration.

Orca version

1.4.210, still true on main at 7a4f080086

Details

What exists today

Orca has two agent keys for OpenCode and launches them into different topologies:

Both installed binaries are the same build here:

$ opencode --version && opencode2 --version
opencode v2.0.16
opencode v2.0.16

So this is not a version difference. It is one flag.

Why the flag is there

tui-agent-config.ts says so directly:

// The private server inherits this pane's hook endpoint and identity.
launchCmd: 'opencode2 --standalone',

--standalone is documented upstream as "Run with a private server instead of the background service". The consequence is that one path gets correct pane identity structurally, and the other does not:

• opencode2 — each pane's server carries that pane's own ORCA_PANE_KEY, so its status posts are right without any inference.
• opencode — the shared service freezes the environment of whichever pane started it, which is the entire reason the session→pane binder and resolveOpenCodeSharedServerEnvelope exist ([Bug]: opencode v2 shared background server freezes pane identity — every pane's status lands on whichever pane started the server #21359, fixed by fix(opencode): attribute shared-server sessions to their panes #21577).

Why it's worth an explicit decision

1. The rebinding subsystem only exists for the stable path. If opencode ever ran standalone the binder becomes dead code; if opencode2 ever dropped standalone it would start misattributing, and nothing in the code tied the two together until fix(opencode): bind same-directory sessions to the pane that submitted the prompt #22847 added a comment at the gate. The coupling is now documented but still unsolved.

2. Standalone is not free. It opts out of the background service, which is the architecture v2 introduced over v1 — [Bug]: opencode v2 shared background server freezes pane identity — every pane's status lands on whichever pane started the server #21359 put it plainly: "That worked when every pane ran its own opencode process. But opencode v2 runs a single shared background server for all panes." Running the beta this way trades that away in exchange for a truthful status dot. That may well have been the right call during the beta, but it was made once, for one agent key, with no recorded rationale, and the stable path never got the same treatment.

3. The trade is currently invisible. The two agent keys look like "v1 vs v2" by name while both run v2.0.16. Someone comparing them would reasonably conclude opencode2 is a different version rather than the same build launched differently.

Open questions

• Should opencode2 rejoin the shared server once pane attribution is reliable — at which point it needs the binder and the opencode2 exclusion at the reattribution gate must go?
• Or is one server per pane the direction, in which case the binder is a stable-path-only workaround and its eventual retirement should be planned?
• Is there a third option — keeping the shared server and giving the plugin a real per-pane identity, which is the only one of these that fixes the class of bug rather than relocating it?

Related

#21359 (the original pane-identity report), #21577 (the rebinding mechanism), #22838 / #22847 (the residual same-directory tie), #22458 (OpenCode TUI sluggish with multiple agents, reported against the shared topology).