fix(vehicle): prevent unsafe BLE write timeout failover

[Bre77]

Intent

Close the last BLE write-timeout double-execution gap in the VehicleBluetooth/VehicleRouter confirmation ladder, per an upstream Home Assistant review finding confirmed by field data (tfa-ble-timeout-rates-j3 study: of 3 verifiable BLE transport-errors, 2 had actually executed on the vehicle). Previously, VehicleBluetooth._send() wrapped ANY write_gatt_char failure (BleakError or TimeoutError, whether pre-submission or mid-backend-I/O) into BluetoothTransportError, and VehicleRouter fails over to the cloud secondary on that exception - so a write that was actually submitted and reached the vehicle before the local wait failed could be replayed on the cloud transport, double-executing a non-idempotent command (locks, toggles, schedule add/remove, etc).

Fix: split write-failure classification by delivery certainty in _send()'s write try/except. Only BleakCharacteristicNotFoundError - raised synchronously by bleak while resolving the WRITE_UUID characteristic, strictly before any backend I/O - stays BluetoothTransportError (provably pre-submission, safe for Router to retry). Every other BleakError/TimeoutError from write_gatt_char happens inside backend I/O (D-Bus/CoreBluetooth/an ESPHome proxy) where delivery can't be proven either way, so instead of raising BluetoothTransportError it: (1) races any already-armed broadcast watcher for the remaining window (a matching VCSEC status broadcast can still confirm success despite the failed write call), then (2) raises plain BluetoothTimeout. Because BluetoothUnconfirmedCommand subclasses BluetoothTimeout, this lands in the exact same 'except BluetoothTimeout' ladder in _sendVehicleSecurity/_sendInfotainment that already handles a lost post-write ack (verify-by-state rung, then raise_unconfirmed gating) - no new exception type needed. _send_optimistic() (used by confirmation='optimistic') previously ONLY ever raised BluetoothTransportError unconditionally on any write failure ('consulting nothing else'); it now also follows this same split - a provable pre-submission failure still always raises, but a delivery-ambiguous failure now follows raise_unconfirmed instead of always raising, since even optimistic/no-wait mode must not let a fallback router blind-retry a command that may have already reached the car. This required threading a command-name string into _send_optimistic for its debug logging (previously only took domain+bytes).

Deliberately scoped narrow: reads (_getVehicleSecurity/_getInfotainment) are NOT touched by this change - they don't override the ladder, so a write-ambiguous read still propagates plain BluetoothTimeout and Router still fails over on it normally, which stays safe since reads carry no double-execution risk. The pre-write connect_if_needed() path (already outside this try/except, wrapped separately by connect()) is unaffected.

Also fixed, found during self-review while investigating this: get_private_key() in tesla.py wrote its PEM (the Fleet API/BLE command-signing EC key) with the process default file mode instead of 0600 - confirmed the upstream HA review's claim was accurate. Mirrored the exact existing chmod(path, 0o600) pattern already used by the sibling get_rsa_private_key() a few lines below in the same file (that one already had it correct), wrapped in the same try/except OSError: pass. This was judged small and low-risk enough (4-line mechanical fix copying an established in-file pattern, not a new design decision) to include in this PR rather than deferring, plus one new test asserting the created file's mode is 0o600.

Tests added: tests/test_ble_send_transport.py (split BleakCharacteristicNotFoundError-vs-other-write-failure classification, driving _send() directly with a mocked GATT client), tests/test_ble_broadcast_confirmation.py new WriteFailureBroadcastRaceTests class (a matching broadcast still confirms success despite write_gatt_char raising, and a write timeout with no broadcast still raises BluetoothUnconfirmedCommand - drives the real unmocked _send state machine), tests/test_ble_optimistic_and_best_effort.py (optimistic mode's new raise_unconfirmed-following behavior for ambiguous writes), tests/test_ble_write_timeout_router.py (new file - the actual double-exec regression test: a real VehicleBluetooth wrapped in a real VehicleRouter with a fake cloud fallback, proving the fallback's door_lock is never invoked when the primary's write is submitted-then-ambiguous, contrasted with a provable pre-submission failure which still correctly fails over), tests/test_tesla_private_key.py (new file - PEM file mode assertion). Updated existing tests in test_ble_send_transport.py that previously asserted BluetoothTransportError for a generic BleakError/TimeoutError from write_gatt_char - those now correctly assert BluetoothTimeout instead, since only the characteristic-not-found case is pre-submission-provable.

Docs: docs/bluetooth_vehicles.md's confirmation-ladder section gained a new markdown table with an explicit GATT-write rung row describing the pre-submission-vs-ambiguous split; the BluetoothTransportError paragraph and the optimistic-mode/raise_unconfirmed bullets were also corrected since they previously said 'only a write/transport failure raises' unconditionally, which is no longer true. AGENTS.md (the actual file behind the CLAUDE.md symlink) got a new bullet documenting the write-delivery-certainty split plus corrections to three existing stale cross-references that previously implied ALL write_gatt_char failures raise BluetoothTransportError.

All local checks pass: ruff check, pyright --strict on tesla_fleet_api (tests/ is intentionally not pyright-strict per this repo's existing CI config, confirmed by reading .github/workflows), and pytest (291 tests, up from 290 baseline). No CHANGELOG.md or other auto-generated files were touched.

What Changed

• Classified BLE GATT write failures by delivery certainty: provable pre-submission failures still raise BluetoothTransportError, while ambiguous backend write failures now flow through the timeout/unconfirmed confirmation ladder to avoid unsafe router replays.
• Updated broadcast/addressed-reply handling, optimistic best-effort behavior, and Router coverage for ambiguous BLE writes, with regression tests for fallback suppression and safe pre-submission failover.
• Hardened Tesla private key creation to write new PEM files with 0600 permissions and refreshed BLE timeout documentation to match the new behavior.

Risk Assessment

✅ Low: The change is narrowly scoped to BLE write-failure classification, preserves the router no-replay invariant for ambiguous mutating writes, and includes focused regression coverage and matching docs.

Testing

Inspected the target diff, ran the focused BLE transport/router/optimistic/private-key tests, generated a JSON evidence transcript showing router fallback behavior and 0o600 key mode, then ran the full test suite; all automated tests passed after retrying the evidence script with uv run python due to no system python binary.

Evidence: BLE write-timeout behavior evidence

{
  "evidence": [
    {
      "case": "submitted_then_timed_out_write_is_not_replayed",
      "exception": "BluetoothUnconfirmedCommand",
      "fallback_door_lock_calls": 0,
      "is_unconfirmed": true,
      "outcome": "raised",
      "raise_unconfirmed": true,
      "write_exception": "TimeoutError"
    },
    {
      "case": "mid_write_bleak_error_is_not_replayed",
      "exception": "BluetoothUnconfirmedCommand",
      "fallback_door_lock_calls": 0,
      "is_unconfirmed": true,
      "outcome": "raised",
      "raise_unconfirmed": true,
      "write_exception": "BleakError"
    },
    {
      "case": "pre_submission_characteristic_resolution_failure_fails_over",
      "fallback_door_lock_calls": 1,
      "outcome": "returned",
      "raise_unconfirmed": true,
      "result": {
        "response": {
          "reason": "fallback-cloud",
          "result": true
        }
      },
      "write_exception": "BleakCharacteristicNotFoundError"
    },
    {
      "case": "default_best_effort_ambiguous_write_returns_without_fallback",
      "fallback_door_lock_calls": 0,
      "outcome": "returned",
      "raise_unconfirmed": false,
      "result": {
        "response": {
          "reason": "",
          "result": true
        }
      },
      "write_exception": "TimeoutError"
    },
    {
      "case": "new_private_key_file_mode",
      "mode": "0o600",
      "path_basename": "private_key.pem"
    }
  ]
}

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed (2) ✅

• ⚠️ tesla_fleet_api/tesla/vehicle/bluetooth.py:744 - On an ambiguous write_gatt_char failure, this path waits only for the broadcast watcher and never drains the addressed response queue. If the write actually reached the car and an addressed ack or rejection arrives before/after the local write timeout, _send() still raises BluetoothTimeout; the mutating wrapper can then return best-effort success with raise_unconfirmed=False, hiding a real car-side rejection. Treat this like the normal post-write wait: race _await_response as well as any broadcast watcher before falling through to unconfirmed.

🔧 Fix: Handle addressed replies after write failures
2 issues (1 warning, 1 info) still open:

• ⚠️ tesla_fleet_api/tesla/vehicle/bluetooth.py:732 - Generic BleakError is not always delivery-ambiguous: Bleak backends can raise BleakError("Not connected") before issuing the backend write call (for example, BlueZ checks connection state before WriteValue: https://raw.githubusercontent.com/hbldh/bleak/v2.0.0/bleak/backends/bluezdbus/client.py). If the link drops after connect_if_needed() but before write_gatt_char(), this now becomes BluetoothTimeout, so mutating commands can return best-effort success or block router failover even though nothing was submitted. Classify known pre-submission BleakError cases such as not-connected as BluetoothTransportError before the ambiguous branch.
• ℹ️ README.md:175 - The top-level README still says BLE GATT write failures raise BluetoothTransportError, but this change intentionally makes most write failures raise BluetoothTimeout/BluetoothUnconfirmedCommand. Update this summary so users who catch BluetoothTransportError separately do not miss the new ambiguous-write behavior.

🔧 Fix: Classify disconnected BLE writes pre-submission
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• git diff --stat 623bfb19d1e9243c47cb485954722d9585fa2d38..HEAD and git diff --name-only 623bfb19d1e9243c47cb485954722d9585fa2d38..HEAD
• uv run pytest tests/test_ble_send_transport.py::SendTransportErrorTests tests/test_ble_broadcast_confirmation.py::WriteFailureBroadcastRaceTests tests/test_ble_optimistic_and_best_effort.py tests/test_ble_write_timeout_router.py tests/test_tesla_private_key.py
• python - <<'PY' > /tmp/no-mistakes-evidence/01KXAJ9P4GFAZD0615S31N64MG/ble_write_timeout_behavior.json (failed because python is not installed in PATH; retried successfully with uv run python)
• uv run python - <<'PY' > /tmp/no-mistakes-evidence/01KXAJ9P4GFAZD0615S31N64MG/ble_write_timeout_behavior.json
• uv run pytest tests

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.