platform/docs/opencode-fork-decision.md

The Phase 2 fork: reopened, and why the first answer was wrong

CORRECTION, same day. An earlier version of this file concluded "the new pipeline does not execute, keep the subprocess". That was wrong, and wrong for an embarrassing reason: my probe. The conclusion is reversed below. The mistake is written up rather than deleted, because the shape of it is the useful part.

Decision: the fork is worth taking, and it is no longer blocked. Not started; the blocker turned out to be a missing credential and is fixed — see RESOLVED below.

---

What actually happened

The serve exposes a newer /api/session/* surface, alongside the /session/* one every prior document was written against. It offers, natively, what the parity doc lists as impossible under stdin: 'ignore': delivery: "steer" | "queue" on POST /prompt, /interrupt, a per-session text/event-stream with an ?after= cursor, /compact, prompt.files, and /permission + /question.

I probed it, saw prompts accepted and never executed, and concluded it was an unfinished pipeline ("session.next.* is the tell"). Every one of those probes passed an explicit model: {providerID: 'opencode', id: 'claude-sonnet-4-6'}.

That model silently does not run on the new pipeline. No error, no event, no assistant message — the prompt is admitted, stored, prompt.admitted and prompted fire, and nothing else ever happens. Drop the model field and the identical request completes normally.

So I had one broken variable in every experiment and read the result as a property of the system.

What is actually true, measured on 1.18.16 (both machines upgraded 2026-08-10)

Claim	Verdict
The new pipeline executes turns	Yes — replies normally when no model is forced
delivery: "steer" injects mid-turn	Yes, verified — steered a running turn, output changed to order
delivery: "queue" runs after	Yes, verified — two replies, "ONE" then "TWO", zero errors
Model selection works at all	Yes — POST /api/session/{id}/model → 204, then runs on it
claude-sonnet-4-6 works there	No — silent no-op, at create and via the model route
claude-sonnet-4-6 works via run --dir	Yes — verified end to end the same day

Steer and queue are exactly the two features we hand-built for Claude and that Andre called a game changer. Having them as primitives, plus a resumable per-session cursor that mirrors officer's durable replay, is a strong argument for migrating.

RESOLVED — it was a missing credential, not a bug

Andre said he had a paid Zen key working in his terminal and suggested it simply was not set up here. He was right, and this is the second wrong conclusion I reached on this page.

The new pipeline has its own credential store, separate from auth.json. opencode run, the CLI and the legacy /session surface all read ~/.local/share/opencode/auth.json, which holds the Zen key — so they reach paid models. The /api/* surface reads integrations instead (/api/integration, /api/credential), and ours had none connected. With no credential it silently fell back to what needs none, which is exactly the free tier.

The fix was one call, and it persists across a serve restart (verified — a paid model still ran after pm2 restart officer-opencode):

POST /api/integration/opencode/connect/key   { "key": "<zen key>", "label": "…" }   → 204

Afterwards claude-sonnet-4-6 and claude-haiku-4-5 both run on the new pipeline. The fork is unblocked, and everything the table above promises — steer, queue, interrupt, resumable per-session SSE — is available with real models.

Two consequences worth carrying:

• alpha needs the same one-time connect before it can use the new pipeline.
• The sidecar should do this itself at boot rather than relying on someone having run it by hand, since a missing credential degrades to "only free models work" with no error anywhere.

What the evidence looked like while I was getting it wrong

Recorded because the shape repeats: the failure was silent and total for paid models, and the cost table drew a perfect line — every cost-0 model ran, every cost>0 model did not. I read that as a billing boundary inside a broken pipeline. It was a billing boundary caused by an absent credential, which is a far more ordinary explanation and one Andre reached from knowing his own setup rather than from the API.

The tell I had and did not use: the configured default is opencode/big-pickle, and a session created with no model ran on ling-3.0-tiny-free instead of the default. A pipeline ignoring its configured default is a pipeline that cannot use it — that is a credential symptom, and it was sitting in the /config/providers output the whole time.

The original diagnosis, kept for the record: only free models run

It is not sonnet, and it is not variant. Swept four models through POST /api/session/{id}/model followed by a prompt:

Model	New pipeline
longcat-2.0-free	ran
ling-3.0-tiny-free	ran
claude-haiku-4-5	never ran
claude-sonnet-4-6	never ran
gpt-5.1-codex-mini	never ran

Every -free model runs; every paid model silently does not. Ruled out along the way:

• Not variant. claude-sonnet-4-6 advertises ["low","medium","high","max"] and session create echoes back variant: "default", which is not among them — a promising theory that turned out to be wrong: setting variant: "high" explicitly also never ran. Tested rather than assumed, which is the whole lesson of this file.
• Not missing credentials. opencode auth list shows an OpenCode Zen API key in ~/.local/share/opencode/auth.json plus ANTHROPIC_API_KEY in the environment.
• Not the sidecar's environment. The same sidecar process runs claude-sonnet-4-6 correctly through opencode run --model, verified end to end. Same user, same home, same auth file.

So the new pipeline does not resolve paid-model credentials, and fails silently rather than reporting it — while the legacy path and run both authenticate fine. Note it can surface provider auth errors when it reaches that far: alpha's default (nano-gpt) returned a clean 401 missing_api_key. The silence is specific to opencode-zen paid models.

This reads as an upstream bug in an in-progress pipeline, not something configurable on our side.

Consequence for the fork: blocked, but precisely. Officer's users pick real models; a harness that works only on free tiers is not adoptable. Re-run the sweep above after each opencode upgrade — the day a paid model runs there, the migration is unblocked and worth doing immediately, because steer and queue are already proven.

Revised recommendation

Take the fork, targeting the new surface, once the model question is answered. Not the legacy /session/{id}/message path — that generates fine but has neither steer nor queue, so it buys streaming at the cost of SSE demux and warm-session lifetime for the two least interesting gaps.

Until then opencode run --dir stays, and it is verified working: session:init → assistant:text → result with cost, on 1.18.16, after the upgrade.

The lesson, which is the reason this file keeps its history

This project has now hit the same trap three times, each time in a different costume:

• directory in the body of POST /session — accepted, echoed, ignored. Produced a confident wrong answer about per-request directories.
• location.directory in the parity doc — a field that did not exist on that surface, which would have compiled and silently produced ''.
• model on POST /api/session — accepted, echoed back in the response, and fatal to execution.

OpenCode's API accepts input it does not honour, and says nothing. So a probe that changes one thing and sees nothing happen has not learned that the feature is missing; it has learned that something is wrong, and the next step is to remove variables, not to conclude. The corrected probes here each changed exactly one field.

Findings worth keeping

• delivery defaults to "steer" when omitted.
• New-surface responses wrap in {"data": …}; the legacy surface returns bare objects, so reading body.id instead of body.data.id silently yields undefined.
• The new surface is location-scoped per request: x-opencode-directory header, or ?location[directory]= as a deepObject query.
• ?after= genuinely replays a finished session's events.
• opencode versions: both machines on 1.18.16 as of 2026-08-10 (Mac was 1.18.11, alpha 1.17.9). Several comments recorded these backwards; corrected. Policy from Andre: write against the latest version regardless of what alpha happens to run.