Skip to content

Commit 99c14e2

Browse files
committed
docs(opencode): record which build the fleet runs, and why not opencode2
The choice of the Homebrew stable line over the opencode2 nightly was made 2026-08-19 and never written down. CLA-381 captured the incident that prompted it - a Transport stream error from nightly 0.0.0-next-17403 exiting 1 and stopping the whole daemon - but not the decision, so a day later the question "opencode or opencode2?" had to be re-derived from PATH, doctor and finally opencode's own session log. Records four things that existed only on the filesystem or in people's heads: - the adapter execs a bare `opencode`, so PATH decides and switching builds is a code change, not a setting; - which build ran is read off opencode's own `version=` log line, never inferred from PATH; - `~/.config/clankerbar/bin/opencode` is an abandoned symlink to opencode2, inert only because that directory is on nobody's PATH; - the stable line has its own defect (anomalyco/opencode#43622) that makes a session exit 0 having produced nothing, which is what our dead implement phases were, and upgrading within 1.18.x does not escape it. No decision record exists for the switch back to stable, so the page states that in as many words and marks its rationale as reconstructed from CLA-381, noting that CLA-381's note warns about both builds rather than endorsing stable. It is correctable by whoever made the call. Also repoints two stale signposts for the quiet-death signature, both of which sent readers to the tool-schema page: the README's docs index AND its in-body paragraph, which additionally called the signature "opencode-go" when CLA-401 disconfirmed the gateway. The tool-schema page's own closing section still presented that gateway hypothesis as live, so it now records it as closed and points at the client defect instead.
1 parent 3bd65a3 commit 99c14e2

3 files changed

Lines changed: 98 additions & 10 deletions

File tree

‎README.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -940,10 +940,12 @@ hit it, the error text is the thing to report — it is a failure shape the adap
940940
should learn a pattern for.
941941

942942
**The quiet-death signature.** A session that dies with a final `step_finish`
943-
reason of `unknown` and all-zero usage on its own last step is the opencode-go
944-
quiet-death signature — see
945-
[`docs/opencode-tool-schema-limits.md`](./docs/opencode-tool-schema-limits.md) for
946-
the incident behind it and what the CLI does about a recurrence.
943+
reason of `unknown` and all-zero usage on its own last step is the quiet-death
944+
signature. The cause is an opencode client defect, not the provider - see
945+
[`docs/opencode-build.md`](./docs/opencode-build.md). The marker itself is
946+
described in
947+
[`docs/opencode-tool-schema-limits.md`](./docs/opencode-tool-schema-limits.md),
948+
which is a separate failure with a separate cause.
947949

948950
**What gets read as a failure.** A session's output is the whole event stream, and
949951
the events quote the backlog verbatim — the task the session claimed is sitting in
@@ -1147,7 +1149,8 @@ parent is the correct setting.
11471149

11481150
- [`docs/releases.md`](./docs/releases.md) - the release/publish pipeline: how a change gets from a task PR to a published binary.
11491151
- [`docs/large-tool-results.md`](./docs/large-tool-results.md) - how the driver reads a tool_result that Claude Code persisted to a file instead of inlining.
1150-
- [`docs/opencode-tool-schema-limits.md`](./docs/opencode-tool-schema-limits.md) - the opencode-go request-time tool-schema rejection family (`unsupported_tool_schema` / `tool_count_limit`): the incident, the real root cause behind the misleading error code, and what the CLI does about a recurrence. Troubleshooting for a session that dies with `reason: "unknown"` and zero usage.
1152+
- [`docs/opencode-tool-schema-limits.md`](./docs/opencode-tool-schema-limits.md) - the opencode-go request-time tool-schema rejection family (`unsupported_tool_schema` / `tool_count_limit`): the incident, the real root cause behind the misleading error code, and what the CLI does about a recurrence.
1153+
- [`docs/opencode-build.md`](./docs/opencode-build.md) - which opencode build the fleet runs and why not `opencode2`, how to tell which one actually ran, and the upstream defect that makes a session exit 0 having done nothing. Start here for a session that dies with `reason: "unknown"` and zero usage.
11511154

11521155
## License
11531156

‎docs/opencode-build.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Which opencode build we run, and why not opencode2
2+
3+
Short answer: **the Homebrew stable line** (`/opt/homebrew/bin/opencode`, 1.18.x). Not
4+
`opencode2`. This page exists because that was decided on 2026-08-19 and never written
5+
down, and re-deriving it a day later cost real time.
6+
7+
## The adapter runs a bare name, so PATH decides
8+
9+
`internal/harness/opencode.go` execs `"opencode"` with no path. There is no config dial for
10+
the binary, so **whatever `opencode` resolves to on the daemon's PATH is what runs**, and
11+
pointing the fleet at a different build is a code change, not a settings change.
12+
13+
**Never answer "which build ran?" from PATH.** Read it off the session:
14+
`~/.local/share/opencode/log/opencode.log` records `version=` on the line where it creates
15+
the session, e.g. `message=created id=ses_... version=1.18.18`. `clankerbar doctor` also
16+
reports it, as `pass harness[opencode] /opt/homebrew/bin/opencode (1.18.18)` - the same fact
17+
from the same resolution the driver will do. The `[opencode]` qualifier appears because
18+
opencode is a phase harness here; were it the run harness the label would read bare
19+
`harness`.
20+
21+
## Why not opencode2
22+
23+
We ran the `opencode2` nightly (`0.0.0-next-17403`) on the first mixed-harness drain,
24+
2026-08-19. At 12:48 an implement session about five minutes and 21 tool calls into a task
25+
emitted a single untyped error event and exited 1:
26+
27+
```json
28+
{"type":"error","error":{"type":"unknown","message":"Transport"}}
29+
```
30+
31+
A transport drop is the canonical transient, but the driver treated any opencode exit 1 as
32+
terminal, so one provider hiccup stopped **the whole daemon** and needed a hand restart.
33+
That is **CLA-381**, and it fixed our classifier - transient stream failures now retry under
34+
the existing backoff. The classifier fix stands on its own and is not a reason to avoid
35+
opencode2.
36+
37+
**No decision record exists for the switch back to stable.** What follows is reconstructed
38+
from CLA-381 and can be corrected by whoever actually made the call.
39+
40+
The likely reason is narrower and duller than the incident: the nightly's error surface is
41+
undocumented and changes without notice, and an unattended fleet cannot classify failures it
42+
cannot predict. CLA-381's note is *consistent with* that, though it warns about both builds in
43+
the same breath - *"the error surface may be version-dependent: this was the opencode2 nightly
44+
... stable 1.18.x may report stream failures differently, so classify by pattern"*. Read as
45+
written, it pins neither surface; it is an argument for pattern-matching, not for stable.
46+
47+
**There is a live trap from that experiment.** `~/.config/clankerbar/bin/opencode` is a
48+
symlink to `opencode2.exe`, created 2026-08-19 12:43, five minutes before the incident above.
49+
It is **abandoned**, and inert only because that directory is on nobody's PATH. If anything
50+
ever puts it there, the whole fleet silently switches binaries with no log line saying so.
51+
Delete it, or if you keep it, say here what it is for.
52+
53+
## Stable is not free of defects either
54+
55+
The line we run has a known one, and upgrading within 1.18.x does not escape it: a turn that
56+
returns an indeterminate finish reason makes opencode **exit 0 with no error**, discarding the
57+
turn - `packages/opencode/src/session/prompt.ts:1113` omits `"unknown"` from the loop-exit
58+
exclusion that the same file applies ~180 lines later at `:1295`. Reproduced against a local
59+
fake provider by patching v1.18.19 and watching the behaviour flip.
60+
61+
Filed upstream as **anomalyco/opencode#43622**. Absent from every release checked (v1.15.0
62+
through v1.18.19, the current latest), and present in the one older checkout available here
63+
(1.2.27, at `prompt.ts:323`), so it reads as a guard dropped in a refactor rather than a
64+
missing feature.
65+
66+
For us that failure looks like a session that ended with no branch and no error (it had
67+
usually done paid work first - only the final step is empty) -
68+
what the driver calls a dead phase. It hit 6 of 16 implement sessions on 2026-08-20.
69+
**CLA-406** covers treating it as a discarded turn to retry rather than a task failure.
70+
71+
If we ever pin a patched build rather than waiting for upstream: **do not vendor the
72+
one-line fix**. Adding `"unknown"` to the list at `:1113` removes the silent exit but
73+
produces an unbounded retry loop - 138 steps and climbing in the test, with no cap observed.
74+
The shape that works is `:1301`, where a `content-filter` finish is surfaced as an error.
75+
76+
## See also
77+
78+
- [`docs/opencode-tool-schema-limits.md`](./opencode-tool-schema-limits.md) - the separate
79+
Console Go tool-schema rejection family. A different failure with a different cause; do not
80+
reach for it when a session dies quietly with zero usage.
81+
- CLA-381 (the opencode2 incident and the classifier fix), CLA-401 (the investigation that
82+
cleared the gateway and the model), CLA-406 (our mitigation).

‎docs/opencode-tool-schema-limits.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -103,9 +103,12 @@ sessions died producing nothing, and the marker above is what makes any such
103103
death self-describing. What is **unconfirmed**: that the tool-schema rejection
104104
caused them. On 2026-08-20 the rejection strings appeared in the iteration logs
105105
only as task-body text an agent read, never as an error event, and the direct
106-
probes all returned 200. The live hypothesis for the dead phases is a different
107-
gateway failure — streams ending with no terminal `finish_reason`
108-
([#40420](https://github.com/anomalyco/opencode/issues/40420),
109-
[#43379](https://github.com/anomalyco/opencode/issues/43379)) — tracked as
110-
CLA-401. The tool-schema work here stands as hardening against a recurrence the
106+
probes all returned 200. **That question is now settled, and not in this page's favour.** CLA-401
107+
disconfirmed the gateway entirely: 40 of 40 streams carried a terminal
108+
`finish_reason`, against both this gateway and the official DeepSeek API. The
109+
cause is an opencode client defect - `prompt.ts:1113` treats an indeterminate
110+
finish as a completed turn and exits 0 - filed as
111+
[#43622](https://github.com/anomalyco/opencode/issues/43622) and written up in
112+
[`opencode-build.md`](./opencode-build.md), with our mitigation as CLA-406.
113+
**Do not reason from this page about a quiet death.** The tool-schema work here stands as hardening against a recurrence the
111114
2026-08-19 logs prove is real.

0 commit comments

Comments
 (0)