Breaking wire-protocol change shipped without bumping REMOTE_SCRIPT_VERSION; ping/doctor cannot detect a stale installed Remote Script

[6uclz1]

Summary

PR #88 changed the wire protocol (plain integer track/device args → track_ref/device_ref objects; tracks_list result gained required stable_ref), but REMOTE_SCRIPT_VERSION in remote_script/AbletonCliRemote/command_backend_contract.py is still "0.4.0" — the same string the pre-#88 script reports. A stale installed Remote Script is therefore indistinguishable from the current one, and ping / doctor succeed right before every ref-based command fails.

Observed symptoms (CLI from current main vs. a pre-#88 script running in Live, both reporting 0.4.0)

• tracks list → exit 13, PROTOCOL_INVALID_RESPONSE: result.tracks[0].stable_ref is required
• track name set --track-index 0 "Drums" (and all track/synth/effect ref-based commands) → INVALID_ARGUMENT: track must be an integer
• clip name set-many → PROTOCOL_CONNECTION_CLOSED (old script closes the socket on unknown commands instead of returning an error; current command_backend_registry.py handles this cleanly, but nothing tells the user their script is old)
• multi-step batch run → PROTOCOL_CONNECTION_CLOSED (single-step works)

None of these errors point at the actual problem ("your installed Remote Script is outdated — run install-remote-script").

Why the existing safeguards don't catch it

• src/ableton_cli/capabilities.py only verifies that the ping payload's command_set_hash matches the supported_commands list in the same payload — an internal-consistency check, not a compatibility check against what this CLI build expects.
• The version string carries no information about argument-shape changes.

Suggested fix

1. Bump REMOTE_SCRIPT_VERSION (and/or PROTOCOL_VERSION) on any breaking wire-protocol change; add a CI/test guard that fails when validator/contract shapes change without a version bump.
2. Make doctor (and ideally the first command of a session) compare the running script's version/command_set_hash against the bundled remote_script/ sources and surface "installed Remote Script is stale, run ableton-cli install-remote-script --yes and reload the control surface".
3. When a ref-based command gets track must be an integer back, map it to a dedicated hint about the protocol mismatch instead of the generic invalid-argument passthrough.

Hit on 2026-07-05 during a production session; worked around by routing everything through batch run with old-style integer args, one step per request.

🤖 Generated with Claude Code