[hongkongkiwi]

What and why

Fixes #209: a cloud machine installed npm opencode-ai (OpenCode v1; latest 1.19.5, no 2.x exists) even when the host ran OpenCode v2, so the sandbox's harness never advertised the model picked from the host's v2 catalog and every first run died with The harness does not advertise the selected setting. about 15 seconds in. Switching the task's model to Default unblocked it, which is how the reporter isolated the harness, not the machine.

#215 pinned the install to the host's version, but for a v2 host that pin produces opencode-ai@2.1.2: an npm version that does not exist, so the install now fails outright instead of installing the wrong generation. The package itself has to follow the host's major generation. This PR is stacked on #215 (its head, 54164e8); only the two commits shown as "commits" below are new.

What (in src-tauri/src/cloud_agents/setup.rs)

• opencode_package(version) returns @opencode/cli for a host major of 2 or higher and opencode-ai otherwise, pinned to the host's exact version when parse_version yields one (@opencode/cli@2.1.2, opencode-ai@1.19.5). npm facts checked today: opencode-ai publishes only 1.x, @opencode/cli only 2.x, and both expose the same opencode bin, so mark_runtime's resolution is unchanged.
• host_generation(version) reads the major from the parsed pin, falling back to a new looser parse_generation so a bare 2, v2 or 2.x still selects the right package without inventing a pin. Anything unparsable keeps the v1 package and latest, as before.
• The runtime marker is keyed by generation (opencode-2, opencode-1), so a machine provisioned for one generation never reuses another's marker; the plain opencode marker written by older builds is likewise never read by a generation-scoped lookup. Other harnesses keep their own name as the marker id.
• cached_program and mark_runtime take the runtime id in place of the harness name; behavior for claude/glm/mimo/codex is byte-identical.
• Review fix: the marker cache gate now compares against the parsed pin instead of the raw host output. A prefixed line like OpenCode 2.1.2 or a bare 2 could never equal the machine CLI's own --version line, so the gate missed and every run reinstalled through npm.

What (in src-tauri/src/providers/acp.rs)

• choice_request now reports The harness does not advertise the selected <setting> "<value>". It offers: <values>. Refresh its models or choose the harness default. The setting name comes from the option's id, else its category, else the word "setting"; up to 12 offered values are listed, then , …, or nothing when the harness offers none. The generic sentence named nothing, which is what left the reporter guessing across model, mode and effort.

How it was tested

• 8 new tests, authored independently of the fix by a separate test-author pass and qualified failing-first against stubs of the old behavior before implementation. Verbatim failures included left: "opencode-ai@2.1.2" / right: "@opencode/cli@2.1.2" and all three choice_request tests panicking on the old generic line. Coverage: package selection across real --version outputs (2.1.2, v2.1.2, OpenCode 2.1.2, 2.2.0-beta.3, bare 2/v2/2.x, 1.19.5, None, "", latest, junk), generation-scoped marker ids, marker read/write scoped to the id (legacy plain opencode never satisfies a v2 lookup), the 12-value cap with zero-padded ids so no substring false positives pass, and the id-then-category fallback.

• The cache-gate seam test is qualified by construction: the direct cached_program call with the raw host line returns None in the same test, which is exactly the miss the unfixed call site produced (running the unfixed path end to end would have performed a real network npm install).

• cargo test --locked --manifest-path src-tauri/Cargo.toml --lib: 1796 passed, 0 failed, 74 ignored (live smokes). cargo clippy --locked --all-targets -- -D warnings: clean. Rust-only change; no frontend surface touched, so the npm/Playwright gates are not exercised by this diff.

• Review passes: one deep review (approve; two nits ignored with reasons: a u32-overflow version string falls back to the v1 package exactly as the base commit did and npm 404s clearly, and values beyond the pre-existing 10,000-entry catalog cap were already rejected before this change) and one independent quick pass whose single finding is the cache-gate fix above; both ran without seeing each other's findings.

• npm run build (typecheck + bundle) — N/A, Rust-only

• npm test — N/A, Rust-only

• cargo test --manifest-path src-tauri/Cargo.toml (lib suite, locked; clippy clean)

• Relevant Playwright tests — N/A, no UI changed

Checklist

• Commit messages follow <type>: <description>
• Docs in docs/ updated if behavior changed — nothing to update: docs/agent-updates.md already documents both packages per generation, and no doc states the installed package or marker name
• Preview mocks added in src/preview.ts for new IPC commands — N/A, no new IPC commands
• No telemetry, secrets or personal paths added