bug: opencode 1.15.1 run exits with InstanceRef not provided

[coygeek]

Summary

opencode run on opencode-ai 1.15.1 can create a session and then exit immediately with:

Error: Unexpected error, check log file at  for more details

InstanceRef not provided

The same command path works when pinned to opencode-ai@1.15.0, so this looks like a 1.15.1 headless-run regression.

Environment

opencode version: 1.15.1
os: Darwin 25.5.0 arm64
terminal: ghostty 1.3.1 / xterm-ghostty
provider/model: github-copilot/gpt-5.4

Reproduction

From an existing repo directory with normal OpenCode config/auth:

opencode run \
  --pure \
  --print-logs \
  --log-level DEBUG \
  --dir "$PWD" \
  -m github-copilot/gpt-5.4 \
  --variant high \
  --agent build \
  --dangerously-skip-permissions \
  'Say READY and stop.'

Observed with 1.15.1:

INFO ... service=session id=... version=1.15.1 ... created
INFO ... service=bus type=session.created publishing
INFO ... service=default ... disposing instance
ERROR ... message=InstanceRef not provided stack=Error: InstanceRef not provided
    at <anonymous> (/$bunfs/root/chunk-s9t5v9c2.js:679:76275)
    at ~effect/Effect/successCont (/$bunfs/root/chunk-jsc6q94x.js:25:7736)
    at runLoop (/$bunfs/root/chunk-jsc6q94x.js:25:2045)
    at evaluate (/$bunfs/root/chunk-jsc6q94x.js:25:1435)
    at <anonymous> (/$bunfs/root/src/index.js:91:12115)

I also reproduced the same InstanceRef not provided failure using a fresh isolated XDG data/cache/state directory, which suggests this is not just corruption in my existing OpenCode database.

Expected

The headless run command should continue after session creation, resolve tools, call the selected model, and print the model response.

Actual

1.15.1 creates the session.
2. Immediately disposes the instance.
3. Exits with InstanceRef not provided before the model call.

Workaround / regression check

Pinned 1.15.0 with the same normal OpenCode data/auth works:

npx -y opencode-ai@1.15.0 run \
  --pure \
  --print-logs \
  --log-level DEBUG \
  --dir "$PWD" \
  -m github-copilot/gpt-5.4 \
  --variant high \
  --agent build \
  --dangerously-skip-permissions \
  'Say READY and stop.'

1.15.0 output reaches the model and returns:

READY

A fresh isolated XDG data dir with 1.15.0 also gets past session creation and reaches the provider call; it then fails with missing required Authorization header, which is expected because that isolated data dir has no Copilot auth token. That still distinguishes the 1.15.1 InstanceRef crash from an auth failure.

Notes

This blocks automation that relies on non-interactive opencode run. For now I am pinning automation to npx -y opencode-ai@1.15.0 run while keeping the normal data directory so existing provider auth remains available.

[iNetanel]

We hit both regressions in The Architect (https://github.com/iNetanel/the-architect), which uses opencode run headlessly. Two separate root causes confirmed:
Cause 1 — OPENCODE_PROCESS_ROLE=worker inheritance
When OpenCode spawns a child opencode run process from inside an existing session, the child inherits OPENCODE_PROCESS_ROLE=worker and OPENCODE_RUN_ID from the parent environment. The child then tries to attach to the parent's server instance, which isn't reachable as a subprocess, and crashes immediately with InstanceRef not provided.
Reproduce:
OPENCODE_PROCESS_ROLE=worker OPENCODE_RUN_ID=some-uuid
opencode run --format json --dangerously-skip-permissions -- "hello"

→ InstanceRef not provided

Workaround: Strip OPENCODE_PROCESS_ROLE, OPENCODE_RUN_ID, OPENCODE_PID, OPENCODE, OPENCODE_CONFIG, OPENCODE_CONFIG_DIR from the environment before spawning any child opencode run process.
Cause 2 — --agent flag broken regardless of environment
Even with a clean environment and the named agent defined in config, --agent crashes with InstanceRef not provided in 1.15.x:

Clean env, agent defined in OPENCODE_CONFIG, still crashes:

env -u OPENCODE_PROCESS_ROLE -u OPENCODE_RUN_ID
OPENCODE_CONFIG=/path/to/config-with-agent.json
opencode run --format json --dangerously-skip-permissions
--agent architect -- "hello"

→ InstanceRef not provided

Without --agent: works fine

env -u OPENCODE_PROCESS_ROLE -u OPENCODE_RUN_ID
OPENCODE_CONFIG=/path/to/config-with-agent.json
opencode run --format json --dangerously-skip-permissions -- "hello"

→ works

The stack trace from --print-logs shows it crashes at chunk-tq6r1wx3.js:679:76275 immediately after service=session ... created and before any model call.
Workaround: Remove --agent and use "default_agent" in the config file instead.
Summary
Both regressions appear to be caused by the Effect-based instance context system introduced in 1.15.0. The --agent crash is the more serious one since it fires even in a clean environment.
We shipped a hotfix in The Architect v1.2.14 that version-gates both workarounds (applied only on ≥1.15, reverted automatically once fixed). Happy to help test a fix.

[hongsw]

Confirming Cause 2 (--agent broken regardless of environment) still reproduces on the latest published snapshots, in case it helps track the fix status:

• opencode-ai@1.15.1 (stable) — crashes
• opencode-ai@beta → 0.0.0-beta-202605160546 (today's snapshot) — still crashes

Two extra data points beyond the existing report:

1. It crashes even with a completely empty HOME — no config, no auth, no plugins, with --pure:

   HOME=/tmp/empty opencode run --agent build --pure "hi"
   # → InstanceRef not provided
   HOME=/tmp/empty opencode run --pure "hi"
   # → works (reaches the model call)

   So it isn't config/agent-definition dependent at all — the --agent flag alone triggers it.

2. Built-in agents are affected too, not just custom ones — --agent build and --agent plan both crash identically.

Stack trace tail (--print-logs):

ERROR service=default name=Error message=InstanceRef not provided stack=Error: InstanceRef not provided
    at <anonymous> (/$bunfs/root/chunk-s9t5v9c2.js:679:76275)
    at ~effect/Effect/successCont (/$bunfs/root/chunk-jsc6q94x.js:25:7736)
    ...

[kitckso]

I got same issue in GitHub action.

My workaround is adding the VERSION: "1.15.0" environment variable to the GitHub Actions workflow configuration. Example:

  - name: Run opencode
    uses: anomalyco/opencode/github@latest
    env:
      VERSION: "1.15.0"