tui: legacy V1 plugin shape rejected without migration path after V1->V2 upgrade #52766

Summary

After upgrading from OpenCode V1 to V2 (v2.0.21), the TUI rejects legacy V1 plugin modules with Invalid V2 TUI plugin module: opencode-subagent-statusline and 2 plugins failed, with no migration path or actionable error.

Environment

• opencode version: v2.0.21 (opencode --version → opencode v2.0.21)
• OS: Darwin MacBook-Pro-de-Rodrigo.local 22.6.0 Darwin Kernel Version 22.6.0: Tue Jul 15 08:22:28 PDT 2025; root:xnu-8796.141.3.713.2~2/RELEASE_X86_64 x86_64
• Terminal: TERM=xterm-256color, TERM_PROGRAM=ghostty, COLORTERM=truecolor
• Shell: /bin/zsh
• Install/channel: latest (release v2.0.21)
• Active plugins: gentle-logo.tsx (local file, loads OK). Removed as workaround (see backups cli.json.bak, tui.json.bak):
  • opencode-subagent-statusline@1.3.0 (https://github.com/Joaquinvesapa/sub-agent-statusline, engines: node >=22.13, @opencode-ai/plugin >=1.14.50 <2)
  • opencode-sdd-engram-manage@1.7.0 (engines: node >=24 <25, system node is v22.15.0, @opencode-ai/plugin >=1.17.11)
  • Installed @opencode-ai/plugin: ^1.18.15 (per ~/.config/opencode/package.json)
  • Node: v22.15.0, npm 11.16.0

Reproduction

1. On OpenCode V1 config, have ~/.config/opencode/cli.json plugins and ~/.config/opencode/tui.json plugin include opencode-subagent-statusline and opencode-sdd-engram-manage (npm-installed), plus local tui-plugins/gentle-logo.tsx.
2. Upgrade to OpenCode v2.0.21 and launch the TUI (opencode).
3. Observe TUI startup error: Invalid V2 TUI plugin module: opencode-subagent-statusline and 2 plugins failed.

Expected Behavior

Legacy V1 { id, tui } plugins keep loading in V2, or the TUI shows a clear migration error (expected shape, docs link, codemod/upgrade step) instead of a bare Invalid V2 TUI plugin module failure.

Actual Behavior

TUI client shows Invalid V2 TUI plugin module: opencode-subagent-statusline and 2 plugins failed on every launch. Error appears only in the TUI client, not in the server log. Reproducible consistently. Disabling the two npm plugins (leaving only gentle-logo.tsx) makes the TUI load clean, but loses plugin features.

Additional Context

• Both failing npm plugins export the legacy shape { id, tui } (verified in dist/tui.js: var plugin = { id: TUI_PLUGIN_ID, tui }, default-exported). The local gentle-logo.tsx uses the same legacy shape (const plugin = { id: "gentle-logo", tui }; export default plugin) yet still loads, so the validator behavior is inconsistent/confusing.
• Suspected V2 validator requirement is { id, setup } vs legacy { id, tui }, but this is not surfaced in the error.
• Docs reference: https://opencode.ai/v2/docs/build/plugins/cli
• Migration guide gap: no documented V1→V2 TUI plugin migration path (shape change, setup vs tui, entrypoint/exports expectations, node engine bump to >=24 for opencode-sdd-engram-manage while system runs node v22.15.0).
• Config evidence (pre-workaround backups): cli.json.bak plugins: ["opencode-subagent-statusline", "opencode-sdd-engram-manage", "<abs-path>/gentle-logo.tsx"]; tui.json.bak plugin: [<same three entries>]. Current cli.json/tui.json contain only gentle-logo.tsx.
• Workaround tried: removed the 2 npm entries from ~/.config/opencode/cli.json plugins and ~/.config/opencode/tui.json plugin (backups cli.json.bak, tui.json.bak kept). Helps (TUI loads clean) but loses features — not a fix.
• No secrets included; absolute username redacted to generic path in this report.