Adopt the shared prefix constant everywhere, trigger CI on build_helpers, pin the copy_files gate

.github/workflows/ci-docker.yml

@@ -21,6 +21,7 @@ on:
       - "esphome/core/**"
       - "esphome/writer.py"
       - "esphome/build_gen/**"
+      - "esphome/build_helpers/**"
       - "esphome/espidf/**"
       - "esphome/platformio/**"
       - "esphome/components/bk72xx/**"

esphome/writer.py

@@ -7,7 +7,7 @@ import re
 import time
 
 from esphome import loader
-from esphome.build_helpers.pch import PCH_ARTIFACT_NAMES
+from esphome.build_helpers.pch import PCH_ARTIFACT_NAMES, PCH_PREFIX_HEADER
 from esphome.compiled_config import save_compiled_config
 from esphome.config import iter_component_configs, iter_components
 from esphome.const import (
@@ -247,7 +247,7 @@ def copy_src_tree():
         Path(
             "esphome/core/ring_buffer.h"
         ),  # moved to components/ring_buffer/, removed in 2026.11.0
-        Path("esphome/core/pch_prefix.h"),  # build machinery, not user API
+        Path(PCH_PREFIX_HEADER),  # build machinery, not user API
     }
     include_l = []
     for target, _ in source_files_l:

script/determine-jobs.py

@@ -498,7 +498,11 @@ ESP32_PLATFORMIO_TEST_COMPONENTS = frozenset(
 # drives every PlatformIO build). The esp32 platform component is already in
 # ESP32_PLATFORMIO_TEST_COMPONENTS, so its changes are covered by the normal
 # component-narrowing path.
-ESP32_PLATFORMIO_TRIGGER_PATH_PREFIXES = ("esphome/platformio/",)
+ESP32_PLATFORMIO_TRIGGER_PATH_PREFIXES = (
+    "esphome/platformio/",
+    # The pch wiring the strict smoke jobs police lives here
+    "esphome/build_helpers/",
+)
 
 # Standalone files that, when changed, trigger the PlatformIO compile test:
 #   - esphome/build_gen/platformio.py -- the PlatformIO build generator

tests/unit_tests/components/esp32/test_pch_wiring.py

@@ -0,0 +1,33 @@
+"""The pch script must reach PlatformIO builds only; the native ESP-IDF
+toolchain has its own pch flow in build_gen/espidf.py."""
+
+from contextlib import suppress
+from unittest.mock import patch
+
+import pytest
+
+from esphome.components import esp32
+from esphome.const import Toolchain
+from esphome.core import CORE
+
+
+@pytest.mark.parametrize(
+    ("toolchain", "copied"),
+    [(Toolchain.PLATFORMIO, True), (Toolchain.ESP_IDF, False)],
+)
+def test_copy_files_gates_pch_script_on_toolchain(
+    toolchain: Toolchain, copied: bool
+) -> None:
+    CORE.toolchain = toolchain
+    with (
+        patch.object(esp32, "_write_sdkconfig"),
+        patch.object(esp32, "_write_idf_component_yml"),
+        patch.object(esp32, "copy_pch_script") as copy_script,
+        patch.object(esp32, "write_file_if_changed"),
+        patch.object(esp32, "get_partition_csv"),
+        patch.dict(CORE.data, {}, clear=False),
+        # Later copy_files steps need a full build dir; the pch gate runs first
+        suppress(Exception),
+    ):
+        esp32.copy_files()
+    assert copy_script.called is copied

tests/unit_tests/test_pch_prefix.py

@@ -9,7 +9,7 @@ from esphome.build_helpers.pch import PCH_PREFIX_HEADER
 REPO = Path(__file__).parents[2]
 
 
-def test_host_pch_prefix_resolves() -> None:
+def test_pch_prefix_resolves() -> None:
     prefix = REPO / PCH_PREFIX_HEADER
     assert prefix.is_file()
     body = prefix.read_text()