[Bug] 0.22.1 ACP agent migration is not atomic: partial npm install never self-heals, empty opencode version dir treated as installed, effort=max pushed to agents that reject it

[noxenys]

[Bug] 0.22.1 升级后多个 ACP agent 损坏:partial install 不自愈 / opencode 空版本目录被当已装 / effort=max 推给不支持的 agent

环境 / Environment

• codeg: 0.22.1
• OS: Windows 11 Pro (win32-x64)
• node: v24.11.1, npm: 11.6.2

概述 / Summary

升级到 0.22.1 后,多个 agent 无法使用:ClaudeCode 每次连接即报错断开、OpenCode 二进制丢失。排查后是 agent 注册表/二进制迁移中途失败且没有自愈/回滚机制,不是单一 agent 的问题。下面按三个独立缺陷分述,均有日志与磁盘证据。

---

Bug A — ClaudeCode ACP 安装残缺,坏状态持续两周不自愈(最严重)

现象

每次拉起 ClaudeCode 都是 Connected → Error → Disconnected,内部错误:

[ACP] session/resume failed (Internal error: {
  "details": "Claude native binary not found for win32-x64. Reinstall @anthropic-ai/claude-agent-sdk without --omit=optional, or set CLAUDE_CODE_EXECUTABLE."
})

根因

~/.codeg/npm-global/node_modules/@agentclientprotocol/ 下只剩一个 npm 半成品暂存目录:

@agentclientprotocol/
└── .claude-agent-acp-NvMnBeDA/      # npm 安装中断留下的 .<pkg>-<hash> 暂存目录
    └── node_modules/                # 依赖装了
    # 根目录连 package.json 都没有,正式 claude-agent-acp 包从未生成

npm 安装被打断:依赖解压进了暂存目录的 node_modules,但包本体文件没写、暂存目录也没 rename 成正式目录。

该目录自 2026-07-16 起持续两周未被修复(目录 mtime 为证),期间 codeg 每次启动都按坏状态拉起 ClaudeCode、每次报同样的 native binary 错误,既不重装也不给可操作提示 —— 用户侧只看到"这个 agent 一直报错"。

补充观察:在 2026-07-30 手动干预并重启 codeg 后,该残缺暂存目录已被清理。说明清理逻辑存在,但触发时机太晚/条件太窄,坏状态能横跨两周和多次启动而不被处理。

期望

• 启动/连接前校验 ACP 包完整性(正式目录 + package.json + native binary 可解析),不完整就自动重装或明确提示"安装损坏,点此重装",而不是反复用坏状态连接。
• 安装原子化:装完再 rename/切换,失败即清理暂存目录,不留半成品。
• native binary 缺失时给出可点击的自助入口(错误里已有 CLAUDE_CODE_EXECUTABLE 提示,但普通用户无从下手)。

---

Bug B — OpenCode 空版本目录被当作"已安装",二进制替换非原子

现象

OpenCode 二进制彻底丢失:旧版本 1.18.5 被删除(连 .trash 都没有),新版本目录 acp-binaries/opencode/1.18.8/ 是空壳(无 windows-x86_64/opencode.exe)。

升级前日志还能看到版本漂移警告:

[ACP][OpenCode] Using cached binary 1.18.5 (registry recommends 1.18.8)

随后 1.18.5 被清、1.18.8 没下完,opencode 无任何可用二进制。

根因

删旧版 → 建新版目录 → 下载新版,这一串不是原子操作;中途失败后留下一个空的版本目录。codeg 见到 1.18.8/ 目录存在就当"已安装"跳过下载,于是永久无二进制。

复现 / 验证

手动 rm -rf acp-binaries/opencode/1.18.8(清掉空壳)后重启 codeg,codeg 立刻正常重下完整二进制并连上:

[ACP][OpenCode] Using cached binary 1.18.8
[ACP][OpenCode] binary_path=...\opencode\1.18.8\windows-x86_64\opencode.exe size=174403464
[ACP] status_changed session=None Connecting -> Connected

即:空壳版本目录就是卡点,删掉即恢复。

期望

• 判断"已安装"要校验目录内实际存在可执行文件,而非目录存在即可。
• 二进制升级原子化:下到临时目录校验完成后再切换,失败不动旧版本。

---

Bug C — effort=max 被推给不支持该档位的 agent(opencode)

现象

每次连接 OpenCode 都刷 ERROR(不影响运行,但污染日志):

[ACP] failed to apply preferred config 'effort'='max' on connect:
  Invalid params: effort not found: max: { "effort": "max" }

根因

OpenCode 的 effort 枚举只有 low/medium/high,不含 max。codeg 把全局/当前选中的 effort=max 无差别下推给 opencode,未按 agent 能力做校验/clamp。

期望

下推 preferred config 前按目标 agent 声明的 capability 过滤或 clamp(如 max→high),不支持的键静默跳过或降级,不刷 ERROR。

---

次要 / Secondary

升级后老会话无法 resume:Codex no rollout found for thread id ...、Claude/opencode session/resume→load→new 回退。会话数据本身还在(conversation 表 469 条),但旧 rollout 与新 agent 版本不兼容。建议迁移时做 rollout 兼容或至少提示用户。

---

临时 workaround(给遇到同问题的人)

• ClaudeCode:把暂存目录里可用的 claude.exe 拷到稳定路径(如 ~/.codeg/bin/claude.exe),在该 agent 的环境变量里设 CLAUDE_CODE_EXECUTABLE 指过去。
• OpenCode:删掉 acp-binaries/opencode/<空版本目录>,重启让 codeg 干净重下。
• effort 噪声:暂无干净绕过(改 delegation.agent_defaults 无效,该值非此来源),只能在 UI 给该会话选非 max 档。

均已在本机验证:重启后 ClaudeCode / OpenCode / Codex 三者都能 Connecting → Connected。

根因一句话

agent 的 npm 包 / 二进制安装与替换不是原子操作,失败后既不回滚也不及时自愈,加上下推 preferred config 不按 agent 能力适配,三者在 0.22.1 一起暴露。

备注

我只从本机日志、磁盘状态和 SQLite 配置反推根因,没有读过源码,所以上面"期望"部分是行为层建议,具体该在哪层修由你们判断。如果需要更多日志(完整 codeg.2026-07-30.log 等)或愿意的话我可以试着提 PR,请告知希望改动的模块。

[noxenys]

Correction to the root-cause analysis above — I traced this from logs/disk only and got two of the three mechanisms wrong. After reading the source (src-tauri/src/acp/), here's the corrected version.

Bug B (opencode "empty version dir treated as installed") — retracted.
This mechanism is wrong. installed_binary_path (binary_cache.rs:280) checks all the way down to path.is_file() (and even validates arch compatibility, deleting on mismatch), so an empty version dir returns None and is never counted as installed. ensure_binary_with_progress (binary_cache.rs:494) therefore does not skip download for an empty dir, and cleans up the dir on failure (remove_dir_all(&dir)).
The real cause is by design: connection.rs (the Binary arm, ~L770) documents "Session-page connect must never trigger a download" and returns SdkNotInstalled(... "is not installed. Please install it in Agent Settings") when no usable cached binary exists. With 1.18.5 removed and 1.18.8 only a shell, find_best_cached_binary_for_agent returned None → that error. Deleting the empty dir was not what fixed it; a later Settings/background path re-downloaded the binary. Sorry for the misdirection.

Bug A (Claude native binary) — re-framed.
The SDK's error text ("Reinstall without --omit=optional") made me assume codeg wasn't passing the flag. It is — commands/acp.rs:1872 defines NPM_INCLUDE_OPTIONAL = "--include=optional" and passes it unconditionally on every install path, with a comment explaining exactly this failure mode. So the missing native binary wasn't a missing flag; it was an interrupted npm install that left only npm's own staging dir (@agentclientprotocol/.claude-agent-acp-<hash>/, no root package.json). The still-valid point is narrower: a partial/interrupted ACP install isn't detected or self-healed at connect time — codeg kept launching the broken state for two weeks, re-emitting the same error each start. An integrity check (final dir + package.json + resolvable native binary) before connect, with a repair prompt, would cover it.

Bug C (effort=max pushed to opencode) — confirmed, with exact location.
connection.rs:4538-4564: preferred config_values are pushed on connect and failures only tracing::error!. The adjacent comment notes it deliberately doesn't skip a config_id absent from advertised options (to tolerate edge-case codex-acp builds that accept an unadvertised mode). So a per-agent capability-aware clamp/filter for effort (e.g. max→high when the agent only advertises low/medium/high) fits better than blanket-skipping unadvertised keys — it preserves that intent while killing the repeated ERROR for agents that genuinely don't support the value.

Net: C stands and is precisely located; A stands in a narrower form (self-heal, not the flag); B is retracted. I'll send a PR for C (capability-aware clamp in the preferred-config apply loop).

[noxenys]

Correction to Bug C — my proposed fix (capability-aware clamp max→high) was based on an unverified assumption and is wrong. I ran the agent's actual ACP handshake; here is what it advertises.

In my previous comment I said opencode's effort enum is low/medium/high and so max should be clamped to high. I never verified that — I inferred the enum from the fact that max was rejected. That inference is false.

Live initialize + session/new against opencode v1.18.8 (the binary codeg itself installed, acp-binaries/opencode/1.18.8/windows-x86_64/opencode.exe):

top-level result keys: ['sessionId', 'configOptions']
n options: 2
  id='model' type='select' category='model' current='opencode/big-pickle' nvals=27
  id='mode'  type='select' category='mode'  current='build'               nvals=6
has 'effort' substring anywhere in result: False

opencode advertises no effort option at all. So Invalid params: effort not found: max names a missing option id, not an out-of-range value — same wording either way, which is what misled me. A clamp would have been dead code: it would rewrite max→high and then still fail with effort not found: high.

Confirmed against the logs — 23 days of ~/.codeg/logs/codeg.2026-07-*.log, every one of these carrying "agent_type":"OpenCode":

saved value	occurrences	error
effort=max	867	Invalid params: effort not found: max
effort=high	61	Invalid params: effort not found: high
effort=medium	36	Invalid params (+12 Internal error)

high and medium fail exactly like max. Clamping to high could never have helped.

The actual mechanism

It isn't per-value capability at all — it's an unpruned preference store.

src/lib/selector-prefs-storage.ts persists config selections per agent type in localStorage under codeg:selector-prefs, and its header comment states the intended cleanup path:

"when the saved value no longer exists in the current option set … the backend's set_session_config_option will reject the application and the stale value is naturally dropped on the next user pick"

That path can't be reached. saveConfigPreference is the only writer, and it only fires on a user pick — but once an agent stops advertising the option, the selector is gone from the UI, so there is no pick to make. The entry becomes immortal, and apply_preferred_session_options (connection.rs:4510) re-sends it on every single connect, logging an ERROR each time. Hence 867.

This also explains the rest of the preferred-config noise in my logs, same mechanism, different agents: reasoning_effort=xhigh/=ultra (Codex, 7+7 — I misattributed two of these to opencode earlier), fast=on (47), model=claude-opus-4-7 (15), mode=bypassPermissions (10).

Why "skip unadvertised ids" is the right fix after all

I argued against blanket-skipping because the comment at connection.rs:4539-4544 says it deliberately does not skip an unadvertised config_id:

"older or edge-case builds accept set_config_option for an unadvertised "mode" (see ensure_codex_mode_option), so let the agent decide."

That intent is real but it is specifically about mode, and it's preserved by allowlisting that one id rather than by sending everything. Two things in the existing code support this reading:

• ensure_codex_mode_option (connection.rs:1496) documents the exception as mode-only: "Codex's set_config_option handler accepts config_id = "mode" regardless of whether it was advertised."
• apply_grok_preferred_options (connection.rs:1947) — the agent-specific path — already gates on advertisement for both model and effort: sel.current_value != pref && sel.options.iter().any(|x| x.value == pref). The generic path is the only one missing that guard.

So the fix is to make the generic path match what the Grok path already does, with mode on an explicit allowlist. "Let the agent decide" is sound for an id the agent might secretly accept; it is not sound for an id the agent has never heard of, where the only outcome is a guaranteed rejection on every connect forever.

I've withdrawn the clamp and have this version working locally instead — happy to send it as the PR for C unless you'd prefer the pruning live in the frontend (selector-prefs-storage.ts dropping keys absent from the advertised set) or in both places.

Local mitigation for anyone hitting the log spam now: remove the stale keys from codeg:selector-prefs in localStorage (open_code.effort, codex.reasoning_effort, claude_code.fast in my case). Dropping them is a functional no-op — the write already fails today — and it silenced the retry: 21 preferred-config errors earlier that same day, then 0 across the Codex connect after the change.