Args:
    clips: Sweep Session slots for active clips.
    devices: Include device chains for each track.
    max_scenes: Maximum number of scenes to probe for Session clips.

Returns:
    Dictionary with script info, session snapshot, track counts, and notes.

Note:
    Measured 2026-08-29 against Live 12.4.5: Round-trip handshake takes ~450 ms.
    Group tracks do not support arm state ('armed' returns null).
    If Live collection introspection reports zero tracks, index probing is used as a fallback.

Args:
    track: index in ``song.tracks`` (or ``song.return_tracks`` for
        ``kind="return"``). Ignored for ``kind="master"``.
    kind: ``track`` | ``return`` | ``master``.

``volume`` and ``panning`` are normalised, not dB: 0.85 is 0 dB (measured),
and the scale is not linear. ``display`` carries the dB reading where Live
offered one.

``arm`` is read only after ``can_be_armed`` says the question applies, because
reading it on a group track raises inside Live and would break the whole batch
(measured). It comes back as ``null`` where it does not apply.

Device names, send values and which clip slots are filled are measured by
probing indices in one batch, because Live's collections report no length
(see ``notes``).

Checks the slot is filled first, because a clip only exists while its slot
has one and every property read would otherwise fail one by one.

Notes are not properties; use ``read_clip_notes``. Automation is not a property
either; use ``read_automation``.

``warping``, ``warp_mode`` and ``pitch_coarse`` are reachable only through a generic
path, because a per-command bridge has no command for them and a missing command is
easily mistaken for a missing capability (docs/architecture.md, 'the restart tax').
Each was read, written, read back and restored on 2026-08-29 against Live 12.4.5, and
all three rows are ``verified``. ``pitch_fine`` is read-verified only, with no write
attempted on it, and the integer mapping behind ``warp_mode`` is still a hypothesis:
confirm it against ``clip.available_warp_modes``, which is the authoritative per-clip
list.

Writing ``warping`` invalidates every time field this tool just returned. Measured
2026-08-30 against Live 12.4.5 on a 1.14-unit audio clip at 120 BPM: turning warping
on took ``loop_end`` from 0.5704 to 1.1408 and ``end_marker`` from 1.1408 to 2.2816,
both doubled, while ``length`` did not follow. At 60 BPM the same toggle moved
neither. The mechanism is not established and is not claimed; what is established is
that the numbers move and that the factor tracks the tempo. Call this again after any
write to ``warping`` rather than reusing what it said before.

The parameter count is worth reading first. A third-party plug-in reporting exactly
one parameter has not been configured; see the ``configure_needed`` flag and the note
it carries. That is a limit in Live, not in this server, and it is lifted only in
Live's GUI.

The parameter probe here only has to settle "exactly one, or more than one",
which is what tells an unconfigured plug-in apart from a configured one. For
the full list call ``describe`` with ``with_parameters=True``.

Device order can be changed, though it is widely assumed to be fixed. The call sits
on the Song rather than on the Device, which is why it reads as missing:
``Song.move_device(device, target_chain, position)``, catalogued as
``song.move_device`` and reachable through ``lom_call``. Measured 2026-08-30 against
Live 12.4.5 on a scratch track: ``['Eq8', 'Compressor2', ...]`` became
``['Compressor2', 'Eq8', ...]``.

Loading order is still worth planning, because it decides what survives. Effects are
appended, and an instrument replaces the instrument already on the track (measured),
taking its settings and its clip envelopes with it. Reordering afterwards is a
convenience; a replaced instrument is not recoverable.

This is the route to the dynamic surface: what a loaded plug-in actually exposes,
which no catalog can know in advance because it is decided at runtime and, for
third-party plug-ins, by what the user picked up in Configure mode.

Args:
    path: a LOM path, e.g. ``song``, ``song.tracks[0]``,
        ``song.tracks[0].devices[1]``. Look shapes up in ``ableton://catalog``.
    depth: how far to descend. Deep describes over a whole set can be slow
        and the cost is unmeasured.
    with_parameters: for a device path, survey every parameter (name, value,
        min/max, quantized steps, display unit) instead of just the child
        counts, and diagnose an unconfigured plug-in rather than returning a
        useless one-entry list.

Methods are never callable through a path. Use ``lom_call``, and only names on the
script's own allowlist.

Measured caveat (Live 12.4.5): the parameter survey depends on
``lom_describe`` reporting a ``count`` for the ``parameters`` child, and a
Live ``Vector`` that refuses ``len()`` reports none, so the survey comes back
with zero parameters on a device that has them. When that happens this tool falls
back to probing parameter indices, reports the names it found, and says which
of the two answers you are looking at.

Args:
    kind: Track kind ('midi', 'audio', or 'return').
    index: Insertion index (-1 inserts at the end without shifting existing track indices).
        Ignored for return tracks.
    name: Optional track name for MIDI or audio tracks.

Returns:
    Dictionary reporting track creation status and before/after track counts.

Note:
    Inserting before existing tracks renumbers subsequent track indices.
    Measured 2026-08-30 against Live 12.4.5.

Two-step process: with confirm=False, searches browser and returns candidate items
along with currently selected track info. With confirm=True and a chosen uri or item_path,
loads the item.

Args:
    query: Search string for browser items.
    root: Optional browser root category to search within.
    uri: Browser item URI returned from search step.
    item_path: Direct filesystem or library item path.
    limit: Maximum number of search candidates to return (defaults to 12).
    confirm: Confirmation flag required to execute loading.

Returns:
    Dictionary containing search candidates or device load verification details.

Note:
    Browser.load_item targets the current selection rather than an explicit track argument.
    Target track is determined by song.view.selected_track.
    Inside racks or drum racks, target destination is determined by rack.view.selected_chain
    or rack.view.selected_drum_pad.
    Instruments replace the track instrument, whereas audio/MIDI effects are appended.

Args:
    track: Track index in song.tracks (MIDI track required).
    slot: Scene/slot index in track.clip_slots.
    length_beats: Clip loop length in beats (defaults to 4.0).
    name: Optional clip name.

Returns:
    Dictionary containing clip creation status and read-back verification.

Note:
    Does not overwrite occupied slots; call delete_clip first if replacing.

When confirm=False, inspects slot and reports clip details that would be deleted.

Args:
    track: Track index in song.tracks.
    slot: Scene/slot index in track.clip_slots.
    confirm: Confirmation flag required to execute deletion.

Returns:
    Dictionary reporting deletion status or pending loss report.

When confirm=False, reports track name, devices, filled Session slots,
and Arrangement clips that would be removed.

Args:
    track: Track index in song.tracks.
    confirm: Confirmation flag required to execute deletion.

Returns:
    Dictionary reporting deletion status or pending loss report.

Note:
    Deleting a track shifts all subsequent track indices down by one.

When confirm=False, reports device details and parameter count that would be removed.

Args:
    track: Track index in song.tracks.
    device: Device index within track chain.
    confirm: Confirmation flag required to execute deletion.

Returns:
    Dictionary reporting deletion status or pending loss report.

Note:
    Deleting a device shifts subsequent device indices down by one.
    Measured 2026-08-30 against Live 12.4.5: Devices can be reordered via song.move_device.

Args:
    track: Track index in song.tracks (MIDI track).
    slot: Scene/slot index in track.clip_slots.
    notes: List of note dictionaries with pitch, start_time, duration, velocity,
        and optional probability, velocity_deviation, release_velocity, mute.
    mode: Write mode, 'replace' (clears prior notes and writes) or 'append'.
    verify: When True, reads back notes and compares with input using diff.

Returns:
    Dictionary containing write confirmation, validation reports, and optional diff.

Note:
    Times are in beats and clip-local, so beat 0 is the clip's own start.

    A list straight from ``read_clip_notes`` can be written back. Live adds
    ``note_id`` to every note it hands out, which is identity rather than content,
    so the keys in :data:`~ableton_maestro.music.notes.TOLERATED_NOTE_KEYS` are
    dropped instead of refused and reported as ``input_keys_ignored``. Every other
    unrecognised key is an error.

    ``pitch``, ``start_time`` and ``duration`` are never defaulted. A reader that
    substitutes ``start_time=0.0`` and ``duration=0.25`` for missing keys turns a
    list built with ``pos``/``dur`` (the humanise spelling) into a pile of
    sixteenths stacked on beat 0, and reports success while doing it. Wrong keys are
    refused before anything is sent.

    ``replace`` is remove-then-write inside one handler call. Live's own
    ``set_notes`` appends, so a second write silently doubles a melody instead of
    correcting it (measured: 63 + 23 = 86 notes). Ask for ``append`` by name when
    adding is the intent. An empty list with ``mode="replace"`` clears the clip.

    A note does not come back bit-identical to the note sent. Times and durations
    return with a small deviation in both directions. Measured 2026-09-01 against
    Live 12.4.5: a sent 0.29 read back as 0.29000010406260407 and a sent 0.18 as
    0.17999994796869798, about 4e-7 relative. Re-measured 2026-09-02 against Live
    12.4.5 at 124 BPM: both values reproduced to every digit, a ``start_time`` of
    2.29 came back as 2.290000104062604, and a duration of 0.5 came back exactly.
    The cause is not established: it is not a tick grid (no grid of 96, 192, 480 or
    960 per quarter produces those numbers) and not a single float32 conversion
    (float32 of 0.29 is 0.28999999). That 0.5 survives while 0.29 does not is
    consistent with a binary-representable value passing through untouched, but the
    mechanism is not claimed here. At 124 BPM the error is around 50 nanoseconds, so
    musically it is nothing. It matters only for comparison: never test a note time
    for equality. The diff run here already uses a tolerance, which is why it
    reports ``0 changed`` for values that differ in the seventh decimal.

Args:
    track: Track index in song.tracks.
    slot: Scene/slot index in track.clip_slots.
    from_time: Start beat of window to query. Omit to query from beat 0.
    time_span: Window length in beats. Omit to query to the end of the clip.
    count_only: When True, returns note count without transferring note data.
    check: When True, performs validation checks on queried notes.

Returns:
    Dictionary containing notes, count, window parameters, and validation report.

Note:
    Times and positions are expressed in clip-local beats. Muted notes are included
    and carry ``mute: true``. ``time_span`` is a length in beats, not an end beat:
    beats 24 to 32 is ``from_time=24, time_span=8``.

    Windowing and counting exist because there was otherwise no way to ask a small
    question. Measured 2026-08-30: surveying note density across 59 drum clips meant
    reading every note of every clip, and one clip alone came back as 384 notes and
    57k characters, past the tool-result cap, so it spilled to a file. The LOM has no
    ``note_count`` on ``Clip`` at all, so counting meant transferring everything in
    order to measure it. ``count_only=True`` counts inside Live and carries back one
    integer.

    With ``count_only`` there is nothing to validate, so ``check`` is ignored. With a
    window, ``check`` sees the window and not the clip.

    Returned notes are sorted by time, then pitch. Live hands its notes back ordered
    by pitch, which is the one order a musical instruction never means: "the third
    note", "every other note" and "the last note" are all about when a note sounds.
    Measured 2026-08-30 against Live 12.4.5: four notes written at beats 0, 1, 2, 3
    with pitches 72, 60, 67, 62 came back 60, 62, 67, 72, so taking every other entry
    off the raw list picks alternating pitches rather than alternating beats, silently
    and plausibly. For Live's own order call ``get_notes_extended`` through
    ``lom_call``.

Reads notes, calculates quantized positions, writes back using mode='replace',
and verifies the result.

Args:
    track: Track index in song.tracks.
    slot: Scene/slot index in track.clip_slots.
    grid: Quantization grid in beats (0.25 = sixteenth notes, 0.5 = eighth notes).
    strength: Quantization strength from 0.0 (no change) to 1.0 (full snap).
    quantize_ends: When True, also quantizes note durations / end positions.

Returns:
    Dictionary containing write result and quantization details.

Args:
    track: Track index in song.tracks.
    slot: Scene/slot index in track.clip_slots.
    semitones: Number of semitones to transpose (positive or negative).
    out_of_range: Action when transposed notes exceed MIDI range 0..127
        ('error', 'clamp', or 'drop').

Returns:
    Dictionary reporting transposition status and details.

Note:
    Measured 2026-08-29 against Live 12.4.5: Audio clips are transposed by setting
    clip.pitch_coarse (-48..48 semitones).

Args:
    track: Track index in song.tracks (or song.return_tracks). Ignored for kind="master".
    volume: Normalized volume level 0.0 to 1.0 (0.85 corresponds to 0 dB).
    pan: Panning position from -1.0 (hard left) to 1.0 (hard right).
    sends: Dictionary of send amounts 0.0 to 1.0 keyed by send letter ('A', 'B') or index.
    mute: Track mute state boolean (unsupported on master track).
    solo: Track solo state boolean (unsupported on master track).
    kind: Track kind ('track', 'return', or 'master').

Returns:
    Dictionary reporting mixer adjustments and before/after verification readings.

Args:
    track: Track index in song.tracks (or song.return_tracks). Ignored for kind="master".
    device: Device index within track chain.
    parameter: Parameter index (as string e.g. "1") or parameter name/glob pattern.
    value: Parameter target value.
    kind: Track kind ('track', 'return', or 'master').

Returns:
    Dictionary reporting write status, resolved parameter index, and read-back value.

Note:
    Parameter values are normalised, not the unit the device displays. Read ``min``
    and ``max`` (``describe`` with ``with_parameters=True``) rather than assuming
    a range.

    The curve from 0..1 onto the displayed unit is not linear and differs per
    device. On one third-party compressor Attack is ``v^4 * 1000 ms``, so writing
    "10 ms" linearly lands at 316 ms, a factor of 30, silently. Where the device
    reports a display, aim with the display; where it does not (all VST2), write
    normalised and calibrate by eye once.

    Measured 2026-08-30 against Live 12.4.5: a quantized parameter takes discrete
    steps, so a written 0.5 can legitimately read back as something else, and that
    is reported as a clamp rather than as a failure.

Args:
    track: Track index in song.tracks (Session clip).
    slot: Scene/slot index in track.clip_slots.
    parameter: LOM path to DeviceParameter (e.g. 'song.tracks[0].mixer_device.volume').
    points: Breakpoint coordinates as [[beat, value], ...] in clip-local beats.
    interpolation: Interpolation mode ('linear', 'hold', 'exponential', 'ease_in', 'ease_out').
    exponent: Exponent for non-linear interpolation shapes.
    resolution: Sampling step size in beats (defaults to 0.0625 = 1/16th note).
    clear_first: When True, clears prior envelope points before writing.
    verify: When True, samples envelope back and compares with generated curve.

Returns:
    Dictionary reporting write status, sampling metrics, and verification comparison.

Note:
    Automation envelopes can be written directly to Session clips;
    subsequently arrange the clip to transfer automation to the Arrangement timeline.

Args:
    track: Track index in song.tracks.
    slot: Scene/slot index in track.clip_slots.
    parameter: LOM path to the target DeviceParameter.
    start: Optional start position in clip-local beats (default skips initial beat 0 guard).
    end: Optional end position in clip-local beats.
    points: Number of sample points to evaluate (clamped 2 to 512, default 64).

Returns:
    Dictionary with sampled values, range, and envelope presence flags.

When confirm=False, inspects clip and reports envelope existence without deleting.

Args:
    track: Track index in song.tracks.
    slot: Scene/slot index in track.clip_slots.
    parameter: Target DeviceParameter LOM path when clearing a single envelope.
    all_envelopes: When True, clears all envelopes on the clip.
    confirm: Confirmation flag required to execute clearing.

Returns:
    Dictionary reporting clearance status or pending envelope details.

Args:
    track: Source track index in song.tracks.
    slot: Source scene/slot index in track.clip_slots.
    at_beat: Target start position on the Arrangement timeline in beats.
    to_track: Destination track index (defaults to source track).

Returns:
    Dictionary containing placement status and arrangement clip counts.

Live's song.set_or_delete_cue toggles: adds a locator if absent, or deletes if present.
When confirm=False, reports current locator positions and requires confirmation.

Args:
    at_beat: Timeline position in beats.
    name: Optional name for newly created locator.
    confirm: Confirmation flag required to execute locator toggle.

Returns:
    Dictionary reporting locator status and resulting cue points.

Args:
    at_beat: Target song time in beats from timeline start.

Returns:
    Dictionary with write confirmation and read-back song time.

Args:
    from_beat: Optional timeline position in beats to cue before playback.
    continue_playing: When True, resumes from current position rather than restarting.

Returns:
    Dictionary reporting start status and is_playing confirmation.

Args:
    clips: When True, also stops active Session clips via song.stop_all_clips.
    quantized: Whether clip stop adheres to global launch quantization.

Returns:
    Dictionary reporting stop status and is_playing confirmation.

Args:
    bpm: Target tempo in beats per minute (catalog validated 20.0 to 999.0).

Returns:
    Dictionary reporting tempo write and read-back result.

Args:
    enabled: Optional loop enabled state boolean.
    start: Optional loop start position in beats.
    length: Optional loop length in beats.

Returns:
    Dictionary reporting write status and before/after verification values.

Args:
    path: Filesystem path to .als or .adg file.
    with_notes: When True, parses clip notes and calculates note metrics.
    track: Optional track name or index to query a specific track instead of the entire project.
    report: When True, includes formatted human-readable summary report.

Returns:
    Dictionary containing project metadata, track list, devices, and automation structure.

Note:
    This is Channel B, a peer of the live connection rather than a fallback. It
    answers two questions the LOM never will: what is in someone else's project, and
    where an envelope's breakpoints actually sit.

    Automation lives in two places and the LOM can read only one of them. Measured
    over 174 professional projects: 52 (30 %) have clip envelopes but 159 (91 %) have
    track automation, and a tool that counted clip envelopes alone reported 110 of
    those projects as unautomated. The two layers are reported separately here and
    are never added together.

Supported operations: 'sidechain', 'configure', 'attribute', 'restore'.
Target project file must not be currently open in Live unless confirmed.

Args:
    path: Path to target .als project file.
    operation: Modification operation ('sidechain', 'configure', 'attribute', 'restore').
    confirm: Confirmation flag required to execute modifications.
    target_track: Name of track containing target device.
    source_track: Name of track providing trigger source (sidechain operation).
    device: Device index within target track.
    tap: Sidechain tap point ('pre' or 'post').
    expression: ElementTree path expression (attribute operation).
    value: New attribute value or configure assignment string ('<index>=<name>; ...').
    attribute: Attribute name to modify (attribute operation, defaults to 'Value').
    index: Target element match index when expression matches multiple elements.
    create: When True, creates attribute if missing.
    backup: Backup filepath required for restore operation.
    allow_live_running: Allow write when Live runs (auto-enabled if holding another set).

Returns:
    Dictionary reporting write status, changes made, and verification report.

Note:
    ``sidechain`` is here for the set Live is not holding, someone else's project
    wired on disk. Measured in a corpus of 174 projects: 74 of 82 in the
    house/trance BPM window use sidechain compression, median 6 wirings each. For
    the set on screen use ``lom_set`` and keep the read-back.

    ``configure`` fills a plugin's parameter strip, which no LOM call can do
    whatever the strip currently holds. Measured 2026-09-01 against Live 12.4.5: two
    parameters written into an instance whose strip held nothing came back on reopen
    with their real values, writable through ``lom_set`` with ``read_back: applied``.
    Live allocates 128 slots per instance and leaves them all in the file, so
    nothing is inserted; three fields of an existing element are filled.

    ``attribute`` sets one attribute anywhere in the file, addressed by an
    ElementTree expression. An expression matching more than one element is refused
    unless ``index`` picks one.

Args:
    path: Dotted LOM path starting with 'song', 'app', or 'song.view'.

Returns:
    Dictionary containing path, value, type, and optional parameter display string.

Args:
    path: Settable dotted LOM path.
    value: Value to set, or object reference dict {'__path__': '...'} for object properties.

Returns:
    Dictionary reporting requested, before, after, clamped, and changed status. For a
    device parameter it also carries ``display`` and ``is_quantized``.

Note:
    Live does not accept an out-of-range value silently, however often that is given
    as the reason to read back. Measured 2026-08-30 against Live 12.4.5: it refuses
    them out loud and stores nothing. ``...mixer_device.volume.value = 1.4`` answers
    ``live_error "Invalid value. Check the parameters range with min/max"`` and the
    value stays at 0.85; ``song.tempo = 5000`` answers "Tempo out of range"; a
    panning of 5 is refused the same way.

    What the read-back really catches, measured the same day, is quantised snap:
    ``<Compressor>.parameters[10].value = 0.4`` (Model: Peak / RMS / Expand) stored 0,
    reporting ``before 1, after 0, clamped: true, changed: true, read_back:
    "clamped", display: "Peak", is_quantized: true``. A caller who asks for a value
    between two steps gets a different one and is told nowhere else.

    Two more, measured separately: a write can apply asynchronously, so the first
    read is stale (``read_back: "not_observed"``, which is not ``clamped``), and a
    method call has no read-back at all. Live also ignores an unknown property name
    silently and reports success for a write that did nothing.

    A collection (``song.tracks``, ``device.parameters``) cannot be assigned. Address
    an element and set one of its properties.

    A Live object cannot travel as a plain value, and there are two cases behind
    that. ``song.tracks[0].mixer_device.volume`` is a DeviceParameter and the wanted
    value is one level down, so write ``...volume.value``. But a property whose value
    really is an object (``song.view.selected_track``, ``song.view.selected_scene``,
    ``song.view.detail_clip``, ``browser.hotswap_target``, ``clip.groove``, and on a
    device ``input_routing_type`` and ``input_routing_channel``) is written by passing
    a reference: ``value={"__path__": "song.tracks[2]"}``, resolved through the same
    resolver and guards as a ``lom_call`` argument (protocol §5.4). Handed a plain
    JSON value the first five answer ``not_settable`` (measured 2026-08-29 against
    Live 12.4.5). The two routing properties, a compressor's sidechain source and its
    tap point, take their reference out of
    ``<device>.available_input_routing_types`` and
    ``...available_input_routing_channels``, never a name string, because RoutingType
    carries ``category`` and ``display_name`` read-only and an ``attached_object``
    pointing at the Track (measured 2026-08-30, same Live).

Args:
    path: Dotted LOM path to target object.
    method: Allowlisted method name to execute.
    args: Optional list of positional arguments.

Returns:
    Dictionary reporting method execution status.

Args:
    ops: List of operation dictionaries ({'op': 'get'|'set'|'call', 'path': ...}).
    atomic: When True, stops execution on the first encountered error.

Returns:
    Dictionary containing ordered results for each operation.

Note:
    A batch runs inside one handler call, so nothing Live recomputes between
    operations is visible to a later operation in the same batch. A read that
    follows a transport jump in the same batch still reports the position from
    before the move. Measured 2026-09-01 against Live 12.4.5: four jumps
    interleaved with four reads returned four identical pre-jump values and no
    error at all. That is the failure shape to expect here. It does not raise; it
    returns a clean set of numbers that look like a measurement of a parameter which
    never changes, and the conclusion drawn from them is wrong. Sample a moving
    transport with one call per position, never inside a batch.

Args:
    path: Target LOM path.
    depth: Traversal depth for nested child collections (defaults to 1).

Returns:
    Dictionary reporting object class, properties, children, and allowed methods.

Args:
    type_name: Dotted Live enum name (e.g. 'Song.Quantization'). Omit to list enum types.

Returns:
    Dictionary of enum member names and mappings.