Removing NFC tag after playback completion triggers invalid pause retries and prevents replay

[Gudsfile]

Description

When a "CD" (NFC tag) reaches the end of playback and the NFC tag is then removed, Jukebox attempts to pause the player even though nothing is currently playing.

This generates repeated warnings in the logs and appears to leave the system in an inconsistent state.

Logs

2026-06-21 15:13:34,947 - jukebox - WARNING - Playback pause failed; retrying in 2.000s
2026-06-21 15:13:37,021 - jukebox - INFO    - Pausing player `PlayerName`
2026-06-21 15:13:37,071 - jukebox - WARNING - pause failed, probably a not available transition: UPnP Error 701 received: Transition not available from 192.168.1.x

Steps to reproduce

1. Place an NFC tag associated with a CD that exists in the library.
2. Let playback reach the end naturally.
3. Remove the NFC tag after playback has finished.

Observed behavior

• Jukebox attempts to pause the player even though no track is currently playing.
• Retry attempts are triggered and generate repeated log messages.
• The system appears to enter an inconsistent state.
• Placing the same NFC tag again does not restart playback.
• The only way I have found to recover is to place another NFC tag that is known by the library.

Expected behavior

If playback has already finished, removing the NFC tag should either be treated as a no-op or Jukebox should verify the player state before sending a pause command.

The system should return to a normal state and allow the same NFC tag to be placed again to restart playback.

Additional information

I have not yet tested the following scenario:

1. Wait until all pause retries have completed.
2. Place an NFC tag that is not known by the library.

So I do not yet know whether the inconsistent state persists in that case.

[Gudsfile]

Root cause analysis

The underlying issue

The state machine (transition_playback.py) only knows about NFC tag presence/absence over time, it has no visibility into the actual transport state of the player. PlayerPort only exposes play/pause/resume/stop, no is_playing(). As a result, when a track ends naturally while the tag is still on the reader, the state machine stays stuck in Playing(tag=X), with no way to detect that the player stopped on its own.

Exact bug sequence

1. Track ends naturally, tag still on reader -> state stays Playing(tag=X) (no data available to detect the end).
2. Tag removed -> transition_playback.py:47-52: Playing -> Waiting(tag=X, removed_at=now), command None.
3. After pause_delay_seconds -> transition_playback.py:58-63: Waiting -> Paused, command "pause".
4. sonos_player_adapter.py calls speaker.pause() on a transport that's already stopped -> Sonos raises SoCoUPnPException UPnP 701 ("Transition not available") -> _log_upnp_failure logs the warning, then _execute_with_recovery re-raises it as a generic PlaybackError.
5. handle_tag_event.py:91-101 catches PlaybackError -> builds a RetryState with exponential backoff -> state stays Waiting (success is never adopted) -> repeated logs as seen in the issue -> once retries are exhausted, exhausted=True, stuck indefinitely.
6. Placing the same tag back: transition_playback.py:56-57, the Waiting case with tag_id == playing_tag returns Playing(tag=X) directly, command None. The domain thinks it's "Playing" but nothing was restarted -> exactly the reported symptom "placing the same tag doesn't resume playback".

Possible fixes

• Option A, transport awareness: give PlayerPort a way to report actual playback state (e.g. is_playing()), and have the state machine react to a natural end -> transition straight to Idle instead of attempting a pause.
• Option B, targeted mitigation: make pause() tolerant of UPnP 701 on the Sonos adapter side. The state would then correctly reach Paused instead of getting stuck in Waiting.

Files involved: transition_playback.py, handle_tag_event.py, playback_state.py/entities.py, sonos_player_adapter.py, domain/errors.py.