Trim controller.py prose: 4594 → 3723 lines (−871)

[bdraco]

What does this implement/fix?

controllers/remote_build/controller.py was 67% prose by line
count — overlong docstrings and inline-comment paragraphs that
paraphrased the code or recapped design history rather than
flagging non-obvious behaviour. The file read as a wall of text
that made it hard to scan for the actual logic.

Trimmed every docstring / comment block that paraphrased what
the code already says; kept the WHY-style notes (hidden
invariants, surprising orderings, post-fix bug references) per
CLAUDE.md's comment-style rule.

controller.py: 4594 → 3723 lines (−871, −19%).
Prose-to-code ratio: 67% → 57%.

Concretely

• Module docstring: 48 → 18 lines (kept the pairing model
  summary; dropped the "Manual hosts have no version /
  fingerprint resolution yet…" historical note and the
  long-form enabled-flag explanation).
• WS-command docstrings (request_pair, submit_job,
  download_artifacts, unpair, edit_pairing_endpoint,
  record_pair_request, set_pairing_window,
  rotate_identity, lookup_peer_for_status,
  set_settings, set_offloader_settings,
  set_pairing_enabled) all lose their Args/Returns/Raises
  walls. The type signatures already carry that contract; the
  trimmed docstring keeps the behaviour summary + any
  non-obvious caveats.
• __init__ attribute-explainer comments drop from 15-20
  lines down to 4-8 each (the _pairings, _peer_link_clients,
  _pending_peers, _approved_peers, _open_peer_links,
  _offloader_alerts, _peer_queue_status,
  _offloader_remote_jobs, _pairing_window_clients,
  _pair_status_listeners, _listeners blocks).
• Method docstrings on internals (_probe_pairing_endpoint,
  _probe_and_rebind_endpoint, _apply_pair_status_result,
  _lookup_open_peer_link_client, _validate_submit_job_config,
  _build_submit_job_bundle, _upsert_host, _sweep_stale_pairings_at_endpoint,
  peers_snapshot, pairings_snapshot,
  offloader_alerts_snapshot, build_scheduler_snapshot,
  _peer_summaries, _on_offloader_peer_link_opened) trimmed
  similarly.
• In-body comment paragraphs (the 51-line security-defense
  block in record_pair_request, the 15-line listener-attach
  rationale at the top of start, the 13-line queue-status
  push explanation in register_peer_link_session) reduced to
  the one or two sentences a future reader actually needs.

Behaviour preservation

No code lines changed; only comment and docstring lines
removed. All 3117 tests pass. Ruff + codespell clean.

Related issue or feature (if applicable):

• Internal cleanup, no issue.

Types of changes

• Bugfix (non-breaking change which fixes an issue) — bugfix
• New feature (non-breaking change which adds functionality) — new-feature
• Enhancement to an existing feature — enhancement
• Breaking change (fix or feature that would cause existing functionality to not work as expected) — breaking-change
• Refactor (no behaviour change) — refactor
• Documentation only — docs
• Maintenance / chore — maintenance
• CI / workflow change — ci
• Dependencies bump — dependencies

Frontend coordination

• No frontend change needed
• Companion frontend PR: esphome/device-builder-dashboard-frontend#

Checklist

• The code change is tested and works locally.
• Pre-commit hooks pass (ruff, codespell, yaml/json/python checks).
• Tests have been added or updated under tests/ where applicable.
• components.json has not been hand-edited (regenerate via script/sync_components.py if a sync is needed).
• Architecture-level changes are reflected in docs/ARCHITECTURE.md and/or docs/API.md.

[Copilot]

Copilot wasn't able to review any files in this pull request.

[codspeed-hq]

Merging this PR will not alter performance

✅ 12 untouched benchmarks

---

_{Comparing trim-controller-prose (f350a45) with main (936b9f8)}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.21%. Comparing base (936b9f8) to head (f350a45).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #630   +/-   ##
=======================================
  Coverage   99.21%   99.21%           
=======================================
  Files          90       90           
  Lines       10757    10757           
=======================================
  Hits        10673    10673           
  Misses         84       84           

Flag	Coverage Δ
py3.12	99.19% <ø> (ø)
py3.14	99.21% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...ice_builder/controllers/remote_build/controller.py	99.67% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.