[6uclz1]

What this changes for you

Nothing on the command line or the wire. Command names, options, help text, JSON envelopes, exit codes and the TCP protocol are unchanged. The command surface snapshot, the public contract snapshot, the generated skill docs and the generated client all regenerate with no diff.

The work cuts duplicated code. Synth and effect behaviour now lives in one place in the CLI and one place in the Remote Script, instead of two copies that could drift apart. 43 files changed, +1759 / −3117. Quality harness warnings fall from 447 to 416 and duplicate groups from 97 to 66, with 0 failures.

Commits, in order

1. Subtract. Deletes seven require_* validators that only their own tests called, and the unread CLIENT_METHOD_SPEC_BY_NAME. Its import-time duplicate check becomes a test.
2. device commands. Seven commands that take only the track and device selectors repeated the same 13-option signature. They now come from one registration factory.
3. synth / effect commands. The two modules were parallel copies. commands/_device_family.py builds both groups from a DeviceFamily. find stays in each module because its --type parameter name (synth_type, effect_type) is part of the command surface snapshot.
4. Shared Typer parameter types. TrackArgument, ClipArgument, ProjectOption and the note source and filter options were spelled out at about 150 call sites. They now live in commands/_params.py, applied by a codemod. Clip and arrangement notes get / notes clear each come from one filter-command factory.
5. Client. Three hand-written pass-through setters move into CLIENT_METHOD_SPECS, so the generator writes them. The clip and arrangement note-args builders become one _note_args.
6. Pin, then the Remote Script change. No test asserted the messages or hints on the synth/effect error paths, so a characterization test lands first. It passes on the old code and on the new. Then device_families.py replaces the second copy of each step: the supported-device check, the parameter payload, standard key resolution, seven backend methods and seven handlers. The handler factory passes each backend method as an explicit attribute, so test_backend_protocol_has_no_unused_methods still sees every call.
7. Harness. quality_harness/globs.py replaces two identical _expand_globstar copies. The quality harness baseline is regenerated, and the client spec table is kept in name order.

How it was verified

• ruff check, ruff format --check, the full pytest suite (1435 passed), the quality harness with the baseline (exit 0), and the Remote Script Python 3.11 compatibility check.
• All four generators rerun with no diff.
• ableton-cli --help, --version and python -m build pass. The wheel contains device_families.py.
• Old vs new runs against 2b1921d:
  • Remote backend: 156 synth/effect calls, 63 of them error paths, with byte-identical results.
  • CLI: 20 invocations through ableton_cli.cli:main, covering argument-validation failures and unreachable-Live failures. Identical JSON envelopes and exit codes.
• Independent review on a second model. It ran its own comparisons: a recursive help and param dump of the whole CLI (7081 lines), 253 handler cases and 81 CLI-to-client calls. All identical, apart from the call style noted below.

Not run: a manual check against a running Ableton Live. One synth and one effect command on a real device is worth a minute before merging.

For the reviewer

• Call style. _device_family.py looks up client methods by string template, as CommandSpec.client_method already does across the CLI. The Remote Script side uses explicit attributes instead, because a parity test reads them statically. The one small call-style change is that synth <type> keys now passes synth_type by keyword rather than position. The real client's parameter has that name.
• Baseline. The net warning count fell, but the regenerated baseline also takes in drift that was already on main. The live count there was 447 against 428 baselined. About 8 new entries come from _device_family.py itself, from its Typer signatures.
• Left as is. The remaining duplicate groups were left on purpose:
  • generated code;
  • typed client methods;
  • CLI and Remote Script validators that cannot share a package;
  • the per-module run_client_command wrappers. Tests monkeypatch get_client on each module, so these wrappers are how the tests inject their fakes.

---

Generated by Claude Code

[6uclz1]

Live verification (Ableton Live 12.4.6, macOS)

The PR's Remote Script (0e008fa) was installed with install-remote-script --yes and loaded by a fresh Live launch. I loaded Wavetable and Utility onto one MIDI track of a new set and ran the commands below.

Preflight: wait-ready and doctor passed (8/8). All 175 commands are present and the command set hash is unchanged.

Synth

• synth parameter set on Wavetable Osc 1 Transp: 0 → 7 → 0. before and after were correct.
• synth find (--type wavetable / meld), synth parameters list, synth observe and synth wavetable keys returned OK.
• Error paths returned the expected INVALID_ARGUMENT messages and hints:
  • out-of-range value (value must be between -24.0 and 24.0)
  • a device that is not a synth (Utility)
  • type mismatch (synth drift set on Wavetable)
  • device index out of range
• --read-only with a write returned READ_ONLY_VIOLATION.

Effect

• effect parameter set on Utility Balance: 0 → 0.5 → 0. before and after were correct.
• effect find --type utility, effect parameters list, effect observe and effect utility keys returned OK.
• Error paths returned the expected messages and hints:
  • out-of-range value
  • a device that is not an effect (Wavetable)
  • type mismatch (effect eq8 set on Utility)

CLI parity: Before the Remote Script swap, I ran 14 read-only synth/effect commands from both the main CLI and the PR CLI against the same running Live. stdout and exit codes were byte-identical.

Afterwards I reinstalled main's Remote Script.

Existing issues on main, not caused by this PR

These behave the same with main's Remote Script, and this PR does not touch synth_specs.py or effect_specs.py.

• synth wavetable observe/set fails with Missing required standard synth keys for wavetable: filter_cutoff, filter_resonance. Live 12.4.6 names these parameters Flt 1 …, for example Flt 1 Res, not Filter 1 Freq.
• effect utility observe/set fails with Missing required standard effect keys for utility: gain.
• browser search is rejected under --read-only (search_browser_items is classified as a write command).