From 0c97e2b3546cf8d5cf5d7ad04f96337019c61f85 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Sun, 23 Aug 2026 14:31:18 -0500
Subject: [PATCH] Route single-archive waves through the batch runner

A dependency chain (api -> noise-c -> libsodium) discovers one archive
per wave, so the <2 gate sent every chained download through the legacy
per-file path. Sized registry archives now always use the batch runner:
one download method, one bar; the per-file path remains only for
unknown-size, git, and local sources.
---
 esphome/platformio/library.py               |  6 ++++--
 tests/unit_tests/test_platformio_library.py | 16 ++++++++++------
 2 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/esphome/platformio/library.py b/esphome/platformio/library.py
index 9840e907bf..a6bb8a1715 100644
--- a/esphome/platformio/library.py
+++ b/esphome/platformio/library.py
@@ -923,10 +923,12 @@ def _prefetch_wave(
                 # A warm build must stay silent
                 continue
             components.append(component)
-        if len(components) < 2:
+        if not components:
             return
+        # Single-item waves (a dependency chain discovers one archive per
+        # wave) go through the same runner: one download method, one bar
         _LOGGER.info(
-            "Downloading %d libraries: %s",
+            "Downloading %d library archive(s): %s",
             len(components),
             ", ".join(c.name for c in components),
         )
diff --git a/tests/unit_tests/test_platformio_library.py b/tests/unit_tests/test_platformio_library.py
index 140f8bb169..d24eae6ec6 100644
--- a/tests/unit_tests/test_platformio_library.py
+++ b/tests/unit_tests/test_platformio_library.py
@@ -762,16 +762,18 @@ def test_prefetch_wave_warm_cache_is_silent(
     assert "Downloading" not in caplog.text
 
 
-def test_prefetch_wave_single_archive_skips_the_pool(
-    monkeypatch: pytest.MonkeyPatch,
+def test_prefetch_wave_single_archive_uses_the_batch(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
 ) -> None:
-    """One archive gains nothing from a pool; the sequential call keeps its
-    progress bar."""
+    """A dependency chain discovers one archive per wave; it downloads
+    through the same runner so there is one download method and one bar."""
+    caplog.set_level("INFO")
+    calls: list[str] = []
     monkeypatch.setattr(
         URLSource,
         "download",
-        lambda self, dir_suffix, **kw: (_ for _ in ()).throw(
-            AssertionError("prefetched")
+        lambda self, dir_suffix, force=False, salt="", namespace="", progress=None: (
+            calls.append(self.url)
         ),
     )
     lib._prefetch_wave(
@@ -779,6 +781,8 @@ def test_prefetch_wave_single_archive_skips_the_pool(
         "",
         "idf",
     )
+    assert calls == ["https://x/a.tar.gz"]
+    assert "Downloading 1 library archive(s): a" in caplog.text
 
 
 def test_normalize_dependencies_forms(caplog) -> None: