Merge branch 'pch-strict-ci' into host-pch

# Conflicts:
#	esphome/platformio/toolchain.py

.github/workflows/ci-docker.yml

@@ -197,6 +197,7 @@ jobs:
         # the default.
         id:
           - esp8266-arduino
+          - esp8266-arduino-native
           - esp32-arduino-platformio
           - esp32-arduino-esp-idf
           - esp32-idf-platformio
@@ -207,6 +208,17 @@ jobs:
           - ln882x-arduino
           - nrf52
           - host
+        # Strict by default so a new matrix id cannot silently join in the
+        # degrade-quietly mode the knob exists to catch; the knob is inert
+        # where no pch code runs (esp32-*-platformio, nrf52).
+        # Opt-outs: libretiny GCC rejects its own pch until a toolchain bump.
+        include:
+          - id: bk72xx-arduino
+            pch_strict: "0"
+          - id: rtl87xx-arduino
+            pch_strict: "0"
+          - id: ln882x-arduino
+            pch_strict: "0"
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Download image artifact
@@ -218,6 +230,7 @@ jobs:
       - name: Compile ${{ matrix.id }}
         run: |
           docker run --rm \
+            -e ESPHOME_PCH_STRICT="${{ matrix.pch_strict || '1' }}" \
             -v "${{ github.workspace }}/docker/test_configs:/config" \
             "ghcr.io/esphome/esphome-amd64:${{ needs.check-docker.outputs.tag }}" \
             compile "${{ matrix.id }}.yaml"

.github/workflows/ci.yml

@@ -1298,8 +1298,10 @@ jobs:
           echo ""
 
           # ESP8266 Arduino built directly (no PlatformIO); compile validates
-          # config first, so a separate config pass is redundant.
-          python3 script/test_build_components.py -e compile -t esp8266-ard -c "$TEST_COMPONENTS" -f --toolchain arduino --fail-on-no-tests
+          # config first, so a separate config pass is redundant. Strict pch:
+          # exercises the native ninja pch (and its probe edge) against real
+          # component configs; the docker matrix smoke-tests both toolchains.
+          ESPHOME_PCH_STRICT=1 python3 script/test_build_components.py -e compile -t esp8266-ard -c "$TEST_COMPONENTS" -f --toolchain arduino --fail-on-no-tests
 
   device-builder:
     name: Test downstream esphome/device-builder

docker/test_configs/esp8266-arduino-native.yaml

@@ -0,0 +1,8 @@
+esphome:
+  name: docker-test-esp8266-native
+
+esp8266:
+  board: d1_mini
+  toolchain: arduino
+
+logger:

esphome/arduino8266/framework.py

@@ -19,6 +19,7 @@ from typing import NamedTuple
 
 from esphome.build_helpers.ccache import ccache_defaults_env
 from esphome.build_helpers.ninja import find_ninja
+from esphome.build_helpers.pch import ccache_pch_env
 from esphome.build_helpers.tools_cache import ARDUINO8266_TOOLS_CACHE, tools_cache_path
 from esphome.core import EsphomeError, Version
 from esphome.framework_helpers import str_to_lst_of_str
@@ -156,4 +157,6 @@ def ccache_env(ccache: str | None) -> dict[str, str]:
     """
     if ccache is None:
         return {}
-    return ccache_defaults_env(get_arduino8266_tools_path() / "ccache")
+    env = ccache_defaults_env(get_arduino8266_tools_path() / "ccache")
+    env.update(ccache_pch_env())
+    return env

esphome/build_gen/arduino8266.py

@@ -27,11 +27,26 @@ import sys
 from typing import TYPE_CHECKING, NamedTuple
 
 from esphome.arduino8266.framework import toolchain_tool
+from esphome.build_helpers.ccache import effective_ccache_basedir
+from esphome.build_helpers.idedata import is_joined_include
 from esphome.build_helpers.ninja import (
     escape as _e,
     quote_path as _q,
     shell_token as _shell_token,
 )
+from esphome.build_helpers.pch import (
+    PCH_CORE_HEADER,
+    PCH_HEADER_NAME,
+    mark_pch_emitted,
+    pch_checksum,
+    pch_consumer_escalation,
+    pch_degraded,
+    pch_disabled_degraded,
+    pch_enabled,
+    pch_header_text,
+    pch_probe_args,
+    pch_strict,
+)
 from esphome.components.esp8266 import build_surgery
 from esphome.components.esp8266.boards import (
     BOARDS,
@@ -874,18 +889,25 @@ def _ninja_compile_edges(
     root: Path,
     group: str,
     flags: str = "",
+    cxx_override: tuple[str, str] | None = None,
 ) -> list[str]:
-    """Emit compile edges for ``sources``; return the object paths."""
+    """Emit compile edges for ``sources``; return the object paths.
+
+    ``cxx_override`` is a (flags, implicit-dep) pair applied to C++ edges
+    only, replacing ``flags`` (used for the precompiled header).
+    """
     objects = []
     for src in sources:
         rel = src.relative_to(root).as_posix()
         obj = f"obj/{group}/{rel}.o"
         escaped_obj = _e(obj)
-        lines.append(
-            f"build {escaped_obj}: {SOURCE_KIND_FOR_SUFFIX[src.suffix]} {_e(src)}"
-        )
-        if flags:
-            lines.append(f"  flags = {flags}")
+        kind = SOURCE_KIND_FOR_SUFFIX[src.suffix]
+        override = cxx_override if kind == "cxx" and cxx_override else None
+        implicit = f" | {override[1]}" if override else ""
+        lines.append(f"build {escaped_obj}: {kind} {_e(src)}{implicit}")
+        edge_flags = override[0] if override else flags
+        if edge_flags:
+            lines.append(f"  flags = {edge_flags}")
         # Escaped once here: the returned paths only ever appear in build
         # statements (archive/link inputs), which use ninja escaping.
         objects.append(escaped_obj)
@@ -1087,6 +1109,13 @@ def write_project(paths: InstalledPaths, ccache: str | None) -> bool:
         "  depfile = $out.d",
         "  deps = gcc",
         "  description = AS $out",
+        # No $ccache: the .gch is compiled once per build dir and ccache
+        # cannot cache it usefully (its bytes embed build-dir paths)
+        "rule pch",
+        "  command = $cxx -MMD -MF $out.d -x c++-header $cxxflags $flags -c $in -o $out",
+        "  depfile = $out.d",
+        "  deps = gcc",
+        "  description = PCH $out",
         # Plain assembler, as SCons's ASCOM: no preprocessor, so no
         # depfile and no $flags (defines/includes) either
         "rule asm",
@@ -1176,7 +1205,8 @@ def write_project(paths: InstalledPaths, ccache: str | None) -> bool:
     # One source of truth with the PlatformIO path: esp8266/__init__ pins
     # build_src_flags (the throw_stubs force-include); -include paths
     # resolve against the source root
-    src_parts: list[str] = []
+    src_other: list[str] = []
+    src_includes: list[str] = []
     src_it = iter(
         lex_build_flags(_pio_option("build_src_flags", ""), "build_src_flags")
     )
@@ -1187,15 +1217,117 @@ def write_project(paths: InstalledPaths, ccache: str | None) -> bool:
                 raise EsphomeError(
                     "build_src_flags has a trailing '-include' with no header"
                 )
-            src_parts.append(f"-include {_q(src_dir / header)}")
+            src_includes.append(header)
+        elif is_joined_include(tok):
+            # Left in src_other it would precede the pch include and
+            # silently defeat the .gch
+            src_includes.append(tok[len("-include") :])
         else:
-            src_parts.append(_shell_token(tok))
-    src_extra = " ".join(src_parts)
+            src_other.append(_shell_token(tok))
+    include_flags = [f"-include {_q(src_dir / h)}" for h in src_includes]
     # One shared variable instead of repeating the flags line on every src
     # edge (hundreds of edges in a real project)
-    lines.append(f"srcflags = {src_extra}")
+    lines.append(f"srcflags = {' '.join(src_other + include_flags)}")
+    src_cxx_override = None
+    if pch_enabled() and any(tok.startswith("-include") for tok in cxxflags):
+        # $cxxflags expands first, so a user -include there means GCC would
+        # never load the .gch
+        _LOGGER.warning(
+            "A -include in build_flags prevents the precompiled header from "
+            "loading; compiling without it"
+        )
+        pch_degraded("a user -include precedes the pch")
+    elif pch_enabled():
+        # C++ src edges swap the force-includes for one precompiled prefix
+        # header (same content plus defines.h); C/assembly keep srcflags
+        pch_header = build_dir / PCH_HEADER_NAME
+        pch_includes = (*src_includes, PCH_CORE_HEADER)
+        pch_text = pch_header_text(pch_includes)
+        checksum = None
+        try:
+            if ccache:
+                # The .sum exists only for CCACHE_PCH_EXTSUM; ninja's depfile
+                # handles staleness. Strip resolved and raw build paths
+                # (symlinks) so identical configs share cache entries
+                flags_id = (
+                    " ".join(cxxflags)
+                    .replace(effective_ccache_basedir(), "")
+                    .replace(str(CORE.build_path), "")
+                )
+                # The header text covers include order
+                checksum = pch_checksum(
+                    src_dir,
+                    pch_includes,
+                    (
+                        pch_text,
+                        str(paths.framework),
+                        str(paths.toolchain),
+                        flags_id,
+                    ),
+                )
+        except (OSError, UnicodeError) as err:
+            # Identity unknown: a stale cache entry must never be served
+            _LOGGER.warning(
+                "Could not establish the pch identity; compiling without it: %s", err
+            )
+            pch_degraded(f"identity unknown: {err}")
+        else:
+            _LOGGER.info(
+                "Compiling with a precompiled header "
+                "(set ESPHOME_PCH_ENABLE=0 to disable)"
+            )
+            write_file_if_changed(pch_header, pch_text)
+            sum_path = build_dir / f"{PCH_HEADER_NAME}.gch.sum"
+            if checksum is not None:
+                # Generate-time stamp: a hand-run ninja can rebuild the .gch
+                # while this .sum lags
+                write_file_if_changed(sum_path, checksum + "\n")
+            else:
+                # A stale .sum from an earlier ccache run must not survive
+                sum_path.unlink(missing_ok=True)
+            gch = _e(f"{PCH_HEADER_NAME}.gch")
+            lines.append(f"build {gch}: pch {_e(pch_header)}")
+            if src_other:
+                lines.append(f"  flags = {' '.join(src_other)}")
+            # Relative -include: absolute would break cross-device ccache.
+            # -Wno-error keeps a rejected .gch a warning under user -Werror;
+            # strict inverts it so any consumer rejection reds the build
+            # (rejection is per-process, so the probe alone cannot prove
+            # the consumers)
+            escalation = pch_consumer_escalation()
+            cxx_parts = src_other + [
+                f"-Winvalid-pch {escalation} -include {PCH_HEADER_NAME}"
+            ]
+            lines.append(f"srccxxflags = {' '.join(cxx_parts)}")
+            pch_dep = gch
+            if pch_strict():
+                # Consumers wait on the probe stamp, so an unloadable .gch
+                # reds the build here instead of warning ~100 times
+                probe = " ".join(pch_probe_args(PCH_HEADER_NAME, source=os.devnull))
+                lines.append("rule pchprobe")
+                # $out only expands in rule text, hence the inline stamp
+                lines.append(
+                    f"  command = $cxx $cxxflags $flags {probe}"
+                    " && $python $buildtool touch $out"
+                )
+                lines.append("  description = PCHPROBE $out")
+                # Runs when the .gch is (re)built; strict consumer -Werror
+                # covers a cached .gch this process cannot load
+                lines.append(f"build esphome_pch.probe: pchprobe {gch}")
+                if src_other:
+                    lines.append(f"  flags = {' '.join(src_other)}")
+                pch_dep = f"{gch} esphome_pch.probe"
+            src_cxx_override = ("$srccxxflags", pch_dep)
+            mark_pch_emitted()
+    else:
+        pch_disabled_degraded()
     src_objs = _ninja_compile_edges(
-        lines, _collect_sources(src_dir), src_dir, "src", flags="$srcflags"
+        lines,
+        _collect_sources(src_dir),
+        src_dir,
+        "src",
+        flags="$srcflags",
+        cxx_override=src_cxx_override,
     )
 
     ld_deps = [f"ld/{_COMMON_LD_NAME}"]

esphome/build_gen/build_tool.py

@@ -6,6 +6,7 @@ started esphome and must not depend on the package being importable.
 Subcommands:
     ar <ar-binary> <archive> <rspfile>   remove stale archive, then ``ar rcs``
     copy <src> <dst>                     copy a file
+    touch <path>                         create/update a stamp file
 
 The ar rspfile carries one object path per line (the generating rule must
 use ``$in_newline``, never ``$in``).
@@ -83,9 +84,18 @@ def _run_copy(src: str, dst: str) -> int:
     return 0
 
 
+def _run_touch(path: str) -> int:
+    try:
+        Path(path).touch()
+    except OSError as err:
+        print(f"touch: {path} failed: {err}", file=sys.stderr)
+        return 1
+    return 0
+
+
 # mode -> (handler, expected operand count); surplus argv means a
 # mis-specified ninja rule and must error, not silently drop operands
-_MODES = {"ar": (_run_ar, 3), "copy": (_run_copy, 2)}
+_MODES = {"ar": (_run_ar, 3), "copy": (_run_copy, 2), "touch": (_run_touch, 1)}
 
 
 def main() -> int:

esphome/build_gen/espidf.py

@@ -4,6 +4,14 @@ import json
 import logging
 from pathlib import Path
 
+from esphome.build_helpers import pch
+from esphome.build_helpers.pch import (
+    PCH_DEFAULT_HEADERS,
+    PCH_HEADER_NAME,
+    mark_pch_emitted,
+    pch_enabled,
+    pch_header_text,
+)
 from esphome.components.esp32 import (
     get_esp32_variant,
     get_excluded_builtin_components,
@@ -279,9 +287,74 @@ idf_component_register(
 target_link_options(${{COMPONENT_LIB}} PUBLIC
     {link_opts_str}
 )
+{_pch_cmake()}"""
+
+
+def _pch_cmake() -> str:
+    """The src component's precompiled-header block (C++ TUs only).
+
+    The -include stays relative (resolved from the compiler cwd, the build
+    dir); an absolute path would poison ccache keys.
+    """
+    if not pch_enabled():
+        return ""
+    # Strict inverts: a per-process consumer rejection reds the build.
+    # Baked at generation: a knob flip takes effect when the CMakeLists is
+    # rewritten (every esphome compile); a hand-run idf.py keeps the old one
+    escalation = pch.pch_consumer_escalation()
+    return f"""
+# ESPHome precompiled header (see esphome/build_helpers/pch.py).
+# OBJECT_DEPENDS is on the header, not the .gch: pch-baked headers drop
+# out of TU depfiles, and prepare_pch() touches the header on rebuild.
+target_compile_options(${{COMPONENT_LIB}} PRIVATE
+    "$<$<COMPILE_LANGUAGE:CXX>:-Winvalid-pch>"
+    "$<$<COMPILE_LANGUAGE:CXX>:{escalation}>"
+    "$<$<COMPILE_LANGUAGE:CXX>:-include>"
+    "$<$<COMPILE_LANGUAGE:CXX>:{PCH_HEADER_NAME}>"
+)
+set_source_files_properties(${{app_sources}} PROPERTIES
+    OBJECT_DEPENDS "${{CMAKE_BINARY_DIR}}/{PCH_HEADER_NAME}")
 """
 
 
+def discard_pch() -> None:
+    """Drop the pch sidecars in the IDF build dir."""
+    pch.discard_pch(CORE.relative_build_path("build"))
+
+
+def prepare_pch() -> None:
+    """Build the .gch right before ninja, after every reconfigure, so the
+    compile_commands.json flags and the sdkconfig are the settled ones."""
+    if not pch_enabled():
+        # Self-cleaning escape hatch: drop any previously built .gch
+        pch.discard_pch(CORE.relative_build_path("build"))
+        pch.pch_disabled_degraded()
+        return
+    sdkconfig_path = CORE.relative_build_path(f"sdkconfig.{CORE.name}")
+    try:
+        sdkconfig = sdkconfig_path.read_text(encoding="utf-8")
+    except OSError as err:
+        # Fail closed: the sdkconfig is the .sum's only config identity for
+        # sdkconfig.h-only options; a stand-in marker would collide
+        _LOGGER.warning(
+            "Could not read %s; compiling without the pch: %s", sdkconfig_path, err
+        )
+        pch.discard_pch(CORE.relative_build_path("build"))
+        pch.pch_degraded(f"sdkconfig unreadable: {err}")
+        return
+    pch.prepare_pch(
+        CORE.relative_build_path("build"),
+        PCH_DEFAULT_HEADERS,
+        (
+            str(idf_version()),
+            CORE.cpp_standard or "",
+            sdkconfig,
+            *get_project_compile_flags(),
+            *get_project_cxx_compile_flags(),
+        ),
+    )
+
+
 def write_project(
     minimal: bool = False, builtin_components: list[str] | None = None
 ) -> None:
@@ -301,6 +374,14 @@ def write_project(
         get_component_cmakelists(),
     )
 
+    if pch_enabled():
+        write_file_if_changed(
+            CORE.relative_build_path("build", PCH_HEADER_NAME),
+            pch_header_text(PCH_DEFAULT_HEADERS),
+        )
+        # Consumers carry the -include; gate the ccache relaxation on it
+        mark_pch_emitted()
+
     # Snapshot the exclusion set so has_outdated_files() can trigger a
     # discovery reconfigure when it changes. Excluded components never
     # register in project_description.json, so re-including one (e.g. a

esphome/build_helpers/ccache.py

@@ -21,12 +21,13 @@ def _ccache_runs(ccache: str) -> bool:
     )
 
 
-def parse_enable_env(name: str) -> bool | None:
+def parse_enable_env(name: str, strict: bool = False) -> bool | None:
     """Strictly parse an on/off environment knob; None when unset or invalid.
 
     ``bool(str)`` truthiness would flip ``no``/``off`` to enabled, so only
     1/true/yes/on and 0/false/no/off count; anything else warns and reads
-    as unset so the caller's default policy applies.
+    as unset so the caller's default policy applies — or raises when
+    ``strict`` (a typo must not silently disable a CI gate).
     """
     raw = os.environ.get(name)
     if raw is None:
@@ -39,6 +40,10 @@ def parse_enable_env(name: str) -> bool | None:
         return True
     if lowered in FALSY_ENV_STRINGS:
         return False
+    if strict:
+        from esphome.core import EsphomeError
+
+        raise EsphomeError(f"Unrecognized {name}={raw!r}; use 1 or 0")
     _LOGGER.warning("Ignoring unrecognized %s=%r; use 1 or 0", name, raw)
     return None
 
@@ -87,6 +92,19 @@ def ccache_defaults_env(cache_dir: Path) -> dict[str, str]:
         "CCACHE_DIR": str(cache_dir),
         "CCACHE_NOHASHDIR": "true",
         "CCACHE_DEPEND": "1",
-        "CCACHE_BASEDIR": str(Path(CORE.build_path).resolve()),
+        # A user value wins via the filter below
+        "CCACHE_BASEDIR": effective_ccache_basedir(),
     }
     return {k: v for k, v in defaults.items() if k not in os.environ}
+
+
+def effective_ccache_basedir() -> str:
+    """The prefix ccache rewrites out of hashed paths: a user CCACHE_BASEDIR
+    wins, else the resolved build path (matching ccache_defaults_env)."""
+    from esphome.core import CORE
+
+    raw = os.environ.get("CCACHE_BASEDIR")
+    if raw is not None and Path(raw).is_absolute() and len(Path(raw).parts) > 1:
+        return raw
+    # Unset or degenerate ("", "/", relative): fall back to the build path
+    return str(Path(CORE.build_path).resolve())

esphome/build_helpers/idedata.py

@@ -59,11 +59,11 @@ def warn_if_idedata_missing(get_idedata: Callable[[], dict | None]) -> None:
             _LOGGER.warning("Idedata failure detail", exc_info=True)
 
 
-# C++ translation-unit suffixes used to identify ESPHome source files.
-_CXX_SUFFIXES = (".cpp", ".cc")
+# C++ translation-unit suffixes.
+CXX_SOURCE_SUFFIXES = (".cpp", ".cc", ".cxx")
 # Suffixes of input/output files that appear bare on the command line (and so
 # must not be mistaken for compiler flags).
-_INPUT_FILE_SUFFIXES = (*_CXX_SUFFIXES, ".c", ".o", ".S", ".s")
+_INPUT_FILE_SUFFIXES = (*CXX_SOURCE_SUFFIXES, ".c", ".o", ".S", ".s")
 # Path marker identifying an ESPHome source translation unit.
 _ESPHOME_SRC_MARKER = "/src/esphome/"
 
@@ -72,11 +72,11 @@ def _is_esphome_src(file: str) -> bool:
     """Whether ``file`` is an ESPHome C++ translation unit; normalized to
     ``/`` first since Windows compile DBs use backslashes."""
     return _ESPHOME_SRC_MARKER in file.replace("\\", "/") and file.endswith(
-        _CXX_SUFFIXES
+        CXX_SOURCE_SUFFIXES
     )
 
 
-def _split_command(command: str) -> list[str]:
+def split_command(command: str) -> list[str]:
     r"""Tokenize a compile_commands.json / response-file command string.
 
     On Windows, tokenize per Windows ``argv`` rules via ``CommandLineToArgvW``.
@@ -112,7 +112,7 @@ def _split_command(command: str) -> list[str]:
         ctypes.windll.kernel32.LocalFree(argv)
 
 
-def _expand_response_files(tokens: list[str], directory: Path) -> list[str]:
+def expand_response_files(tokens: list[str], directory: Path) -> list[str]:
     """Inline any ``@response-file`` arguments (paths relative to ``directory``).
 
     GCC response files embed flags that must be expanded so GCC-only flags
@@ -127,8 +127,8 @@ def _expand_response_files(tokens: list[str], directory: Path) -> list[str]:
                 rf = directory / rf
             try:
                 out.extend(
-                    _expand_response_files(
-                        _split_command(rf.read_text(encoding="utf-8")), directory
+                    expand_response_files(
+                        split_command(rf.read_text(encoding="utf-8")), directory
                     )
                 )
                 continue
@@ -147,7 +147,7 @@ def _pick_entry(entries: list[dict]) -> dict:
         if _is_esphome_src(entry["file"]):
             return entry
     for entry in entries:
-        if entry["file"].endswith(_CXX_SUFFIXES):
+        if entry["file"].endswith(CXX_SOURCE_SUFFIXES):
             return entry
     raise ValueError("no C++ translation unit found in compile_commands.json")
 
@@ -157,16 +157,25 @@ def _pick_entry(entries: list[dict]) -> dict:
 _LAUNCHER_STEMS = frozenset({"ccache", "sccache", "distcc", "icecc", "buildcache"})
 
 
-def _is_launcher(token: str) -> bool:
+def is_launcher(token: str) -> bool:
     return Path(token).stem.lower() in _LAUNCHER_STEMS
 
 
+def is_joined_include(tok: str) -> bool:
+    """The joined ``-includefoo.h`` spelling; excludes clang's -include-pch."""
+    return (
+        tok.startswith("-include")
+        and tok != "-include"
+        and not tok.startswith("-include-")
+    )
+
+
 def parse_entry(
     entry: dict, launcher: str | None = None
 ) -> tuple[str, list[str], list[str], list[str]]:
     """Parse one compile_commands entry -> (cxx_path, defines, includes, cxx_flags)."""
     directory = Path(entry["directory"])
-    tokens = _expand_response_files(_split_command(entry["command"]), directory)
+    tokens = expand_response_files(split_command(entry["command"]), directory)
 
     def _include(raw: str) -> str:
         # Resolve against the entry's ``directory`` so cached idedata works
@@ -182,7 +191,7 @@ def parse_entry(
     if not tokens:
         # An empty command, or one that was only the launcher; fail by name
         raise ValueError(f"empty compile command for {entry.get('file')}")
-    if _is_launcher(tokens[0]) and len(tokens) > 1 and not tokens[1].startswith("-"):
+    if is_launcher(tokens[0]) and len(tokens) > 1 and not tokens[1].startswith("-"):
         # Stale DB built with a launcher this run no longer configures; the
         # real compiler is the next token
         _LOGGER.warning("Stripping unconfigured launcher %s", tokens[0])
@@ -195,11 +204,23 @@ def parse_entry(
     defines: list[str] = []
     includes: list[str] = []
     cxx_flags: list[str] = []
+    unresolved_force_includes: list[str] = []
 
     it = iter(tokens[1:])
     for tok in it:
         if tok in ("-c", "-o"):
             next(it, None)  # drop the flag and its argument (input/output)
+        elif tok == "-include" or is_joined_include(tok):
+            # Re-anchor only names next to the compile (the pch); a name
+            # meant for the -I chain must stay untouched
+            raw = next(it, "") if tok == "-include" else tok[len("-include") :]
+            if not raw:
+                _LOGGER.warning("Dropping -include with no argument")
+            elif Path(resolved := _include(raw)).is_file():
+                cxx_flags.extend(("-include", resolved))
+            else:
+                unresolved_force_includes.append(raw)
+                cxx_flags.extend(("-include", raw))
         elif tok.startswith("-D"):
             # ``.strip()`` handles tokens like ``-D CONFIGURED=1`` (a single
             # quoted arg with a space after -D) that some flags arrive as.
@@ -218,6 +239,14 @@ def parse_entry(
             pass  # input/output files
         else:
             cxx_flags.append(tok)
+    for raw in unresolved_force_includes:
+        # A deleted build artifact would otherwise surface only downstream
+        if not any((Path(inc) / raw).is_file() for inc in includes):
+            _LOGGER.warning(
+                "-include %s found neither next to the compile nor on the "
+                "include path; cached idedata may not resolve it",
+                raw,
+            )
     return cxx_path, defines, includes, cxx_flags
 
 
@@ -282,7 +311,7 @@ def _cache_usable(cached: object) -> bool:
     if not isinstance(cached, dict) or "cc_path" not in cached:
         return False
     cxx_path = cached.get("cxx_path")
-    if not isinstance(cxx_path, str) or _is_launcher(cxx_path):
+    if not isinstance(cxx_path, str) or is_launcher(cxx_path):
         return False
     includes = cached.get("includes")
     return isinstance(includes, dict) and isinstance(includes.get("build"), list)
@@ -330,7 +359,7 @@ def load_or_build_idedata(
 def reject_launcher_compiler(cxx_path: str) -> None:
     """Reject a compile DB naming a launcher (ccache) as the compiler; it
     must never be probed, cached, or consumed."""
-    if _is_launcher(cxx_path):
+    if is_launcher(cxx_path):
         raise EsphomeError(
             f"compile_commands.json names the launcher {cxx_path} as the "
             "compiler; the compile database is unusable"

esphome/build_helpers/pch.py

@@ -0,0 +1,549 @@
+"""Shared precompiled-header policy for the build backends.
+
+The prefix either mirrors the TUs' own force-includes (ESP8266) or is a
+curated core-header set (ESP-IDF). ``esphome: includes:`` sources receive
+it too; Arduino.h visibility there is intended (esphome#8693).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from contextlib import suppress
+from dataclasses import dataclass
+import hashlib
+import json
+import logging
+import os
+from pathlib import Path
+import posixpath
+import re
+import stat
+import subprocess
+
+from esphome.build_helpers.ccache import effective_ccache_basedir, parse_enable_env
+from esphome.build_helpers.idedata import (
+    CXX_SOURCE_SUFFIXES,
+    expand_response_files,
+    is_launcher,
+    split_command,
+)
+
+_DOMAIN = "pch"
+
+
+@dataclass
+class _PCHData:
+    emitted: bool = False
+
+
+def _pch_data() -> _PCHData:
+    from esphome.core import CORE
+
+    if _DOMAIN not in CORE.data:
+        CORE.data[_DOMAIN] = _PCHData()
+    return CORE.data[_DOMAIN]
+
+
+def mark_pch_emitted() -> None:
+    """Record that this build's consumers reference the pch."""
+    _pch_data().emitted = True
+
+
+_LOGGER = logging.getLogger(__name__)
+
+# The header and its .gch/.sum sidecars live in the build directory.
+PCH_HEADER_NAME = "esphome_pch.h"
+
+# Every artifact the pch machinery can leave behind, for cleanup.
+PCH_ARTIFACT_NAMES = (
+    PCH_HEADER_NAME,
+    f"{PCH_HEADER_NAME}.gch",
+    f"{PCH_HEADER_NAME}.gch.sum",
+    f"{PCH_HEADER_NAME}.gch.failed",
+)
+
+# The core defines header every backend anchors its prefix on.
+PCH_CORE_HEADER = "esphome/core/defines.h"
+
+# Prefix-header contents for backends that inject a curated set (rather
+# than mirroring the TUs' own force-includes), defines.h first so USE_*
+# macros exist for the rest. Deliberately hard-coded: frequency-derived
+# sets measured no better and kept selecting headers that cannot compile
+# standalone (X-macro, platform-variant). Every entry must be safe to
+# include first in an empty TU. Caveat: application.h/automation.h become
+# ambiently visible, so a TU missing those #includes still builds on such
+# backends; ESPHOME_PCH_ENABLE=0 restores the strict view.
+PCH_DEFAULT_HEADERS = (
+    PCH_CORE_HEADER,
+    "esphome/core/component.h",
+    "esphome/core/helpers.h",
+    "esphome/core/log.h",
+    "esphome/core/application.h",
+    "esphome/core/automation.h",
+)
+
+# ccache cannot hash through a .gch; CCACHE_PCH_EXTSUM makes it hash the
+# .sum sidecar instead of the .gch bytes, which are not reproducible.
+# Keep in sync with the literals in platformio/pch.py.script.
+_CCACHE_PCH_ENV = {
+    "CCACHE_SLOPPINESS": "pch_defines,time_macros",
+    "CCACHE_PCH_EXTSUM": "true",
+}
+
+# Both include forms: an angle include resolving under src/ must enter the
+# digest too; ones that do not resolve simply end the walk
+# Compiler failures that clear on their own must not latch the .failed marker
+_TRANSIENT_ERRORS = ("No space left", "Cannot allocate", "Resource temporarily")
+
+_INCLUDE_RE = re.compile(rb'^\s*#\s*include\s+["<]([^">]+)[">]', re.MULTILINE)
+
+
+def pch_enabled() -> bool:
+    """Precompiled-header knob: default on, ``ESPHOME_PCH_ENABLE=0`` opts out."""
+    return parse_enable_env("ESPHOME_PCH_ENABLE") is not False
+
+
+def pch_strict() -> bool:
+    """CI knob: ``ESPHOME_PCH_STRICT=1`` turns pch degrade paths fatal.
+
+    A set-but-unrecognized value raises: a typo must not silently turn
+    the gate into a no-op that proves nothing.
+    """
+    return parse_enable_env("ESPHOME_PCH_STRICT", strict=True) is True
+
+
+def pch_degraded(reason: str) -> None:
+    """Every degrade path funnels through here; strict mode raises."""
+    if pch_strict():
+        from esphome.core import EsphomeError
+
+        raise EsphomeError(f"ESPHOME_PCH_STRICT: {reason}")
+
+
+def pch_disabled_degraded() -> None:
+    """Strict CI must not read "no pch at all" as success."""
+    pch_degraded("pch disabled by ESPHOME_PCH_ENABLE")
+
+
+def pch_probe_tail(source: str = "-") -> list[str]:
+    """The syntax-only compile shared by the probe and its baseline."""
+    return ["-fsyntax-only", "-x", "c++", source]
+
+
+def pch_probe_args(header: str, source: str = "-") -> list[str]:
+    """Flags that load-check a built .gch via a syntax-only compile.
+
+    Rejection must be a nonzero exit (never just a wording match), so the
+    invalid-pch class is always escalated. ``source`` defaults to stdin
+    (host independent); the ninja probe edge passes a real file.
+    """
+    return [
+        "-Winvalid-pch",
+        "-Werror=invalid-pch",
+        "-include",
+        header,
+        *pch_probe_tail(source),
+    ]
+
+
+def pch_consumer_escalation() -> str:
+    """Consumer-side invalid-pch flag: strict reds the build on rejection
+    (per-process, so the probe alone cannot prove the consumers)."""
+    return "-Werror=invalid-pch" if pch_strict() else "-Wno-error=invalid-pch"
+
+
+def ccache_pch_env() -> dict[str, str]:
+    """Settings ccache needs to cache compiles that consume the .gch;
+    empty unless this build actually emitted one. User-set values win.
+    Native backends export these process-wide; only time_macros affects
+    non-pch TUs."""
+    if not (pch_enabled() and _pch_data().emitted):
+        return {}
+    extsum = os.environ.get("CCACHE_PCH_EXTSUM")
+    if extsum is not None and extsum.strip().lower() not in ("1", "true", "yes", "on"):
+        # ccache then hashes the non-reproducible .gch bytes: permanent misses
+        _LOGGER.warning("CCACHE_PCH_EXTSUM=%s disables pch caching", extsum)
+    env = {k: v for k, v in _CCACHE_PCH_ENV.items() if k not in os.environ}
+    user_sloppiness = os.environ.get("CCACHE_SLOPPINESS")
+    if user_sloppiness is not None and (
+        missing := [
+            t
+            for t in ("pch_defines", "time_macros")
+            if t not in {tok.strip() for tok in user_sloppiness.split(",")}
+        ]
+    ):
+        # Without these ccache declines every pch-consuming compile
+        env["CCACHE_SLOPPINESS"] = ",".join((user_sloppiness, *missing))
+        _LOGGER.warning(
+            "Adding %s to CCACHE_SLOPPINESS so ccache can cache compiles "
+            "that use the precompiled header",
+            ",".join(missing),
+        )
+    return env
+
+
+def pch_extra_scripts() -> list[str]:
+    """The extra_scripts entries a PlatformIO platform registers for the
+    pch; empty when disabled (the script itself has no enable check)."""
+    if not pch_enabled():
+        pch_disabled_degraded()
+        return []
+    return ["post:pch.py"]
+
+
+def pch_header_text(include_headers: Iterable[str]) -> str:
+    """The prefix-header source: exactly these includes, in order."""
+    return "".join(f'#include "{name}"\n' for name in include_headers)
+
+
+def _resolves(path: Path) -> bool:
+    """False when missing; other stat failures propagate (identity unknown,
+    unlike is_file(), which would silently drop the header)."""
+    try:
+        return stat.S_ISREG(path.stat().st_mode)
+    except (FileNotFoundError, NotADirectoryError):
+        return False
+
+
+def _include_closure(src_dir: Path, roots: Iterable[str]) -> dict[str, bytes]:
+    """Include closure of ``roots``: src-relative name -> contents.
+
+    Resolution mirrors the compiler (includer's dir, then src root); names
+    outside ``src_dir`` end the walk and are versioned by the caller. No
+    #ifdef evaluation: over-approximating is the safe direction.
+    """
+    seen: dict[str, bytes] = {}
+    stack: list[tuple[str, str]] = [(name, "") for name in roots]
+    while stack:
+        name, from_dir = stack.pop()
+        for candidate in (f"{from_dir}/{name}" if from_dir else name, name):
+            rel = posixpath.normpath(candidate)
+            if not rel.startswith("..") and _resolves(src_dir / rel):
+                break
+        else:
+            continue
+        if rel in seen:
+            continue
+        try:
+            data = (src_dir / rel).read_bytes()
+        except OSError as err:
+            # A marker would truncate the transitive walk; fail closed
+            _LOGGER.warning("Could not read %s for the pch checksum: %s", rel, err)
+            raise
+        seen[rel] = data
+        parent = posixpath.dirname(rel)
+        stack.extend(
+            # surrogateescape: a non-UTF-8 name just fails to resolve
+            (inc.decode(errors="surrogateescape"), parent)
+            for inc in _INCLUDE_RE.findall(data)
+        )
+    return seen
+
+
+def pch_checksum(
+    src_dir: Path, include_headers: Iterable[str], extra: Iterable[str]
+) -> str:
+    """Digest standing in for the .gch in ccache's hash: the include closure
+    of the prefix header plus caller-supplied identity strings (versioned
+    install paths, flags). Raises OSError when a header's identity cannot
+    be established at all; callers must then compile without a pch."""
+    digest = hashlib.sha256()
+    closure = _include_closure(src_dir, include_headers)
+    for name in sorted(closure):
+        digest.update(name.encode(errors="surrogateescape"))
+        digest.update(closure[name])
+        digest.update(b"\0")
+    for item in extra:
+        digest.update(item.encode(errors="surrogateescape"))
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+# Tokens dropped when retargeting a TU's flags at the prefix header
+# (the pch compile must not touch depfiles)
+_PCH_STRIP_FLAGS_WITH_ARG = frozenset({"-o", "-c", "-MT", "-MF", "-MQ"})
+_PCH_STRIP_FLAGS = frozenset({"-MD", "-MMD", "-MP", "-MM", "-M"})
+
+
+def pch_compile_command(
+    build_dir: Path, header: Path, gch: Path
+) -> tuple[list[str], Path] | None:
+    """The exact src C++ flags from compile_commands.json retargeted at the
+    header, with the directory they resolve against (relative -I paths must
+    be expanded and executed from the same root); None (logged) when no
+    configured C++ TU is available yet."""
+    from esphome.core import CORE
+
+    try:
+        entries = json.loads(
+            (build_dir / "compile_commands.json").read_text(encoding="utf-8")
+        )
+    except (OSError, json.JSONDecodeError) as err:
+        # Configure already succeeded, so an unusable DB is a real anomaly
+        _LOGGER.warning("No usable compile database, skipping pch: %s", err)
+        return None
+    if not isinstance(entries, list):
+        _LOGGER.warning("Malformed compile database, skipping pch")
+        return None
+    # CMake may spell paths through a symlink differently than CORE does
+    # (macOS /tmp vs /private/tmp), so compare resolved paths
+    src_root = Path(CORE.relative_src_path()).resolve()
+    entry = next(
+        (
+            e
+            for e in entries
+            if isinstance(e, dict)
+            and isinstance(e.get("file"), str)
+            and e["file"].endswith(CXX_SOURCE_SUFFIXES)
+            and Path(e["file"]).resolve().is_relative_to(src_root)
+        ),
+        None,
+    )
+    if entry is None:
+        _LOGGER.warning("No src C++ entry in the compile database, skipping pch")
+        return None
+    directory = entry.get("directory")
+    cmd_dir = Path(directory) if isinstance(directory, str) and directory else build_dir
+    command = entry.get("command")
+    tokens = expand_response_files(
+        split_command(command if isinstance(command, str) else ""), cmd_dir
+    )
+    # A DB recorded with ccache enabled prefixes the compiler with the
+    # launcher; the .gch must be compiled directly
+    if tokens and is_launcher(tokens[0]):
+        tokens = tokens[1:]
+    if not tokens:
+        # "arguments"-style or empty entries must skip, not spawn "-x ..."
+        _LOGGER.warning("Compile database entry has no usable command, skipping pch")
+        return None
+    args: list[str] = []
+    arg_it = iter(tokens)
+    for tok in arg_it:
+        if tok in _PCH_STRIP_FLAGS_WITH_ARG:
+            next(arg_it, None)
+            continue
+        if tok in _PCH_STRIP_FLAGS:
+            continue
+        if tok == "-include":
+            # Drop only the injected prefix; user force-includes must reach
+            # the .gch compile or GCC rejects it over the macro mismatch
+            inc = next(arg_it, "")
+            if not inc.endswith(PCH_HEADER_NAME):
+                args.extend(("-include", inc))
+            continue
+        args.append(tok)
+    return [*args, "-x", "c++-header", "-c", str(header), "-o", str(gch)], cmd_dir
+
+
+def _log_pch_in_use() -> None:
+    # The only place a user can discover the knob; emitted only once a
+    # .gch is actually fresh or being built
+    _LOGGER.info(
+        "Compiling with a precompiled header (set ESPHOME_PCH_ENABLE=0 to disable)"
+    )
+
+
+def _read_stamp(path: Path) -> str:
+    """A corrupt sidecar must read as stale, not kill the pch forever."""
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError):
+        return ""
+
+
+def discard_pch(build_dir: Path) -> None:
+    """Remove the pch sidecars so a stale .gch is never consumed.
+
+    Bumps the header only when a .gch was actually removed: TUs compiled
+    against it have incomplete depfiles, while a repeat failure with no
+    .gch must not force a full rebuild every build. A .gch that survives
+    an unlink failure would be consumed silently (wrong output, not a
+    slow build), so that raises.
+    """
+    header = build_dir / PCH_HEADER_NAME
+    gch = Path(f"{header}.gch")
+    had_gch = gch.is_file()
+    errors = []
+    for sidecar in (gch, Path(f"{gch}.sum")):
+        try:
+            sidecar.unlink(missing_ok=True)
+        except OSError as err:
+            if sidecar.is_file():
+                from esphome.core import EsphomeError
+
+                raise EsphomeError(
+                    f"Could not discard the stale precompiled header: {err}"
+                ) from err
+            errors.append(err)
+    for err in errors:
+        _LOGGER.warning("Could not discard the pch sidecars: %s", err)
+    if had_gch and header.is_file():
+        with suppress(OSError):
+            os.utime(header)
+
+
+def prepare_pch(
+    build_dir: Path, include_headers: tuple[str, ...], extra: Iterable[str]
+) -> None:
+    """Compile ``build_dir``'s .gch from compile_commands.json flags and
+    write its ccache .sum.
+
+    The .sum doubles as the freshness stamp and folds in the compile
+    command, so a flag-only change rebuilds the .gch; ``extra`` carries
+    backend identity (framework version, sdkconfig, ...). A failed
+    compile falls back to the plain header include.
+    """
+    from esphome.core import CORE
+
+    header = build_dir / PCH_HEADER_NAME
+    gch = Path(f"{header}.gch")
+    sum_path = Path(f"{gch}.sum")
+    cmd_and_dir = pch_compile_command(build_dir, header, gch)
+    if cmd_and_dir is None:
+        # Freshness cannot be validated; a leftover .gch must not be consumed
+        discard_pch(build_dir)
+        pch_degraded("no usable compile command")
+        return
+    cmd, cmd_dir = cmd_and_dir
+    # Strip like ccache's rewriting (user CCACHE_BASEDIR wins); the raw
+    # build path covers unresolved (symlinked) spellings
+    cmd_id = (
+        " ".join(cmd)
+        .replace(effective_ccache_basedir(), "")
+        .replace(str(CORE.build_path), "")
+    )
+    try:
+        checksum = pch_checksum(
+            CORE.relative_src_path(),
+            include_headers,
+            (
+                # The closure is sorted, so root order only enters via the text
+                pch_header_text(include_headers),
+                *extra,
+                cmd_id,
+            ),
+        )
+    except (OSError, UnicodeError) as err:
+        # Identity unknown: a stale cache entry must never be served
+        _LOGGER.warning(
+            "Could not establish the pch identity; compiling without it: %s", err
+        )
+        discard_pch(build_dir)
+        pch_degraded(f"identity unknown: {err}")
+        return
+    failed_marker = Path(f"{gch}.failed")
+
+    def _run(
+        run_cmd: list[str], what: str, stdin: str | None = None
+    ) -> subprocess.CompletedProcess | None:
+        """Spawn one pch tool step; environmental failures discard and
+        degrade (None): spawn/IO/timeout errors and signal kills never
+        latch the marker."""
+        try:
+            proc = subprocess.run(
+                run_cmd,
+                cwd=cmd_dir,
+                # C locale keeps diagnostics matchable by _TRANSIENT_ERRORS
+                env={**os.environ, "LC_ALL": "C"},
+                input=stdin,
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=300,
+            )
+        except (OSError, subprocess.SubprocessError) as err:
+            _LOGGER.warning("Precompiled header %s did not run: %s", what, err)
+            discard_pch(build_dir)
+            pch_degraded(f"{what} did not run: {err}")
+            return None
+        if proc.returncode < 0:
+            # Killed by a signal (OOM, ^C): environmental, do not latch
+            _LOGGER.warning(
+                "Precompiled header %s was killed (signal %d); retrying next build",
+                what,
+                -proc.returncode,
+            )
+            discard_pch(build_dir)
+            pch_degraded(f"{what} killed by signal {-proc.returncode}")
+            return None
+        return proc
+
+    def _fail(error: str, reason: str, latch: bool) -> None:
+        """Discard and degrade; deterministic failures latch when asked."""
+        _LOGGER.warning(
+            "Precompiled header failed; compiling without it: %s", error[:400]
+        )
+        # Latching paths keep the full compiler output recoverable
+        _LOGGER.debug("Full pch output: %s", error)
+        discard_pch(build_dir)
+        if latch and not any(m in error for m in _TRANSIENT_ERRORS):
+            # Skip retries until a header/flag/backend-identity/command change
+            failed_marker.write_text(checksum + "\n", encoding="utf-8")
+            os.utime(header)
+        pch_degraded(f"{reason}: {error[:200]}")
+
+    def _probe(latch: bool = True) -> None:
+        """Load-check the built .gch: some toolchains build one they then
+        refuse to load (per-process ASLR). Dep flags are already stripped
+        from cmd, so no -MF is needed; cmd ends with the fixed
+        "-x c++-header -c -o" tail. A cached-header rejection may not
+        reproduce (per-process), so that caller passes latch=False."""
+        if cmd[-6:-4] != ["-x", "c++-header"]:
+            # The slice below depends on pch_compile_command's fixed tail
+            _LOGGER.warning("Unexpected pch command shape: %s", cmd[-6:])
+            discard_pch(build_dir)
+            pch_degraded("unexpected pch command shape")
+            return
+        base = cmd[:-6]
+        probe = _run([*base, *pch_probe_args(str(header))], "probe", stdin="")
+        if probe is None:
+            return
+        if probe.returncode != 0:
+            # Disambiguate: only blame the pch when the same compile passes
+            # without it; a failing baseline is its own (latchable) problem
+            baseline = _run([*base, *pch_probe_tail()], "probe baseline", stdin="")
+            if baseline is None:
+                return
+            if baseline.returncode == 0:
+                error = probe.stderr.strip() or f"exit code {probe.returncode}"
+                _fail(error, "toolchain cannot load the pch", latch=latch)
+            else:
+                error = baseline.stderr.strip() or f"exit code {baseline.returncode}"
+                _fail(error, "probe cannot run at all", latch=latch)
+
+    if gch.is_file() and _read_stamp(sum_path) == checksum:
+        _log_pch_in_use()
+        if pch_strict():
+            # Rejection is per-process, so a cached .gch must re-prove
+            # loadability for the strict gate (CI-only cost); no latch,
+            # since the rejection may not reproduce either
+            _probe(latch=False)
+        return
+    if _read_stamp(failed_marker) == checksum:
+        _LOGGER.info(
+            "Precompiled header disabled after an earlier failure; delete %s to retry",
+            failed_marker,
+        )
+        pch_degraded("earlier failure latched")
+        return
+    _log_pch_in_use()
+    result = _run(cmd, "compile")
+    if result is None:
+        return
+    error = None
+    if result.returncode != 0:
+        error = result.stderr.strip() or f"exit code {result.returncode}"
+    elif not gch.is_file():
+        error = "compiler produced no .gch"
+    if error is not None:
+        _fail(error, "compile failed", latch=True)
+        return
+    _probe()
+    if not gch.is_file():
+        # The probe discarded a rejected or unrunnable .gch
+        return
+    failed_marker.unlink(missing_ok=True)
+    sum_path.write_text(checksum + "\n", encoding="utf-8")
+    # Consumers depend on the header (depfiles cannot see through a .gch);
+    # bump it so users of the previous .gch recompile
+    os.utime(header)

esphome/components/esp8266/__init__.py

@@ -6,6 +6,7 @@ import subprocess
 import time
 from typing import Any
 
+from esphome.build_helpers.pch import pch_extra_scripts
 import esphome.codegen as cg
 import esphome.config_validation as cv
 from esphome.const import (
@@ -34,7 +35,7 @@ from esphome.core import (
 )
 from esphome.core.config import BOARD_MAX_LENGTH
 from esphome.helpers import IS_MACOS, copy_file_if_changed
-from esphome.platformio.toolchain import copy_ccache_script
+from esphome.platformio.toolchain import copy_ccache_script, copy_pch_script
 from esphome.storage_json import StorageJSON
 from esphome.types import ConfigType
 
@@ -398,6 +399,7 @@ async def to_code(config: ConfigType) -> None:
         ]
         if not enable_scanf_float:
             extra_scripts.append("pre:remove_float_scanf.py")
+        extra_scripts.extend(pch_extra_scripts())
         extra_scripts.append("post:post_build.py")
         cg.add_platformio_option("extra_scripts", extra_scripts)
 
@@ -563,6 +565,7 @@ def copy_files() -> None:
             CORE.relative_build_path(f"{script}.py"),
         )
     copy_ccache_script()
+    copy_pch_script()
 
 
 # ESP logs stack trace decoder, based on https://github.com/me-no-dev/EspExceptionDecoder

esphome/components/host/__init__.py

@@ -1,3 +1,4 @@
+from esphome.build_helpers.pch import pch_enabled, pch_extra_scripts
 import esphome.codegen as cg
 import esphome.config_validation as cv
 from esphome.const import (
@@ -10,7 +11,7 @@ from esphome.const import (
     ThreadModel,
 )
 from esphome.core import CORE
-from esphome.platformio.toolchain import copy_ccache_script
+from esphome.platformio.toolchain import copy_ccache_script, copy_pch_script
 from esphome.types import ConfigType
 
 from .const import KEY_HOST
@@ -18,6 +19,9 @@ from .const import KEY_HOST
 # force import gpio to register pin schema
 from .gpio import host_pin_to_code  # noqa: F401
 
+# Guarded wrapper: build_src_flags reaches C/assembly edges too
+HOST_PCH_PREFIX = "esphome/core/pch_prefix.h"
+
 CODEOWNERS = ["@esphome/core", "@clydebarrow"]
 AUTO_LOAD = ["network", "preferences"]
 IS_TARGET_PLATFORM = True
@@ -55,9 +59,18 @@ async def to_code(config: ConfigType) -> None:
     cg.add_platformio_option("platform", "platformio/native")
     cg.add_platformio_option("lib_ldf_mode", "off")
     cg.add_platformio_option("lib_compat_mode", "strict")
-    cg.add_platformio_option("extra_scripts", ["pre:ccache.py"])
+    cg.add_platformio_option("extra_scripts", ["pre:ccache.py", *pch_extra_scripts()])
+    if pch_enabled():
+        # Curated prefix for the pch (the script folds it plus defines.h):
+        # host has no framework force-includes, and the per-TU cost is the
+        # STL closure behind the core headers. Measured -43% compile CPU.
+        # Gated so ESPHOME_PCH_ENABLE=0 restores the strict view. When the
+        # .gch fails to build or load, the force-include stays and every TU
+        # parses the closure as text: correct, but slower than no pch.
+        cg.add_platformio_option("build_src_flags", f"-include {HOST_PCH_PREFIX}")
 
 
 # Called by writer.py
 def copy_files() -> None:
     copy_ccache_script()
+    copy_pch_script()

esphome/components/libretiny/__init__.py

@@ -2,6 +2,7 @@ import json
 import logging
 from pathlib import Path
 
+from esphome.build_helpers.pch import pch_extra_scripts
 import esphome.codegen as cg
 import esphome.config_validation as cv
 from esphome.const import (
@@ -26,7 +27,7 @@ from esphome.const import (
 from esphome.core import CORE
 from esphome.core.config import BOARD_MAX_LENGTH
 from esphome.helpers import copy_file_if_changed
-from esphome.platformio.toolchain import copy_ccache_script
+from esphome.platformio.toolchain import copy_ccache_script, copy_pch_script
 from esphome.storage_json import StorageJSON
 
 from . import gpio  # noqa: F401
@@ -513,7 +514,7 @@ async def component_to_code(config):
         # it for project source files only. GCC uses the last -O flag.
         build_src_flags += " -Os"
     cg.add_platformio_option("build_src_flags", build_src_flags)
-    cg.add_platformio_option("extra_scripts", ["pre:ccache.py"])
+    cg.add_platformio_option("extra_scripts", ["pre:ccache.py", *pch_extra_scripts()])
     # IRAM_ATTR is a no-op on BK72xx (SDK masks FIQ+IRQ around flash ops).
     # On other families, patch_linker.py routes .sram.text into the right
     # RAM-executable output section and prints a post-link placement summary.
@@ -619,3 +620,4 @@ def copy_files() -> None:
         CORE.relative_build_path("patch_linker.py"),
     )
     copy_ccache_script()
+    copy_pch_script()

esphome/components/rp2/__init__.py

@@ -6,6 +6,7 @@ from string import ascii_letters, digits
 import subprocess
 from typing import Any
 
+from esphome.build_helpers.pch import pch_extra_scripts
 import esphome.codegen as cg
 import esphome.config_validation as cv
 from esphome.const import (
@@ -33,7 +34,7 @@ from esphome.core import (
 )
 from esphome.core.config import BOARD_MAX_LENGTH
 from esphome.helpers import copy_file_if_changed, read_file, write_file_if_changed
-from esphome.platformio.toolchain import copy_ccache_script
+from esphome.platformio.toolchain import copy_ccache_script, copy_pch_script
 from esphome.storage_json import StorageJSON
 from esphome.types import ConfigType
 
@@ -340,7 +341,10 @@ async def to_code(config: ConfigType) -> None:
     cg.add_define("ESPHOME_VARIANT", VARIANT_FRIENDLY[variant])
     cg.add_define(ThreadModel.SINGLE)
 
-    cg.add_platformio_option("extra_scripts", ["pre:ccache.py", "post:post_build.py"])
+    cg.add_platformio_option(
+        "extra_scripts",
+        ["pre:ccache.py", *pch_extra_scripts(), "post:post_build.py"],
+    )
 
     conf = config[CONF_FRAMEWORK]
     cg.add_platformio_option("framework", "arduino")
@@ -644,6 +648,7 @@ def copy_files() -> None:
         CORE.relative_build_path("inject_lwip_include.py"),
     )
     copy_ccache_script()
+    copy_pch_script()
     _generate_lwipopts_h()
     if generate_pio_files():
         path = CORE.relative_src_path("esphome.h")

esphome/core/pch_prefix.h

@@ -0,0 +1,8 @@
+#pragma once
+// Curated precompiled-header prefix for backends that force-include it via
+// build_src_flags (the pch script folds it into the .gch). Guarded because
+// build_src_flags also reaches C and assembly src edges.
+#ifdef __cplusplus
+#include "esphome/core/application.h"
+#include "esphome/core/automation.h"
+#endif

esphome/espidf/framework.py

@@ -16,6 +16,7 @@ from esphome.build_helpers.ccache import (
     parse_enable_env,
     resolve_ccache_path,
 )
+from esphome.build_helpers.pch import ccache_pch_env
 from esphome.build_helpers.tools_cache import IDF_TOOLS_CACHE, tools_cache_path
 from esphome.core import Version
 from esphome.framework_helpers import (
@@ -1205,15 +1206,33 @@ def _ccache_env() -> dict[str, str]:
 
     Only values the user has not already set in the environment are returned, so
     a custom ``CCACHE_DIR`` / ``CCACHE_MAXSIZE`` / etc. is respected.
+    The pch settings add ``time_macros`` sloppiness process-wide; the visible
+    effect is a cached TU can keep an older ``esp_app_desc`` build timestamp.
+    """
+    if not _ccache_enabled():
+        # The raw knob value (e.g. "disable") is still inherited by idf.py
+        # via os.environ, where a non-false-constant string reads as
+        # truthy; export the canonical off spelling instead
+        return {"IDF_CCACHE_ENABLE": "0"}
+
+    env = ccache_defaults_env(get_idf_tools_path() / "ccache")
+    env.update(ccache_pch_env())
+    # Exactly one canonical spelling ever reaches idf.py, whatever the
+    # accepted input spelling was ("enable", "yes", ...)
+    env["IDF_CCACHE_ENABLE"] = "1"
+    return env
+
+
+def _ccache_enabled() -> bool:
+    """Whether ESP-IDF compiles run under ccache.
+
+    IDF_CCACHE_ENABLE (the backend-native knob) wins over the shared
+    ESPHOME_CCACHE_ENABLE; when unset, enabled iff a runnable binary is
+    on PATH.
     """
-    # IDF_CCACHE_ENABLE (the backend-native knob) wins over the shared
-    # ESPHOME_CCACHE_ENABLE.
     idf_knob = parse_enable_env("IDF_CCACHE_ENABLE")
     if idf_knob is False:
-        # The raw value (e.g. "disable") is still inherited by idf.py via
-        # os.environ, where a non-false-constant string reads as truthy;
-        # export the canonical off spelling instead
-        return {"IDF_CCACHE_ENABLE": "0"}
+        return False
     if idf_knob is True:
         # Forced on ignores the runnability verdict, but the outcome is
         # worth saying out loud. Probed directly (not via the resolver,
@@ -1233,17 +1252,8 @@ def _ccache_env() -> dict[str, str]:
                 "IDF_CCACHE_ENABLE=1 forces on the ccache at %s even though "
                 "it failed to run; idf.py will use it anyway",
             )
-    elif resolve_ccache_path() is None:
-        # ESP-IDF silently skips ccache without the binary; export the
-        # canonical off spelling so an unparsable inherited value (or a
-        # probe-rejected ccache idf.py would still find) cannot enable it
-        return {"IDF_CCACHE_ENABLE": "0"}
-
-    env = ccache_defaults_env(get_idf_tools_path() / "ccache")
-    # Exactly one canonical spelling ever reaches idf.py, whatever the
-    # accepted input spelling was ("enable", "yes", ...)
-    env["IDF_CCACHE_ENABLE"] = "1"
-    return env
+        return True
+    return resolve_ccache_path() is not None
 
 
 def get_framework_env(

esphome/espidf/toolchain.py

@@ -528,6 +528,25 @@ def run_compile(config, verbose: bool) -> int:
             return result.returncode
         _patch_memory_segments()
 
+    # After every reconfigure so compile_commands and sdkconfig are settled.
+    # An optional speedup must never abort the build
+    from esphome.build_gen.espidf import discard_pch, prepare_pch
+
+    try:
+        prepare_pch()
+    except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
+        from esphome.build_helpers.pch import pch_strict
+
+        # Strict first: its own knob error must not mask the real failure
+        strict = pch_strict()
+        # Raises itself if a stale .gch survives (silently wrong output)
+        discard_pch()
+        if strict:
+            raise
+        _LOGGER.warning(
+            "Precompiled header setup failed; compiling without it", exc_info=True
+        )
+
     # Build
     args = []
 

esphome/platformio/pch.py.script

@@ -0,0 +1,416 @@
+import hashlib
+import os
+from pathlib import Path
+import posixpath
+import re
+import shlex
+import stat
+import subprocess
+import traceback
+
+# pylint: disable=E0602
+Import("env")  # noqa: F821
+_projenv_error = None
+try:
+    Import("projenv")  # noqa: F821
+except Exception as err:  # noqa: BLE001 -- not exported under -t nobuild
+    projenv = None
+    _projenv_error = err
+
+# Precompile the src force-includes plus defines.h and force-include the
+# result into C++ src compiles only; their preprocessed output is unchanged.
+# Registration is gated host-side (pch_enabled()). Keep the closure, ccache
+# values, probe flow, stamp flow, and env-knob spellings in sync with
+# build_helpers/pch.py.
+
+# Compiler failures that clear on their own must not latch the .failed marker
+_TRANSIENT_ERRORS = ("No space left", "Cannot allocate", "Resource temporarily")
+
+# Keep in sync with helpers.TRUTHY_ENV_STRINGS / FALSY_ENV_STRINGS
+_TRUTHY = ("1", "true", "yes", "on", "enable")
+_FALSY = ("", "0", "false", "no", "off", "disable")
+_STRICT_RAW = os.environ.get("ESPHOME_PCH_STRICT")
+_STRICT_VALUE = (_STRICT_RAW or "").strip().lower()
+_STRICT = _STRICT_VALUE in _TRUTHY
+if _STRICT_RAW is not None and _STRICT_VALUE not in _TRUTHY + _FALSY:
+    # A typo must not silently turn the gate into a no-op
+    raise RuntimeError(f"Unrecognized ESPHOME_PCH_STRICT={_STRICT_RAW!r}; use 1 or 0")
+
+_INCLUDE_RE = re.compile(rb'^\s*#\s*include\s+["<]([^">]+)[">]', re.MULTILINE)
+_CORE_HEADER = "esphome/core/defines.h"
+
+
+def _raise_walk_error(err: OSError) -> None:
+    raise err
+
+
+def _resolves_dir(path: Path) -> bool:
+    """False when missing; other stat failures propagate."""
+    try:
+        return stat.S_ISDIR(path.stat().st_mode)
+    except (FileNotFoundError, NotADirectoryError):
+        return False
+
+
+def _resolves(path: Path) -> bool:
+    """False when missing; other stat failures propagate (identity unknown)."""
+    try:
+        return stat.S_ISREG(path.stat().st_mode)
+    except (FileNotFoundError, NotADirectoryError):
+        return False
+
+
+def _include_closure(src_dir: Path, roots: list) -> dict:
+    """Quoted-include closure: src-relative name -> contents (mirror of
+    build_helpers/pch.py)."""
+    seen = {}
+    stack = [(name, "") for name in roots]
+    while stack:
+        name, from_dir = stack.pop()
+        for candidate in (f"{from_dir}/{name}" if from_dir else name, name):
+            rel = posixpath.normpath(candidate)
+            if not rel.startswith("..") and _resolves(src_dir / rel):
+                break
+        else:
+            continue
+        if rel in seen:
+            continue
+        try:
+            data = (src_dir / rel).read_bytes()
+        except OSError as err:
+            # A marker would truncate the transitive walk; fail closed
+            print(f"ESPHome: could not read {rel} for the pch checksum: {err}")
+            raise
+        seen[rel] = data
+        parent = posixpath.dirname(rel)
+        stack.extend(
+            (inc.decode(errors="surrogateescape"), parent)
+            for inc in _INCLUDE_RE.findall(data)
+        )
+    return seen
+
+
+def _shell_arg(element) -> str | None:
+    """One compiler argv from one SCons element, matching the real spawn:
+    spaced elements pass whole, the rest get one shell unquote (skipped on
+    Windows, where shlex would eat path backslashes)."""
+    arg = str(element)
+    if " " in arg or os.name == "nt":
+        return arg.replace('\\"', '"')
+    if not arg.strip():
+        return arg
+    try:
+        tokens = shlex.split(arg)
+    except ValueError as err:
+        print(f"ESPHome: could not lex flag {arg!r} for the pch: {err}")
+        return None
+    if len(tokens) != 1:
+        # A flag the model cannot reproduce would diverge the .gch's flags
+        print(f"ESPHome: cannot model flag {arg!r} for the pch")
+        return None
+    return tokens[0]
+
+
+def _compile_gch(cxx, flags, header: Path, gch: Path, proj_dir: Path):
+    """Compile the .gch, then probe that the toolchain can load it back
+    (GCC 10 on macOS arm64 rejects its own per-process). Returns an error
+    string or None; OSError propagates as transient."""
+    result = subprocess.run(  # noqa: PLW1510
+        [cxx, "-x", "c++-header", *flags, "-c", str(header), "-o", str(gch)],
+        cwd=proj_dir,
+        # C locale keeps diagnostics matchable by _TRANSIENT_ERRORS
+        env={**os.environ, "LC_ALL": "C"},
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode < 0:
+        # Signal-killed (OOM, ^C): route to the transient no-marker path
+        raise OSError(f"compiler killed by signal {-result.returncode}")
+    if result.returncode != 0:
+        return result.stderr
+    return _probe_gch(cxx, flags, header, proj_dir)
+
+
+def _probe_run(cxx, flags, extra, proj_dir: Path):
+    probe = subprocess.run(  # noqa: PLW1510
+        [cxx, *flags, *extra, "-fsyntax-only", "-x", "c++", "-"],
+        cwd=proj_dir,
+        env={**os.environ, "LC_ALL": "C"},
+        input="",
+        capture_output=True,
+        text=True,
+    )
+    if probe.returncode < 0:
+        raise OSError(f"probe killed by signal {-probe.returncode}")
+    return probe
+
+
+def _probe_gch(cxx, flags, header: Path, proj_dir: Path):
+    """Load-check an existing .gch; error string or None. Rejection must
+    be a nonzero exit (keep in sync with pch_probe_args); a baseline run
+    without the pch keeps environmental failures from being blamed on it."""
+    # -MF is only legal alongside a dependency flag; pass it solely to
+    # redirect a depfile that -MD/-MMD in the flags would otherwise write
+    dep_redirect = (
+        ["-MF", os.devnull]
+        if any(f in ("-MD", "-MMD", "-M", "-MM") for f in flags)
+        else []
+    )
+    probe = _probe_run(
+        cxx,
+        flags,
+        [*dep_redirect, "-Winvalid-pch", "-Werror=invalid-pch", "-include", str(header)],
+        proj_dir,
+    )
+    if probe.returncode == 0:
+        return None
+    baseline = _probe_run(cxx, flags, dep_redirect, proj_dir)
+    if baseline.returncode != 0:
+        # Deterministic and latchable; the transient filter at the caller
+        # keeps resource exhaustion from latching
+        return f"probe cannot run at all: {baseline.stderr.strip()[:200]}"
+    return f"toolchain cannot load the pch: {probe.stderr.strip()}"
+
+
+def _read_stamp(path: Path) -> str:
+    """A corrupt sidecar must read as stale, not kill the pch forever."""
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError):
+        return ""
+
+
+def _setup_pch() -> bool | None:
+    if projenv is None:
+        print(f"ESPHome: projenv unavailable ({_projenv_error}); skipping pch")
+        try:
+            from SCons.Script import COMMAND_LINE_TARGETS
+        except ImportError:
+            # No SCons is an anomaly under PlatformIO: the unknown state
+            # must not read as success (strict decides fatality at the gate)
+            return False
+        # Expected under -t nobuild (nothing compiles); a missing
+        # projenv on a real compile must not pass strict
+        return "nobuild" in [str(t) for t in COMMAND_LINE_TARGETS]
+    # Project root: SCons compiles run here, so the relative -include
+    # resolves; an absolute path would break cross-device ccache sharing.
+    proj_dir = Path(env.subst("$PROJECT_DIR"))  # noqa: F821
+    src_dir = Path(env.subst("$PROJECT_SRC_DIR"))  # noqa: F821
+    header = proj_dir / "esphome_pch.h"
+    gch = Path(f"{header}.gch")
+    sum_path = Path(f"{gch}.sum")
+
+    cxx = projenv.subst("$CXX")  # noqa: F821
+    # The header holds the -include entries itself, so the .gch compile must
+    # not see them; consumers keep theirs, which the .gch then satisfies.
+    flags = []
+    include_headers = []
+    raw_args = [
+        _shell_arg(element)
+        for element in projenv.subst_list("$CXXFLAGS $CCFLAGS $_CCCOMCOM")[0]  # noqa: F821
+    ]
+    if any(arg is None for arg in raw_args):
+        print("ESPHome: skipping precompiled header: unmodelable flag")
+        return
+    flag_it = iter(raw_args)
+    for tok in flag_it:
+        if tok == "-include":
+            include_headers.append(next(flag_it, ""))
+        elif tok.startswith("-include") and not tok.startswith("-include-"):
+            include_headers.append(tok[len("-include") :])
+        else:
+            flags.append(tok)
+    if any(not name for name in include_headers):
+        print("ESPHome: build_src_flags has a trailing -include; skipping pch")
+        return
+    # Fold only relative names resolving under src/: consumers keep their
+    # own -include entries, so folding an unguarded user header would
+    # include it twice; unfolded ones stay consumer-only.
+    try:
+        folded = [
+            name
+            for name in include_headers
+            if not Path(name).is_absolute() and _resolves(src_dir / name)
+        ]
+    except OSError as err:
+        print(f"ESPHome: skipping precompiled header: {err}")
+        return
+    if unfolded := [n for n in include_headers if n not in folded]:
+        print(f"ESPHome: not precompiling non-src force-includes: {unfolded}")
+    content = "".join(f'#include "{name}"\n' for name in (*folded, _CORE_HEADER))
+
+    digest = hashlib.sha256()
+    digest.update(content.encode(errors="surrogateescape"))
+    digest.update(cxx.encode(errors="surrogateescape"))
+    # Mirror CCACHE_BASEDIR: strip the per-device build path so identical
+    # configs produce identical .sum files and share cache entries
+    flags_id = " ".join(flags)
+    if basedir := os.environ.get("CCACHE_BASEDIR"):
+        flags_id = flags_id.replace(basedir, "")
+    digest.update(flags_id.encode(errors="surrogateescape"))
+    # GCC never validates a .gch against its source headers, and PlatformIO
+    # package paths carry no version, so a package bump must invalidate here
+    platform = env.PioPlatform()  # noqa: F821
+    for package in sorted(platform.packages):
+        try:
+            version = platform.get_package_version(package)
+        except KeyError:
+            # An unresolved manifest must not hash as a constant
+            if platform.get_package(package) is not None:
+                print(f"ESPHome: skipping precompiled header: no version for {package}")
+                return
+            version = None  # absent optional package
+        except Exception as err:  # noqa: BLE001
+            # No trustworthy package identity: a stale .gch could survive
+            print(f"ESPHome: skipping precompiled header: {err}")
+            return
+        digest.update(f"{package}={version}".encode())
+        digest.update(b"\0")
+    try:
+        closure = _include_closure(src_dir, [*folded, _CORE_HEADER])
+    except OSError as err:
+        print(f"ESPHome: skipping precompiled header: {err}")
+        return
+    for rel in sorted(closure):
+        digest.update(rel.encode(errors="surrogateescape"))
+        digest.update(closure[rel])
+        digest.update(b"\0")
+    # Project-local -I dirs (e.g. rp2's lwip_override) hold generated
+    # headers the src closure cannot see; hash them too
+    prev = ""
+    try:
+        for tok in flags:
+            inc = tok[2:] if tok.startswith("-I") and len(tok) > 2 else ""
+            if prev == "-I":
+                inc = tok
+            prev = tok
+            if not inc:
+                continue
+            inc_dir = Path(inc)
+            if not (
+                _resolves_dir(inc_dir)
+                and inc_dir.is_relative_to(proj_dir)
+                and not inc_dir.is_relative_to(src_dir)
+                # Library trees never enter the prefix closure; walking them
+                # would read every library file each build
+                and not inc_dir.is_relative_to(proj_dir / ".piolibdeps")
+                and not inc_dir.is_relative_to(proj_dir / ".pioenvs")
+            ):
+                continue
+            local_headers = []
+            # os.walk with onerror: rglob would swallow unlistable subtrees
+            for root, _dirs, files in os.walk(inc_dir, onerror=_raise_walk_error):
+                local_headers.extend(
+                    Path(root) / f
+                    for f in files
+                    if f.endswith((".h", ".hpp", ".hh", ".inc"))
+                )
+            for local in sorted(local_headers):
+                digest.update(str(local.relative_to(proj_dir)).encode())
+                digest.update(local.read_bytes())
+                digest.update(b"\0")
+    except OSError as err:
+        print(f"ESPHome: skipping precompiled header: {err}")
+        return
+    checksum = digest.hexdigest()
+
+    # The ccache .sum sidecar doubles as the freshness stamp
+    fresh = (
+        header.is_file()
+        and gch.is_file()
+        and sum_path.is_file()
+        and (_read_stamp(sum_path) == checksum)
+    )
+    if fresh and _STRICT:
+        # Rejection is per-process: strict re-proves a cached .gch loads
+        # (mirrors the pch_strict() re-probe in build_helpers/pch.py)
+        error = _probe_gch(cxx, flags, header, proj_dir)
+        if error is not None:
+            print(f"ESPHome: {error}")
+            gch.unlink(missing_ok=True)
+            sum_path.unlink(missing_ok=True)
+            return
+    if not fresh:
+        failed_marker = Path(f"{gch}.failed")
+        if _read_stamp(failed_marker) == checksum:
+            print(
+                "ESPHome: skipping precompiled header (previous attempt "
+                f"failed); delete {failed_marker.name} to retry"
+            )
+            return
+        header.write_text(content, encoding="utf-8")
+        try:
+            error = _compile_gch(cxx, flags, header, gch, proj_dir)
+        except OSError as err:
+            # Transient spawn/IO failure: no marker, retry next build
+            print(f"ESPHome: precompiled header compile did not run: {err}")
+            gch.unlink(missing_ok=True)
+            sum_path.unlink(missing_ok=True)
+            return
+        if error is not None:
+            print("ESPHome: precompiled header failed; compiling without it")
+            print(error)
+            gch.unlink(missing_ok=True)
+            sum_path.unlink(missing_ok=True)
+            if any(m in error for m in _TRANSIENT_ERRORS):
+                # Resource exhaustion clears on its own; retry next build
+                return
+            # Skip retries until a flag/header/platform change alters the checksum
+            failed_marker.write_text(checksum + "\n", encoding="utf-8")
+            return
+        failed_marker.unlink(missing_ok=True)
+        sum_path.write_text(checksum + "\n", encoding="utf-8")
+
+    # Computed first so the flags and env land together: a raise between
+    # them would leave a pch-consuming build without its ccache settings.
+    # projenv["ENV"] aliases os.environ, so these reach all TUs; only
+    # time_macros affects non-pch TUs. User values win.
+    ccache_updates = {
+        key: value
+        for key, value in (
+            ("CCACHE_SLOPPINESS", "pch_defines,time_macros"),
+            ("CCACHE_PCH_EXTSUM", "true"),
+        )
+        if key not in os.environ
+    }
+    sloppiness = os.environ.get("CCACHE_SLOPPINESS")
+    if sloppiness is not None:
+        tokens = {tok.strip() for tok in sloppiness.split(",")}
+        missing = [t for t in ("pch_defines", "time_macros") if t not in tokens]
+        if missing:
+            # Without these ccache declines every pch-consuming compile
+            ccache_updates["CCACHE_SLOPPINESS"] = ",".join((sloppiness, *missing))
+            print(f"ESPHome: adding {','.join(missing)} to CCACHE_SLOPPINESS for the pch")
+    extsum = os.environ.get("CCACHE_PCH_EXTSUM")
+    if extsum is not None and extsum.strip().lower() not in ("1", "true", "yes", "on"):
+        # ccache then hashes the non-reproducible .gch bytes: permanent misses
+        print(f"ESPHome: CCACHE_PCH_EXTSUM={extsum} disables pch caching")
+    # Prepended: GCC only uses a .gch while no other tokens precede it.
+    # The relative name also reaches "pio run -t idedata" output.
+    # -Wno-error: the per-process probe can pass while a later cc1plus
+    # rejects the .gch; that must stay a warning under user -Werror.
+    projenv.Prepend(  # noqa: F821
+        CXXFLAGS=[
+            "-Winvalid-pch",
+            # Strict inverts: a per-process consumer rejection reds the build
+            "-Werror=invalid-pch" if _STRICT else "-Wno-error=invalid-pch",
+            "-include",
+            header.name,
+        ]
+    )
+    projenv["ENV"].update(ccache_updates)  # noqa: F821
+    print("ESPHome: Compiling with precompiled header")
+    return True
+
+
+
+try:
+    _used = _setup_pch()
+except Exception:  # noqa: BLE001 -- a speedup must never break the build
+    if _STRICT:
+        raise
+    print("ESPHome: pch internal error; compiling without it")
+    traceback.print_exc()
+else:
+    if _STRICT and not _used:
+        raise RuntimeError("ESPHOME_PCH_STRICT: precompiled header was not used")

esphome/platformio/toolchain.py

@@ -289,6 +289,15 @@ def copy_ccache_script() -> None:
     )
 
 
+def copy_pch_script() -> None:
+    """Copy the shared precompiled-header SCons post-script into the build
+    dir; platform components pair it with ``post:pch.py`` in extra_scripts."""
+    copy_file_if_changed(
+        Path(__file__).parent / "pch.py.script",
+        CORE.relative_build_path("pch.py"),
+    )
+
+
 def default_libdeps_dir() -> str:
     """The PLATFORMIO_LIBDEPS_DIR value a pio run defaults to; the package
     prefetch must resolve installed libraries against the same dir."""

esphome/writer.py

@@ -7,6 +7,7 @@ import re
 import time
 
 from esphome import loader
+from esphome.build_helpers.pch import PCH_ARTIFACT_NAMES
 from esphome.compiled_config import save_compiled_config
 from esphome.config import iter_component_configs, iter_components
 from esphome.const import (
@@ -246,6 +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
     }
     include_l = []
     for target, _ in source_files_l:
@@ -609,6 +611,10 @@ def clean_build(clear_pio_cache: bool = True, *, full: bool = False):
             if idf_path.is_dir():
                 _LOGGER.info("Deleting %s", idf_path)
                 rmtree(idf_path)
+        # The PlatformIO pch artifacts live at the project root so the
+        # relative -include resolves; a partial clean must drop them too
+        for name in PCH_ARTIFACT_NAMES:
+            CORE.relative_build_path(name).unlink(missing_ok=True)
 
     # The idedata caches are derived from the build but live under the data
     # dir, not the build path, so they must be removed separately in both

tests/unit_tests/build_gen/test_arduino8266.py

@@ -364,7 +364,118 @@ def test_write_project_link_line_and_exclusions(tmp_path: Path) -> None:
         line for line in content.splitlines() if line.startswith("  flags = ")
     ]
     assert flags_lines
-    assert all(line == "  flags = $srcflags" for line in flags_lines)
+    # C++ src edges consume the precompiled header; C/assembly keep srcflags
+    assert set(flags_lines) == {"  flags = $srcflags", "  flags = $srccxxflags"}
+
+
+def test_write_project_pch(tmp_path: Path) -> None:
+    paths = _make_framework(tmp_path)
+    _set_flags("-DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH")
+    content = _write_ninja(paths, ccache="/usr/bin/ccache")
+    build_dir = CORE.relative_pioenvs_path(CORE.name)
+    assert "rule pch" in content
+    assert "build esphome_pch.h.gch: pch" in content
+    for line in content.splitlines():
+        # C++ edges wait on the .gch; the C edge must not reference it
+        if line.startswith("build obj/src/main.cpp.o:"):
+            assert line.endswith("| esphome_pch.h.gch")
+        if line.startswith("build obj/src/esphome/vendor.c.o:"):
+            assert "esphome_pch" not in line
+    assert (build_dir / "esphome_pch.h").read_text().splitlines() == [
+        '#include "esphome/components/esp8266/throw_stubs.h"',
+        '#include "esphome/core/defines.h"',
+    ]
+    assert (build_dir / "esphome_pch.h.gch.sum").read_text().strip()
+    # Emission recorded so the framework env exports the ccache settings
+    from esphome.build_helpers.pch import ccache_pch_env
+
+    assert "CCACHE_PCH_EXTSUM" in ccache_pch_env()
+
+
+def test_write_project_pch_sum_only_with_ccache(tmp_path: Path) -> None:
+    """The .sum sidecar exists solely for ccache; skip it when disabled."""
+    paths = _make_framework(tmp_path)
+    _set_flags("-DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH")
+    content = _write_ninja(paths)
+    build_dir = CORE.relative_pioenvs_path(CORE.name)
+    assert "build esphome_pch.h.gch: pch" in content
+    assert not (build_dir / "esphome_pch.h.gch.sum").exists()
+
+
+def test_write_project_pch_identity_unknown_skips_pch(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """An OSError from the checksum means the .sum cannot vouch for the
+    .gch: the build must fall back to plain srcflags."""
+    paths = _make_framework(tmp_path)
+    _set_flags("-DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH")
+    with patch(
+        "esphome.build_gen.arduino8266.pch_checksum",
+        side_effect=OSError("stat failed"),
+    ):
+        content = _write_ninja(paths, ccache="/usr/bin/ccache")
+    assert "esphome_pch" not in content
+    assert "srccxxflags" not in content
+    assert "  flags = $srcflags" in content
+    assert "Could not establish the pch identity" in caplog.text
+
+
+def test_write_project_pch_folds_joined_src_force_include(
+    tmp_path: Path,
+) -> None:
+    """-includefoo.h in build_src_flags must fold into the pch like the
+    separated spelling, not precede and defeat it."""
+    paths = _make_framework(tmp_path)
+    _set_flags("-DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH")
+    CORE.platformio_options["build_src_flags"] = "-includeesphome/core/defines.h"
+    content = _write_ninja(paths, ccache="/usr/bin/ccache")
+    assert "build esphome_pch.h.gch: pch" in content
+    assert "srccxxflags" in content
+    assert "-includeesphome" not in content
+
+
+def test_write_project_pch_skipped_for_joined_force_include_spelling(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """GCC also accepts -includefoo.h as one token; the guard must see it."""
+    paths = _make_framework(tmp_path)
+    _set_flags(
+        "-DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH", "-includefoo.h"
+    )
+    content = _write_ninja(paths, ccache="/usr/bin/ccache")
+    assert "esphome_pch" not in content
+    assert "prevents the precompiled header" in caplog.text
+
+
+def test_write_project_pch_skipped_when_user_force_include_precedes(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A -include in build_flags lands ahead of the pch include, so GCC
+    would never load the .gch; skip it and say so."""
+    paths = _make_framework(tmp_path)
+    _set_flags(
+        "-DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH", "-include foo.h"
+    )
+    content = _write_ninja(paths, ccache="/usr/bin/ccache")
+    assert "esphome_pch" not in content
+    assert "srccxxflags" not in content
+    assert "prevents the precompiled header" in caplog.text
+    # No pch emitted: the ccache relaxation must stay off
+    from esphome.build_helpers.pch import ccache_pch_env
+
+    assert ccache_pch_env() == {}
+
+
+def test_write_project_pch_disabled(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+    paths = _make_framework(tmp_path)
+    _set_flags("-DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH")
+    content = _write_ninja(paths)
+    assert "esphome_pch" not in content
+    assert "srccxxflags" not in content
+    assert "  flags = $srcflags" in content
 
 
 def test_write_project_scanf_float_and_waveform_kept(tmp_path: Path) -> None:
@@ -1711,3 +1822,73 @@ def test_write_project_rejects_spaced_ldscript_override(tmp_path: Path) -> None:
     _set_flags()
     with pytest.raises(EsphomeError, match="Invalid flash linker script name"):
         arduino8266.write_project(paths, None)
+
+
+def test_write_project_pch_no_device_path_poison(tmp_path: Path) -> None:
+    """Regression: the -include stays relative and the .sum carries no
+    per-device path, or cross-device ccache sharing breaks."""
+    paths = _make_framework(tmp_path / "shared")
+    sums = []
+    for name in ("dev_a", "dev_b"):
+        CORE.name = name
+        CORE.build_path = tmp_path / name
+        _set_flags("-DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH")
+        content = _write_ninja(paths, ccache="/usr/bin/ccache")
+        assert (
+            "srccxxflags = -Winvalid-pch -Wno-error=invalid-pch "
+            "-include esphome_pch.h" in content
+        )
+        sums.append(
+            (CORE.relative_pioenvs_path(name) / "esphome_pch.h.gch.sum").read_text()
+        )
+    assert sums[0] == sums[1]
+
+
+def test_write_project_pch_strict_raises_on_skip(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from esphome.core import EsphomeError
+
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    paths = _make_framework(tmp_path)
+    _set_flags(
+        "-DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH", "-include foo.h"
+    )
+    with pytest.raises(EsphomeError, match="precedes the pch"):
+        _write_ninja(paths, ccache="/usr/bin/ccache")
+
+
+def test_write_project_pch_strict_emits_probe_edge(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Strict mode gates C++ src edges on a hard-failing load probe."""
+    paths = _make_framework(tmp_path)
+    _set_flags("-DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH")
+    content = _write_ninja(paths, ccache="/usr/bin/ccache")
+    assert "pchprobe" not in content
+
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    content = _write_ninja(paths, ccache="/usr/bin/ccache")
+    assert "build esphome_pch.probe: pchprobe esphome_pch.h.gch" in content
+    assert "-Werror=invalid-pch" in content
+    # $out only expands in rule text; an edge-level binding would emit a
+    # bare stamp command and fail every strict build
+    assert "&& $python $buildtool touch $out" in content
+    assert "$stamp" not in content
+    # Strict consumers escalate: a per-TU rejection must red the build
+    assert "srccxxflags = -Winvalid-pch -Werror=invalid-pch" in content
+    assert "-Wno-error=invalid-pch" not in content
+
+    # With extra src flags the probe edge carries them like the .gch edge
+    CORE.platformio_options["build_src_flags"] = (
+        "-include esphome/components/esp8266/throw_stubs.h -DSRC_EXTRA"
+    )
+    content = _write_ninja(paths, ccache="/usr/bin/ccache")
+    assert "pchprobe esphome_pch.h.gch\n  flags = " in content
+    edges = [
+        line
+        for line in content.splitlines()
+        if line.startswith("build obj/src/") and ".cpp.o:" in line
+    ]
+    assert edges
+    assert all(line.endswith("| esphome_pch.h.gch esphome_pch.probe") for line in edges)

tests/unit_tests/build_gen/test_build_tool.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 from pathlib import Path
 import subprocess
 import sys
@@ -244,3 +245,20 @@ def test_copy_failure_leaves_no_partial_output(tmp_path: Path) -> None:
     ):
         assert build_tool.main() == 1
     assert not dst.exists()
+
+
+def test_touch_creates_and_updates_stamp(tmp_path: Path) -> None:
+    stamp = tmp_path / "esphome_pch.probe"
+    assert build_tool._run_touch(str(stamp)) == 0
+    assert stamp.is_file()
+    os.utime(stamp, (1, 1))
+    assert build_tool._run_touch(str(stamp)) == 0
+    assert stamp.stat().st_mtime > 1
+
+
+def test_touch_reports_failure(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    missing_dir = tmp_path / "gone" / "stamp"
+    assert build_tool._run_touch(str(missing_dir)) == 1
+    assert "touch:" in capsys.readouterr().err

tests/unit_tests/build_gen/test_espidf.py

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import json
 import logging
+import os
 from pathlib import Path
+import subprocess
 from unittest.mock import patch
 
 import pytest
@@ -488,3 +490,922 @@ def test_get_component_cmakelists_no_compile_features() -> None:
         content = get_component_cmakelists()
 
     assert "target_compile_features" not in content
+
+
+@pytest.fixture(autouse=True)
+def _pch_default_on(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Pin the knob so a developer's ESPHOME_PCH_ENABLE=0 cannot fail these."""
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "1")
+
+
+def _make_pch_device(tmp_path: Path, name: str) -> Path:
+    """A device dir with the pch source headers and a stub compile_commands."""
+    from esphome.build_helpers.pch import PCH_DEFAULT_HEADERS
+
+    dev = tmp_path / name
+    for header in PCH_DEFAULT_HEADERS:
+        path = dev / "src" / header
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("")
+    # A real quoted include chain and a per-device-named sdkconfig with
+    # identical content: the closure and sdkconfig inputs must be exercised
+    (dev / "src" / "esphome" / "core" / "defines.h").write_text(
+        '#include "esphome/core/macros.h"\n'
+    )
+    (dev / "src" / "esphome" / "core" / "macros.h").write_text("#define M 1\n")
+    # Both spellings: tests patch CORE.name to "test" or to the device name
+    (dev / f"sdkconfig.{name}").write_text("CONFIG_X=y\n")
+    (dev / "sdkconfig.test").write_text("CONFIG_X=y\n")
+    build = dev / "build"
+    build.mkdir(exist_ok=True)
+    from esphome.build_helpers.pch import pch_header_text
+
+    (build / "esphome_pch.h").write_text(pch_header_text(PCH_DEFAULT_HEADERS))
+    # Native separators: mixed f-string paths break the src-prefix match
+    # on Windows
+    src_file = str(dev / "src" / "a.cpp")
+    (build / "compile_commands.json").write_text(
+        json.dumps(
+            [
+                {
+                    "directory": str(build),
+                    "command": (
+                        "g++ -DX=1 -include esphome_pch.h "
+                        "-o esp-idf/src/CMakeFiles/__idf_src.dir/a.cpp.obj "
+                        f'-c "{src_file}"'
+                    ),
+                    "file": src_file,
+                }
+            ]
+        )
+    )
+    return dev
+
+
+def test_prepare_pch_writes_header_and_sum(tmp_path: Path) -> None:
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_a")
+    CORE.build_path = dev
+    gch = dev / "build" / "esphome_pch.h.gch"
+
+    def fake_compile(cmd, **kwargs):
+        if "-fsyntax-only" in cmd:
+            # The load probe follows a successful .gch build
+            return subprocess.CompletedProcess(cmd, 0, "", "")
+        # The compile must target the header, not the stub TU
+        assert cmd[-5:-3] == ["c++-header", "-c"]
+        gch.write_bytes(b"gch")
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=fake_compile),
+    ):
+        prepare_pch()
+    checksum = (dev / "build" / "esphome_pch.h.gch.sum").read_text().strip()
+    assert len(checksum) == 64
+    # Unchanged inputs: the second call must not recompile
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=AssertionError),
+    ):
+        prepare_pch()
+
+
+def test_pch_no_device_path_poison(tmp_path: Path) -> None:
+    """Regression: neither the injected -include nor the .sum may carry the
+    per-device build path, or cross-device ccache sharing breaks."""
+    from esphome.build_gen.espidf import get_component_cmakelists, prepare_pch
+
+    sums = []
+    for name in ("dev_a", "dev_b"):
+        dev = _make_pch_device(tmp_path, name)
+        CORE.build_path = dev
+        gch = dev / "build" / "esphome_pch.h.gch"
+
+        def fake_compile(cmd, _gch=gch, **kwargs):
+            _gch.write_bytes(b"gch")
+            return subprocess.CompletedProcess(cmd, 0, "", "")
+
+        with (
+            patch.object(CORE, "name", name),
+            patch("esphome.build_helpers.pch.subprocess.run", side_effect=fake_compile),
+        ):
+            prepare_pch()
+            content = get_component_cmakelists()
+        assert str(dev) not in content
+        sums.append((dev / "build" / "esphome_pch.h.gch.sum").read_text())
+    assert sums[0] == sums[1]
+
+
+def test_component_cmakelists_pch_block(monkeypatch: pytest.MonkeyPatch) -> None:
+    from esphome.build_gen.espidf import get_component_cmakelists
+
+    content = get_component_cmakelists()
+    assert '"$<$<COMPILE_LANGUAGE:CXX>:-include>"' in content
+    assert "-Wno-error=invalid-pch" in content
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    strict_content = get_component_cmakelists()
+    assert "-Werror=invalid-pch" in strict_content
+    monkeypatch.delenv("ESPHOME_PCH_STRICT")
+    assert '"$<$<COMPILE_LANGUAGE:CXX>:esphome_pch.h>"' in content
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+    assert "-include" not in get_component_cmakelists()
+
+
+def test_pch_compile_command_variants(tmp_path: Path) -> None:
+    """Missing DB, no matching entry, and launcher-prefixed commands."""
+    from esphome.build_helpers.pch import pch_compile_command
+
+    build = tmp_path / "build"
+    build.mkdir()
+    header = build / "esphome_pch.h"
+    gch = build / "esphome_pch.h.gch"
+    assert pch_compile_command(build, header, gch) is None
+
+    (build / "compile_commands.json").write_text(
+        json.dumps(
+            [
+                {"command": "gcc -c other.c", "file": "other.c"},
+            ]
+        )
+    )
+    assert pch_compile_command(build, header, gch) is None
+
+    src_file = str(tmp_path / "src" / "esphome" / "a.cpp")
+    (build / "compile_commands.json").write_text(
+        json.dumps(
+            [
+                {
+                    "command": (
+                        "/usr/bin/ccache g++ -DX=1 -include esphome_pch.h -MMD "
+                        "-MT a.cpp.obj -MF a.cpp.obj.d "
+                        "-o esp-idf/src/CMakeFiles/__idf_src.dir/a.cpp.obj "
+                        f"-c {src_file}"
+                    ),
+                    "file": src_file,
+                },
+            ]
+        )
+    )
+    # Launcher stripped; -include/-o/-c and depfile flags removed
+    cmd, cmd_dir = pch_compile_command(build, header, gch)
+    assert cmd == [
+        "g++",
+        "-DX=1",
+        "-x",
+        "c++-header",
+        "-c",
+        str(header),
+        "-o",
+        str(gch),
+    ]
+    # The compile must run where the flags were resolved
+    assert cmd_dir == build
+
+
+@pytest.mark.skipif(os.name == "nt", reason="symlinks need privileges on Windows")
+def test_pch_compile_command_matches_src_through_symlink(tmp_path: Path) -> None:
+    """Find the src TU when CMake spells paths through a different symlink (macOS /tmp)."""
+    from esphome.build_helpers.pch import pch_compile_command
+
+    real = tmp_path / "real"
+    (real / "src" / "esphome").mkdir(parents=True)
+    link = tmp_path / "link"
+    link.symlink_to(real, target_is_directory=True)
+    CORE.build_path = str(real)
+    build = real / "build"
+    build.mkdir()
+    header = build / "esphome_pch.h"
+    gch = build / "esphome_pch.h.gch"
+    src_file = str(link / "src" / "esphome" / "a.cpp")
+    (build / "compile_commands.json").write_text(
+        json.dumps([{"command": f"g++ -DX=1 -o a.obj -c {src_file}", "file": src_file}])
+    )
+
+    cmd, cmd_dir = pch_compile_command(build, header, gch)
+
+    assert cmd[:2] == ["g++", "-DX=1"]
+    assert cmd_dir == build
+
+
+def test_pch_compile_command_rejects_unusable_entries(tmp_path: Path) -> None:
+    """Malformed DB shapes and command-less entries skip cleanly instead of
+    producing a compiler-less argv retried every build."""
+    from esphome.build_helpers.pch import pch_compile_command
+
+    build = tmp_path / "build"
+    build.mkdir()
+    header = build / "esphome_pch.h"
+    gch = build / "esphome_pch.h.gch"
+    db = build / "compile_commands.json"
+    src_file = str(tmp_path / "src" / "esphome" / "a.cpp")
+
+    db.write_text(json.dumps({"not": "a list"}))
+    assert pch_compile_command(build, header, gch) is None
+
+    db.write_text(json.dumps(["just a string"]))
+    assert pch_compile_command(build, header, gch) is None
+
+    # An empty-string directory must fall back to the build dir, not cwd
+    db.write_text(
+        json.dumps(
+            [
+                {
+                    "directory": "",
+                    "command": f"g++ -DX=1 -o a.obj -c {src_file}",
+                    "file": src_file,
+                }
+            ]
+        )
+    )
+    _, cmd_dir = pch_compile_command(build, header, gch)
+    assert cmd_dir == build
+
+    # Corrupted entries with null fields must skip, not raise
+    db.write_text(
+        json.dumps(
+            [
+                {"file": None, "command": "g++ -c x.cpp", "directory": None},
+                {"file": src_file, "command": None, "directory": None},
+            ]
+        )
+    )
+    assert pch_compile_command(build, header, gch) is None
+
+    # arguments-style entry (allowed by the spec, unused by CMake)
+    db.write_text(
+        json.dumps([{"arguments": ["g++", "-c", src_file], "file": src_file}])
+    )
+    assert pch_compile_command(build, header, gch) is None
+
+
+def test_pch_header_list_order_is_in_checksum(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Reordering PCH_DEFAULT_HEADERS keeps the include closure identical, but the
+    generated header text differs, so the .gch must rebuild."""
+    import esphome.build_gen.espidf as espidf_mod
+
+    dev = _make_pch_device(tmp_path, "dev_r")
+    CORE.build_path = dev
+    gch = dev / "build" / "esphome_pch.h.gch"
+
+    def fake_compile(cmd, **kwargs):
+        gch.write_bytes(b"gch")
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=fake_compile),
+    ):
+        espidf_mod.prepare_pch()
+        first = (dev / "build" / "esphome_pch.h.gch.sum").read_text()
+        monkeypatch.setattr(
+            espidf_mod,
+            "PCH_DEFAULT_HEADERS",
+            tuple(reversed(espidf_mod.PCH_DEFAULT_HEADERS)),
+        )
+        espidf_mod.prepare_pch()
+    assert (dev / "build" / "esphome_pch.h.gch.sum").read_text() != first
+
+
+def test_prepare_pch_failure_writes_marker_and_skips_retry(tmp_path: Path) -> None:
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_f")
+    CORE.build_path = dev
+    calls = []
+
+    def failing_compile(cmd, **kwargs):
+        calls.append(cmd)
+        return subprocess.CompletedProcess(cmd, 1, "", "boom")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=failing_compile),
+    ):
+        prepare_pch()
+        prepare_pch()
+    assert len(calls) == 1
+    assert not (dev / "build" / "esphome_pch.h.gch.sum").exists()
+    assert (dev / "build" / "esphome_pch.h.gch.failed").exists()
+
+
+def test_prepare_pch_spawn_oserror_is_transient(tmp_path: Path) -> None:
+    """Spawn/IO failures retry on the next build instead of latching."""
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_o")
+    CORE.build_path = dev
+    calls = []
+
+    def raising(cmd, **kwargs):
+        calls.append(cmd)
+        raise OSError("no such compiler")
+
+    header = dev / "build" / "esphome_pch.h"
+    before = header.stat().st_mtime_ns
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=raising),
+    ):
+        prepare_pch()
+        prepare_pch()
+    assert not (dev / "build" / "esphome_pch.h.gch.failed").exists()
+    assert not (dev / "build" / "esphome_pch.h.gch.sum").exists()
+    assert len(calls) == 2
+    # No .gch was ever in play, so the header must not be re-touched into
+    # forcing a full rebuild on every failing build
+    assert header.stat().st_mtime_ns == before
+
+
+def test_prepare_pch_transient_with_stale_gch_bumps_header(tmp_path: Path) -> None:
+    """A stale .gch removed on a transient failure must dirty its consumers."""
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_s")
+    CORE.build_path = dev
+    gch = dev / "build" / "esphome_pch.h.gch"
+    gch.write_bytes(b"stale")
+    header = dev / "build" / "esphome_pch.h"
+    os.utime(header, (1, 1))
+    with (
+        patch.object(CORE, "name", "test"),
+        patch(
+            "esphome.build_helpers.pch.subprocess.run",
+            side_effect=OSError("no such compiler"),
+        ),
+    ):
+        prepare_pch()
+    assert not gch.exists()
+    assert header.stat().st_mtime_ns > 1_000_000_000
+
+
+def test_prepare_pch_disabled_discards_and_skips_compile(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The escape hatch is self-cleaning: a leftover .gch is removed."""
+    from esphome.build_gen.espidf import prepare_pch
+
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+    dev = _make_pch_device(tmp_path, "dev_d")
+    CORE.build_path = dev
+    stale = dev / "build" / "esphome_pch.h.gch"
+    stale.write_bytes(b"stale")
+    with patch("esphome.build_helpers.pch.subprocess.run", side_effect=AssertionError):
+        prepare_pch()
+    assert not stale.exists()
+
+
+def test_prepare_pch_missing_sdkconfig_fails_closed(tmp_path: Path) -> None:
+    """No sdkconfig means no config identity for the .sum: no pch at all."""
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_m")
+    (dev / "sdkconfig.test").unlink()
+    CORE.build_path = dev
+    stale = dev / "build" / "esphome_pch.h.gch"
+    stale.write_bytes(b"stale")
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=AssertionError),
+    ):
+        prepare_pch()
+    assert not stale.exists()
+    assert not (dev / "build" / "esphome_pch.h.gch.sum").exists()
+
+
+def test_prepare_pch_signal_kill_is_transient(tmp_path: Path) -> None:
+    """A signal-killed compile (OOM) must not latch the .failed marker."""
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_k")
+    CORE.build_path = dev
+    calls = []
+
+    def killed(cmd, **kwargs):
+        calls.append(cmd)
+        return subprocess.CompletedProcess(cmd, -9, "", "")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=killed),
+    ):
+        prepare_pch()
+        prepare_pch()
+    assert not (dev / "build" / "esphome_pch.h.gch.failed").exists()
+    assert len(calls) == 2
+
+
+def test_prepare_pch_probe_spawn_failure_degrades(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A probe that cannot run discards the pch; strict raises."""
+    from esphome.build_gen.espidf import prepare_pch
+    from esphome.core import EsphomeError
+
+    dev = _make_pch_device(tmp_path, "dev_pf")
+    CORE.build_path = dev
+    gch = dev / "build" / "esphome_pch.h.gch"
+
+    def probe_dies(cmd, **kwargs):
+        if "-fsyntax-only" in cmd:
+            raise OSError("probe spawn failed")
+        gch.write_bytes(b"gch")
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=probe_dies),
+    ):
+        prepare_pch()
+    assert not gch.exists()
+    assert not (dev / "build" / "esphome_pch.h.gch.sum").exists()
+
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=probe_dies),
+        pytest.raises(EsphomeError, match="probe did not run"),
+    ):
+        prepare_pch()
+
+
+@pytest.mark.parametrize(
+    ("stderr", "code"),
+    [("", -9), ("fatal: No space left on device", 1)],
+    ids=("signal-kill", "enospc"),
+)
+def test_prepare_pch_probe_environmental_failures_do_not_latch(
+    tmp_path: Path, stderr: str, code: int
+) -> None:
+    """A signal-killed or ENOSPC probe retries next build, no marker."""
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_pe")
+    CORE.build_path = dev
+    gch = dev / "build" / "esphome_pch.h.gch"
+
+    def env_probe(cmd, **kwargs):
+        if "-fsyntax-only" in cmd:
+            return subprocess.CompletedProcess(cmd, code, "", stderr)
+        gch.write_bytes(b"gch")
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=env_probe),
+    ):
+        prepare_pch()
+    assert not gch.exists()
+    assert not (dev / "build" / "esphome_pch.h.gch.failed").exists()
+
+
+def test_prepare_pch_signal_kill_strict_raises(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from esphome.build_gen.espidf import prepare_pch
+    from esphome.core import EsphomeError
+
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    dev = _make_pch_device(tmp_path, "dev_ks")
+    CORE.build_path = dev
+    with (
+        patch.object(CORE, "name", "test"),
+        patch(
+            "esphome.build_helpers.pch.subprocess.run",
+            side_effect=lambda cmd, **kw: subprocess.CompletedProcess(cmd, -9, "", ""),
+        ),
+        pytest.raises(EsphomeError, match="killed by signal"),
+    ):
+        prepare_pch()
+
+
+def test_prepare_pch_strict_raises_when_disabled(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Strict must not read a disabled pch as success."""
+    from esphome.build_gen.espidf import prepare_pch
+    from esphome.core import EsphomeError
+
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    dev = _make_pch_device(tmp_path, "dev_ds")
+    CORE.build_path = dev
+    with (
+        patch.object(CORE, "name", "test"),
+        pytest.raises(EsphomeError, match="disabled"),
+    ):
+        prepare_pch()
+
+
+def test_prepare_pch_missing_sdkconfig_strict_raises(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from esphome.build_gen.espidf import prepare_pch
+    from esphome.core import EsphomeError
+
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    dev = _make_pch_device(tmp_path, "dev_ss")
+    (dev / "sdkconfig.test").unlink()
+    CORE.build_path = dev
+    with (
+        patch.object(CORE, "name", "test"),
+        pytest.raises(EsphomeError, match="sdkconfig unreadable"),
+    ):
+        prepare_pch()
+
+
+def test_prepare_pch_without_compile_commands(tmp_path: Path) -> None:
+    """Stale checksum but no configured TU yet: no compile, no sidecars."""
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_n")
+    (dev / "build" / "compile_commands.json").unlink()
+    CORE.build_path = dev
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=AssertionError),
+    ):
+        prepare_pch()
+    assert not (dev / "build" / "esphome_pch.h.gch.sum").exists()
+    assert not (dev / "build" / "esphome_pch.h.gch.failed").exists()
+
+
+def test_write_project_pch_disabled_writes_no_header(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from esphome.build_gen.espidf import write_project
+
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+    _write_project_description(tmp_path, {})
+    CORE.build_path = tmp_path
+    with (
+        patch("esphome.build_gen.espidf.get_esp32_variant", return_value="ESP32"),
+        patch.object(CORE, "name", "test"),
+    ):
+        write_project()
+    assert not (tmp_path / "build" / "esphome_pch.h").exists()
+
+
+def test_write_project_writes_pch_header(tmp_path: Path) -> None:
+    """The header write_project emits is what _pch_cmake() force-includes;
+    this pairing is the one non-fail-safe path in the design."""
+    from esphome.build_gen.espidf import write_project
+    from esphome.build_helpers.pch import PCH_DEFAULT_HEADERS, pch_header_text
+
+    _write_project_description(tmp_path, {})
+    CORE.build_path = tmp_path
+    with (
+        patch("esphome.build_gen.espidf.get_esp32_variant", return_value="ESP32"),
+        patch.object(CORE, "name", "test"),
+    ):
+        write_project()
+    assert (tmp_path / "build" / "esphome_pch.h").read_text() == pch_header_text(
+        PCH_DEFAULT_HEADERS
+    )
+
+
+def test_prepare_pch_stale_bailout_removes_gch(tmp_path: Path) -> None:
+    """A stale .gch must not survive when no compile command is available."""
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_s")
+    CORE.build_path = dev
+    gch = dev / "build" / "esphome_pch.h.gch"
+    gch.write_bytes(b"stale")
+    (dev / "build" / "esphome_pch.h.gch.sum").write_text("stale-sum\n")
+    (dev / "build" / "compile_commands.json").unlink()
+    with patch.object(CORE, "name", "test"):
+        prepare_pch()
+    assert not gch.exists()
+    assert not (dev / "build" / "esphome_pch.h.gch.sum").exists()
+
+
+def test_prepare_pch_zero_exit_without_gch_is_failure(tmp_path: Path) -> None:
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_z")
+    CORE.build_path = dev
+
+    def no_output(cmd, **kwargs):
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=no_output),
+    ):
+        prepare_pch()
+    assert not (dev / "build" / "esphome_pch.h.gch.sum").exists()
+    assert (dev / "build" / "esphome_pch.h.gch.failed").exists()
+
+
+def test_prepare_pch_bumps_header_for_object_depends(tmp_path: Path) -> None:
+    """The OBJECT_DEPENDS edge watches the header; a rebuilt .gch must bump
+    it so pch-consuming TUs recompile."""
+    import os as _os
+
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_t")
+    CORE.build_path = dev
+    header = dev / "build" / "esphome_pch.h"
+    gch = dev / "build" / "esphome_pch.h.gch"
+    _os.utime(header, (0, 0))
+    before = header.stat().st_mtime
+
+    def fake_compile(cmd, **kwargs):
+        gch.write_bytes(b"gch")
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=fake_compile),
+    ):
+        prepare_pch()
+    assert header.stat().st_mtime > before
+
+
+def test_component_cmakelists_pch_object_depends() -> None:
+    from esphome.build_gen.espidf import get_component_cmakelists
+
+    content = get_component_cmakelists()
+    assert 'OBJECT_DEPENDS "${CMAKE_BINARY_DIR}/esphome_pch.h"' in content
+
+
+def test_prepare_pch_command_change_invalidates_sum(tmp_path: Path) -> None:
+    """A flag-only change in the compile DB must rebuild the .gch."""
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_c")
+    CORE.build_path = dev
+    gch = dev / "build" / "esphome_pch.h.gch"
+
+    def fake_compile(cmd, **kwargs):
+        gch.write_bytes(b"gch")
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=fake_compile),
+    ):
+        prepare_pch()
+        first = (dev / "build" / "esphome_pch.h.gch.sum").read_text()
+        db = dev / "build" / "compile_commands.json"
+        db.write_text(db.read_text().replace("-DX=1", "-DX=2"))
+        prepare_pch()
+    assert (dev / "build" / "esphome_pch.h.gch.sum").read_text() != first
+
+
+def test_prepare_pch_keeps_user_force_includes(tmp_path: Path) -> None:
+    from esphome.build_helpers.pch import pch_compile_command
+
+    dev = _make_pch_device(tmp_path, "dev_u")
+    CORE.build_path = dev
+    build = dev / "build"
+    src_file = str(dev / "src" / "esphome" / "a.cpp")
+    build.joinpath("compile_commands.json").write_text(
+        json.dumps(
+            [
+                {
+                    "directory": str(build),
+                    "command": (
+                        "g++ -include user.h -include esphome_pch.h "
+                        f"-o a.obj -c {src_file}"
+                    ),
+                    "file": src_file,
+                }
+            ]
+        )
+    )
+    cmd, _ = pch_compile_command(build, build / "esphome_pch.h", build / "x.gch")
+    assert "user.h" in cmd
+    assert "esphome_pch.h" not in " ".join(cmd[:-3])
+
+
+def test_prepare_pch_identity_unknown_discards(tmp_path: Path) -> None:
+    """An OSError from the checksum discards artifacts and skips the pch."""
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_i")
+    CORE.build_path = dev
+    stale = dev / "build" / "esphome_pch.h.gch"
+    stale.write_bytes(b"stale")
+    with (
+        patch.object(CORE, "name", "test"),
+        patch(
+            "esphome.build_helpers.pch.pch_checksum",
+            side_effect=OSError("stat failed"),
+        ),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=AssertionError),
+    ):
+        prepare_pch()
+    assert not stale.exists()
+    assert not (dev / "build" / "esphome_pch.h.gch.sum").exists()
+
+
+def test_prepare_pch_transient_compiler_failure_does_not_latch(
+    tmp_path: Path,
+) -> None:
+    """ENOSPC-style failures clear on their own; no .failed marker."""
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_e")
+    CORE.build_path = dev
+    calls = []
+
+    def enospc(cmd, **kwargs):
+        calls.append(cmd)
+        return subprocess.CompletedProcess(
+            cmd, 1, "", "fatal error: No space left on device"
+        )
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=enospc),
+    ):
+        prepare_pch()
+        prepare_pch()
+    assert not (dev / "build" / "esphome_pch.h.gch.failed").exists()
+    assert len(calls) == 2
+
+
+def test_prepare_pch_strict_raises_on_missing_db(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """ESPHOME_PCH_STRICT turns the silent skip into a failure."""
+    from esphome.build_gen.espidf import prepare_pch
+    from esphome.core import EsphomeError
+
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    dev = _make_pch_device(tmp_path, "dev_st")
+    (dev / "build" / "compile_commands.json").unlink()
+    CORE.build_path = dev
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=AssertionError),
+        pytest.raises(EsphomeError, match="no usable compile command"),
+    ):
+        prepare_pch()
+
+
+def test_prepare_pch_probe_rejection_latches_and_degrades(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A toolchain that cannot load its own .gch discards it, latches the
+    marker, and fails strict mode."""
+    from esphome.build_gen.espidf import prepare_pch
+    from esphome.core import EsphomeError
+
+    dev = _make_pch_device(tmp_path, "dev_p")
+    CORE.build_path = dev
+    gch = dev / "build" / "esphome_pch.h.gch"
+
+    def rejecting(cmd, **kwargs):
+        if "-fsyntax-only" in cmd:
+            if "-include" not in cmd:
+                # Baseline without the pch passes: the pch is to blame
+                return subprocess.CompletedProcess(cmd, 0, "", "")
+            return subprocess.CompletedProcess(
+                cmd, 1, "", "error: esphome_pch.h.gch: had text segment "
+            )
+        gch.write_bytes(b"gch")
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=rejecting),
+    ):
+        prepare_pch()
+    assert not gch.exists()
+    assert (dev / "build" / "esphome_pch.h.gch.failed").exists()
+
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    (dev / "build" / "esphome_pch.h.gch.failed").unlink()
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=rejecting),
+        pytest.raises(EsphomeError, match="cannot load the pch"),
+    ):
+        prepare_pch()
+
+
+def test_prepare_pch_strict_reprobes_cached_gch(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Rejection is per-process: strict must re-prove a cached .gch loads."""
+    from esphome.build_gen.espidf import prepare_pch
+    from esphome.core import EsphomeError
+
+    dev = _make_pch_device(tmp_path, "dev_rc")
+    CORE.build_path = dev
+    gch = dev / "build" / "esphome_pch.h.gch"
+
+    def ok(cmd, **kwargs):
+        if "-fsyntax-only" not in cmd:
+            gch.write_bytes(b"gch")
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=ok),
+    ):
+        prepare_pch()
+    assert gch.exists()
+
+    def reject(cmd, **kwargs):
+        assert "-fsyntax-only" in cmd, "cached path must not recompile"
+        if "-include" not in cmd:
+            return subprocess.CompletedProcess(cmd, 0, "", "")
+        return subprocess.CompletedProcess(
+            cmd, 1, "", "error: esphome_pch.h.gch: had text segment "
+        )
+
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=reject),
+        pytest.raises(EsphomeError, match="cannot load the pch"),
+    ):
+        prepare_pch()
+    assert not gch.exists()
+    # Per-process rejection may not reproduce: the cached path must not
+    # latch the pch off for later non-strict builds
+    assert not (dev / "build" / "esphome_pch.h.gch.failed").exists()
+
+
+def test_prepare_pch_unexpected_command_shape_degrades(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A tail the probe slice cannot trust discards and degrades."""
+    from esphome.build_gen.espidf import prepare_pch
+    from esphome.core import EsphomeError
+
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    dev = _make_pch_device(tmp_path, "dev_sh")
+    CORE.build_path = dev
+    gch = dev / "build" / "esphome_pch.h.gch"
+
+    def ok(cmd, **kwargs):
+        gch.write_bytes(b"gch")
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=ok),
+        patch(
+            "esphome.build_helpers.pch.pch_compile_command",
+            return_value=(
+                ["g++", "-DX=1", "-c", "x", "-o", "y", "extra"],
+                dev / "build",
+            ),
+        ),
+        pytest.raises(EsphomeError, match="command shape"),
+    ):
+        prepare_pch()
+    assert not gch.exists()
+
+    # Non-strict: same shape problem degrades without raising
+    monkeypatch.delenv("ESPHOME_PCH_STRICT")
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=ok),
+        patch(
+            "esphome.build_helpers.pch.pch_compile_command",
+            return_value=(
+                ["g++", "-DX=1", "-c", "x", "-o", "y", "extra"],
+                dev / "build",
+            ),
+        ),
+    ):
+        prepare_pch()
+    assert not gch.exists()
+
+
+def test_prepare_pch_probe_baseline_spawn_failure_is_transient(
+    tmp_path: Path,
+) -> None:
+    """A baseline that cannot spawn is environmental: no marker."""
+    from esphome.build_gen.espidf import prepare_pch
+
+    dev = _make_pch_device(tmp_path, "dev_bs")
+    CORE.build_path = dev
+    gch = dev / "build" / "esphome_pch.h.gch"
+
+    def flaky(cmd, **kwargs):
+        if "-fsyntax-only" in cmd:
+            if "-include" in cmd:
+                return subprocess.CompletedProcess(cmd, 1, "", "boom")
+            raise OSError("baseline spawn failed")
+        gch.write_bytes(b"gch")
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+
+    with (
+        patch.object(CORE, "name", "test"),
+        patch("esphome.build_helpers.pch.subprocess.run", side_effect=flaky),
+    ):
+        prepare_pch()
+    assert not gch.exists()
+    assert not (dev / "build" / "esphome_pch.h.gch.failed").exists()

tests/unit_tests/build_helpers/test_ccache.py

@@ -10,6 +10,7 @@ from unittest.mock import patch
 import pytest
 
 from esphome.build_helpers import ccache
+from esphome.core import CORE
 
 
 def test_resolve_opt_out() -> None:
@@ -120,3 +121,17 @@ def test_parse_enable_env_spelling_tables(
     """cv.boolean's spelling tables plus the 1/0 env convention."""
     monkeypatch.setenv("ESPHOME_CCACHE_ENABLE", raw)
     assert ccache.parse_enable_env("ESPHOME_CCACHE_ENABLE") is expected
+
+
+def test_effective_ccache_basedir_prefers_user_value(tmp_path: Path) -> None:
+    CORE.build_path = tmp_path
+    # Drive-qualified on Windows: "/custom/base" is not absolute there
+    base = "C:\\custom\\base" if os.name == "nt" else "/custom/base"
+    with patch.dict(os.environ, {"CCACHE_BASEDIR": base}, clear=True):
+        assert ccache.effective_ccache_basedir() == base
+    with patch.dict(os.environ, {}, clear=True):
+        assert ccache.effective_ccache_basedir() == str(tmp_path.resolve())
+    # Degenerate values would strip substrings ccache never rewrites
+    for bad in ("", "/", "a/b"):
+        with patch.dict(os.environ, {"CCACHE_BASEDIR": bad}, clear=True):
+            assert ccache.effective_ccache_basedir() == str(tmp_path.resolve())

tests/unit_tests/build_helpers/test_idedata.py

@@ -85,6 +85,87 @@ def test_parse_entry_resolves_relative_includes() -> None:
     assert all(Path(inc).is_absolute() for inc in includes)
 
 
+def test_parse_entry_resolves_force_include_path(tmp_path: Path) -> None:
+    """The pch -include is emitted relative to the build dir; idedata must
+    resolve it so cached flags work from any cwd."""
+    (tmp_path / "esphome_pch.h").write_text("")
+    entry = _entry(
+        str(tmp_path),
+        f"{tmp_path}/src/esphome/x.cpp",
+        "g++ -include esphome_pch.h -c x.cpp",
+    )
+
+    _, _, _, cxx_flags = idedata.parse_entry(entry)
+
+    idx = cxx_flags.index("-include")
+    resolved = cxx_flags[idx + 1]
+    assert Path(resolved).is_absolute()
+    assert resolved == str(tmp_path / "esphome_pch.h").replace("\\", "/")
+
+
+def test_parse_entry_resolves_joined_force_include(tmp_path: Path) -> None:
+    """The joined -includefoo.h spelling takes the same resolve path."""
+    (tmp_path / "esphome_pch.h").write_text("")
+    entry = _entry(
+        str(tmp_path),
+        f"{tmp_path}/src/esphome/x.cpp",
+        "g++ -includeesphome_pch.h -c x.cpp",
+    )
+
+    _, _, _, cxx_flags = idedata.parse_entry(entry)
+
+    resolved = cxx_flags[cxx_flags.index("-include") + 1]
+    assert resolved == str(tmp_path / "esphome_pch.h").replace("\\", "/")
+
+
+def test_parse_entry_keeps_search_chain_force_include(tmp_path: Path) -> None:
+    """-include names resolved via the -I chain (libretiny's Arduino.h) must
+    not be re-anchored to a nonexistent build-dir path."""
+    entry = _entry(
+        str(tmp_path),
+        f"{tmp_path}/src/esphome/x.cpp",
+        "g++ -include Arduino.h -c x.cpp",
+    )
+
+    _, _, _, cxx_flags = idedata.parse_entry(entry)
+
+    assert cxx_flags[cxx_flags.index("-include") + 1] == "Arduino.h"
+
+
+def test_parse_entry_warns_on_vanished_force_include(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A build-dir force-include deleted by clean_build must leave a trail;
+    a name resolvable via the -I chain must not warn."""
+    inc = tmp_path / "inc"
+    inc.mkdir()
+    (inc / "Arduino.h").write_text("")
+    entry = _entry(
+        str(tmp_path),
+        f"{tmp_path}/src/esphome/x.cpp",
+        f"g++ -I{inc} -include Arduino.h -include esphome_pch.h -c x.cpp",
+    )
+
+    _, _, _, cxx_flags = idedata.parse_entry(entry)
+
+    assert "Arduino.h" in cxx_flags
+    assert "esphome_pch.h" in caplog.text
+    assert "Arduino.h" not in caplog.text
+
+
+def test_parse_entry_drops_trailing_force_include(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    entry = _entry(
+        str(tmp_path), f"{tmp_path}/src/esphome/x.cpp", "g++ -c x.cpp -include"
+    )
+
+    _, _, _, cxx_flags = idedata.parse_entry(entry)
+
+    assert "-include" not in cxx_flags
+    assert "no argument" in caplog.text
+
+
 def test_parse_entry_skips_dependency_flags() -> None:
     """Dependency-generation flags (and their args) are dropped."""
     entry = _entry(
@@ -104,7 +185,7 @@ def test_expand_response_files(tmp_path: Path) -> None:
     rsp = tmp_path / "flags.rsp"
     rsp.write_text("-DFROM_RSP -I/rsp/inc")
 
-    tokens = idedata._expand_response_files(
+    tokens = idedata.expand_response_files(
         ["g++", f"@{rsp.name}", "-c", "x.cpp"], tmp_path
     )
 
@@ -115,7 +196,7 @@ def test_expand_response_files(tmp_path: Path) -> None:
 
 def test_expand_response_files_keeps_literal_when_missing(tmp_path: Path) -> None:
     """An unreadable ``@file`` token is kept verbatim rather than dropped."""
-    tokens = idedata._expand_response_files(["g++", "@nope.rsp"], tmp_path)
+    tokens = idedata.expand_response_files(["g++", "@nope.rsp"], tmp_path)
     assert "@nope.rsp" in tokens
 
 
@@ -327,7 +408,7 @@ def test_split_command_preserves_paths_and_unescapes_quotes() -> None:
     r"""Backslash paths survive while ``\"`` define-quoting is unescaped."""
     command = r"C:\esp\bin\riscv32-esp-elf-g++.exe -DVER=\"1.2.3\" -IC:/inc/a -c x.cpp"
 
-    tokens = idedata._split_command(command)
+    tokens = idedata.split_command(command)
 
     assert tokens[0] == r"C:\esp\bin\riscv32-esp-elf-g++.exe"
     assert '-DVER="1.2.3"' in tokens
@@ -341,8 +422,8 @@ def test_split_command_empty_returns_empty() -> None:
     Guards against ``CommandLineToArgvW("")`` returning the current process name
     instead of an empty list.
     """
-    assert idedata._split_command("") == []
-    assert idedata._split_command("   ") == []
+    assert idedata.split_command("") == []
+    assert idedata.split_command("   ") == []
 
 
 @pytest.mark.skipif(os.name != "nt", reason="Windows argv tokenization")
@@ -503,9 +584,9 @@ def test_load_or_build_idedata_rebuilds_non_dict_cache(tmp_path: Path) -> None:
 def test_is_launcher_matches_only_known_launchers() -> None:
     """Compilers of any shape pass; only the closed launcher set matches."""
     for token in ("/t/g++-13", "gcc-8.4.0", "clang++-17", "armcc", "icx", "cc"):
-        assert not idedata._is_launcher(token)
+        assert not idedata.is_launcher(token)
     for token in ("/opt/homebrew/bin/ccache", "CCACHE.EXE", "distcc", "sccache"):
-        assert idedata._is_launcher(token)
+        assert idedata.is_launcher(token)
 
 
 def test_load_or_build_idedata_corrupted_cache_is_logged(

tests/unit_tests/build_helpers/test_pch.py

@@ -0,0 +1,336 @@
+"""Tests for esphome.build_helpers.pch."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from esphome.build_helpers import pch
+
+
+def _write(src_dir: Path, name: str, content: str) -> None:
+    path = src_dir / name
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [
+        (None, True),
+        ("1", True),
+        ("0", False),
+        ("false", False),
+        ("", False),
+    ],
+)
+def test_pch_enabled(value: str | None, expected: bool) -> None:
+    env = {} if value is None else {"ESPHOME_PCH_ENABLE": value}
+    with patch.dict(os.environ, env, clear=True):
+        assert pch.pch_enabled() is expected
+
+
+def test_ccache_pch_env_empty_until_emitted() -> None:
+    """No sloppiness relaxation for a build that skipped the pch."""
+    with patch.dict(os.environ, {}, clear=True):
+        assert pch.ccache_pch_env() == {}
+
+
+def test_ccache_pch_env_enabled() -> None:
+    pch.mark_pch_emitted()
+    with patch.dict(os.environ, {}, clear=True):
+        env = pch.ccache_pch_env()
+    assert env["CCACHE_SLOPPINESS"] == "pch_defines,time_macros"
+    assert env["CCACHE_PCH_EXTSUM"] == "true"
+
+
+def test_ccache_pch_env_disabled() -> None:
+    with patch.dict(os.environ, {"ESPHOME_PCH_ENABLE": "0"}, clear=True):
+        assert pch.ccache_pch_env() == {}
+
+
+def test_ccache_pch_env_token_check_is_membership_not_substring(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A token merely containing ours must not suppress the union."""
+    pch.mark_pch_emitted()
+    with patch.dict(os.environ, {"CCACHE_SLOPPINESS": "pch_defines_extra"}, clear=True):
+        env = pch.ccache_pch_env()
+    assert env["CCACHE_SLOPPINESS"] == "pch_defines_extra,pch_defines,time_macros"
+
+
+def test_ccache_pch_env_unions_user_sloppiness(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Without pch_defines/time_macros ccache declines every pch-consuming
+    compile, so missing tokens are unioned onto the user's value."""
+    pch.mark_pch_emitted()
+    with patch.dict(os.environ, {"CCACHE_SLOPPINESS": "locale"}, clear=True):
+        env = pch.ccache_pch_env()
+    assert env["CCACHE_SLOPPINESS"] == "locale,pch_defines,time_macros"
+    assert env["CCACHE_PCH_EXTSUM"] == "true"
+    assert "Adding pch_defines,time_macros" in caplog.text
+    caplog.clear()
+    with patch.dict(
+        os.environ, {"CCACHE_SLOPPINESS": "pch_defines,time_macros"}, clear=True
+    ):
+        env = pch.ccache_pch_env()
+    assert "CCACHE_SLOPPINESS" not in env
+    assert not caplog.records
+
+
+def test_pch_header_text_preserves_order() -> None:
+    text = pch.pch_header_text(["b.h", "a.h"])
+    assert text == '#include "b.h"\n#include "a.h"\n'
+
+
+def test_include_closure_resolves_relative_and_root(tmp_path: Path) -> None:
+    """Sibling includes resolve against the includer's directory first,
+    full paths against the src root; unresolvable names end the walk."""
+    _write(tmp_path, "esphome/components/x/a.h", '#include "b.h"\n')
+    _write(
+        tmp_path,
+        "esphome/components/x/b.h",
+        '#include "esphome/core/deep.h"\n#include <system.h>\n#include "missing.h"\n',
+    )
+    _write(tmp_path, "esphome/core/deep.h", "")
+    closure = pch._include_closure(tmp_path, ["esphome/components/x/a.h"])
+    assert sorted(closure) == [
+        "esphome/components/x/a.h",
+        "esphome/components/x/b.h",
+        "esphome/core/deep.h",
+    ]
+
+
+def test_include_closure_handles_cycles(tmp_path: Path) -> None:
+    _write(tmp_path, "a.h", '#include "b.h"\n')
+    _write(tmp_path, "b.h", '#include "a.h"\n')
+    assert sorted(pch._include_closure(tmp_path, ["a.h"])) == ["a.h", "b.h"]
+
+
+def test_include_closure_blocks_parent_escape(tmp_path: Path) -> None:
+    _write(tmp_path / "src", "a.h", '#include "../outside.h"\n')
+    (tmp_path / "outside.h").write_text("")
+    assert sorted(pch._include_closure(tmp_path / "src", ["a.h"])) == ["a.h"]
+
+
+def test_pch_checksum_tracks_closure_content(tmp_path: Path) -> None:
+    """A transitive header edit or an extra-identity change must change the
+    digest; unrelated files must not."""
+    _write(tmp_path, "root.h", '#include "nested.h"\n')
+    _write(tmp_path, "nested.h", "int a;\n")
+    _write(tmp_path, "unrelated.h", "int u;\n")
+    base = pch.pch_checksum(tmp_path, ["root.h"], ["id"])
+    assert base == pch.pch_checksum(tmp_path, ["root.h"], ["id"])
+    assert base != pch.pch_checksum(tmp_path, ["root.h"], ["other-id"])
+    _write(tmp_path, "unrelated.h", "int changed;\n")
+    assert base == pch.pch_checksum(tmp_path, ["root.h"], ["id"])
+    _write(tmp_path, "nested.h", "int b;\n")
+    assert base != pch.pch_checksum(tmp_path, ["root.h"], ["id"])
+
+
+@pytest.mark.skipif(
+    os.name == "nt" or os.geteuid() == 0, reason="chmod is ineffective here"
+)
+def test_include_closure_fails_closed_on_unreadable(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A marker would truncate the transitive walk; the OSError propagates
+    so callers compile without a pch."""
+    _write(tmp_path, "a.h", '#include "locked.h"\n')
+    locked = tmp_path / "locked.h"
+    locked.write_text("")
+    locked.chmod(0)
+    try:
+        with pytest.raises(OSError):
+            pch._include_closure(tmp_path, ["a.h"])
+    finally:
+        locked.chmod(0o644)
+    assert "Could not read locked.h" in caplog.text
+
+
+def test_pch_extra_scripts_gated(monkeypatch: pytest.MonkeyPatch) -> None:
+    with patch.dict(os.environ, {}, clear=True):
+        assert pch.pch_extra_scripts() == ["post:pch.py"]
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+    assert pch.pch_extra_scripts() == []
+
+
+def test_include_closure_raises_when_identity_unknown(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """An unreadable header propagates; callers compile without a pch."""
+
+    class _BadFile:
+        def stat(self):  # noqa: ANN202 -- regular-file mode only
+            import os
+            import stat as stat_mod
+
+            return os.stat_result((stat_mod.S_IFREG | 0o644,) + (0,) * 9)
+
+        def read_bytes(self) -> bytes:
+            raise OSError("read failed")
+
+    class _FakeSrcDir:
+        def __truediv__(self, rel: str) -> _BadFile:
+            return _BadFile()
+
+    with pytest.raises(OSError, match="read failed"):
+        pch._include_closure(_FakeSrcDir(), ["a.h"])
+    assert "Could not read a.h" in caplog.text
+
+
+def test_include_closure_survives_non_utf8_include_name(tmp_path: Path) -> None:
+    """A non-UTF-8 quoted include must not abort the build; it simply does
+    not resolve and ends the walk."""
+    (tmp_path / "a.h").write_bytes(b'#include "bad\xff.h"\n#include "b.h"\n')
+    (tmp_path / "b.h").write_text("")
+    closure = pch._include_closure(tmp_path, ["a.h"])
+    assert set(closure) == {"a.h", "b.h"}
+
+
+def test_pch_checksum_survives_surrogate_extra(tmp_path: Path) -> None:
+    """Install paths from non-UTF-8 filesystems carry surrogates; hashing
+    them must not raise past the caller's identity-unknown guard."""
+    assert pch.pch_checksum(tmp_path, [], ["/opt/bad\udcff/framework"])
+
+
+def test_include_closure_walks_angle_includes_under_src(tmp_path: Path) -> None:
+    """An angle include resolving under src/ must enter the digest; one
+    that does not simply ends the walk."""
+    _write(tmp_path, "a.h", "#include <local.h>\n#include <Arduino.h>\n")
+    (tmp_path / "local.h").write_text("")
+    closure = pch._include_closure(tmp_path, ["a.h"])
+    assert set(closure) == {"a.h", "local.h"}
+
+
+def test_ccache_pch_env_warns_on_falsy_extsum(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A user CCACHE_PCH_EXTSUM=false makes ccache hash the .gch bytes."""
+    pch.mark_pch_emitted()
+    with patch.dict(os.environ, {"CCACHE_PCH_EXTSUM": "false"}, clear=True):
+        env = pch.ccache_pch_env()
+    assert "CCACHE_PCH_EXTSUM" not in env
+    assert "disables pch caching" in caplog.text
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [(None, False), ("0", False), ("1", True), ("true", True)],
+)
+def test_pch_strict(
+    value: str | None, expected: bool, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    if value is None:
+        monkeypatch.delenv("ESPHOME_PCH_STRICT", raising=False)
+    else:
+        monkeypatch.setenv("ESPHOME_PCH_STRICT", value)
+    assert pch.pch_strict() is expected
+
+
+def test_pch_degraded_raises_only_in_strict(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from esphome.core import EsphomeError
+
+    monkeypatch.delenv("ESPHOME_PCH_STRICT", raising=False)
+    pch.pch_degraded("reason")
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    with pytest.raises(EsphomeError, match="reason"):
+        pch.pch_degraded("reason")
+
+
+def test_pch_extra_scripts_strict_raises_when_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from esphome.core import EsphomeError
+
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    with pytest.raises(EsphomeError, match="disabled"):
+        pch.pch_extra_scripts()
+
+
+def test_pch_strict_rejects_unrecognized_values(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A typo must not silently disable the gate."""
+    from esphome.core import EsphomeError
+
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "yolo")
+    with pytest.raises(EsphomeError, match="Unrecognized ESPHOME_PCH_STRICT"):
+        pch.pch_strict()
+
+
+def test_discard_pch_raises_when_gch_survives(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A .gch an unlink failure leaves behind would be consumed silently."""
+    from pathlib import Path as _P
+
+    from esphome.core import EsphomeError
+
+    (tmp_path / "esphome_pch.h").write_text("")
+    gch = tmp_path / "esphome_pch.h.gch"
+    gch.write_bytes(b"gch")
+    real_unlink = _P.unlink
+
+    def failing_unlink(self, missing_ok=False):
+        if self.name.endswith(".gch"):
+            raise OSError("readonly")
+        return real_unlink(self, missing_ok=missing_ok)
+
+    monkeypatch.setattr(_P, "unlink", failing_unlink)
+    with pytest.raises(EsphomeError, match="Could not discard"):
+        pch.discard_pch(tmp_path)
+
+
+def test_discard_pch_raises_when_sum_survives(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The .sum is ccache's pch identity; one that survives is as unsafe
+    as a surviving .gch."""
+    from pathlib import Path as _P
+
+    from esphome.core import EsphomeError
+
+    (tmp_path / "esphome_pch.h").write_text("")
+    (tmp_path / "esphome_pch.h.gch").write_bytes(b"gch")
+    (tmp_path / "esphome_pch.h.gch.sum").write_text("x")
+    real_unlink = _P.unlink
+
+    def failing_unlink(self, missing_ok=False):
+        if self.name.endswith(".sum"):
+            raise OSError("readonly")
+        return real_unlink(self, missing_ok=missing_ok)
+
+    monkeypatch.setattr(_P, "unlink", failing_unlink)
+    with pytest.raises(EsphomeError, match="Could not discard"):
+        pch.discard_pch(tmp_path)
+
+
+def test_discard_pch_warns_when_file_vanished_concurrently(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """An unlink error on a file that is nonetheless gone only warns."""
+    from pathlib import Path as _P
+
+    (tmp_path / "esphome_pch.h").write_text("")
+    (tmp_path / "esphome_pch.h.gch").write_bytes(b"gch")
+    real_unlink = _P.unlink
+
+    def racing_unlink(self, missing_ok=False):
+        if self.name.endswith(".sum"):
+            # Racer removed it, then our unlink errored
+            raise OSError("stale handle")
+        return real_unlink(self, missing_ok=missing_ok)
+
+    monkeypatch.setattr(_P, "unlink", racing_unlink)
+    pch.discard_pch(tmp_path)
+    assert "Could not discard the pch sidecars" in caplog.text

tests/unit_tests/test_arduino8266_toolchain.py

@@ -9,6 +9,7 @@ from unittest.mock import MagicMock, patch
 import pytest
 
 from esphome.arduino8266 import framework, toolchain
+from esphome.build_helpers.pch import mark_pch_emitted
 import esphome.config_validation as cv
 from esphome.const import (
     CONF_COMPILE_PROCESS_LIMIT,
@@ -629,3 +630,28 @@ def test_get_idedata_accepts_preresolved_ccache() -> None:
         assert toolchain.get_idedata("/usr/bin/ccache") == {"ok": True}
     mock_resolve.assert_not_called()
     assert mock_build.call_args.kwargs["launcher"] == "/usr/bin/ccache"
+
+
+def test_ccache_env_includes_pch_settings() -> None:
+    """The native build exports the ccache settings the pch needs."""
+    mark_pch_emitted()
+    with patch.dict(os.environ, {}, clear=True):
+        env = framework.ccache_env("/usr/bin/ccache")
+    assert env["CCACHE_SLOPPINESS"] == "pch_defines,time_macros"
+    assert env["CCACHE_PCH_EXTSUM"] == "true"
+
+
+def test_ccache_env_pch_disabled() -> None:
+    with patch.dict(os.environ, {"ESPHOME_PCH_ENABLE": "0"}, clear=True):
+        env = framework.ccache_env("/usr/bin/ccache")
+    assert "CCACHE_SLOPPINESS" not in env
+    assert "CCACHE_PCH_EXTSUM" not in env
+
+
+def test_ccache_env_respects_user_sloppiness() -> None:
+    mark_pch_emitted()
+    with patch.dict(os.environ, {"CCACHE_SLOPPINESS": "locale"}, clear=True):
+        env = framework.ccache_env("/usr/bin/ccache")
+    # The user's tokens survive; the ones the pch needs are unioned on
+    assert env["CCACHE_SLOPPINESS"] == "locale,pch_defines,time_macros"
+    assert env["CCACHE_PCH_EXTSUM"] == "true"

tests/unit_tests/test_espidf_framework.py

@@ -19,6 +19,7 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 
+from esphome.build_helpers.pch import _PCHData
 from esphome.espidf.framework import (
     ESPHOME_STAMP_FILE,
     STAMP_SCHEMA_VERSION,
@@ -1592,10 +1593,14 @@ def _ccache_patches(tmp_path: Path, which: str | None, build_path: Path | None):
             "esphome.espidf.framework.get_idf_tools_path",
             return_value=tmp_path / "tools",
         ),
-        # ccache_defaults_env (build_helpers.ccache) reads CORE at call time
+        # ccache_defaults_env and the pch emission flag read CORE at call time
         patch(
             "esphome.core.CORE",
-            SimpleNamespace(build_path=build_path),
+            SimpleNamespace(
+                build_path=build_path,
+                # Pre-marked: these env tests model a pch-emitting build
+                data={"pch": _PCHData(emitted=True)},
+            ),
         ),
     )
 
@@ -1609,6 +1614,9 @@ def test_ccache_env_default_enabled_when_available(tmp_path: Path) -> None:
     assert env["CCACHE_NOHASHDIR"] == "true"
     assert env["CCACHE_DEPEND"] == "1"
     assert env["CCACHE_BASEDIR"] == str((tmp_path / "build").resolve())
+    # The pch cannot cache under ccache without these
+    assert env["CCACHE_SLOPPINESS"] == "pch_defines,time_macros"
+    assert env["CCACHE_PCH_EXTSUM"] == "true"
 
 
 def test_ccache_env_disabled_when_binary_missing(tmp_path: Path) -> None:

tests/unit_tests/test_espidf_toolchain.py

@@ -93,6 +93,13 @@ def test_get_configured_targets_ci_installs_all(monkeypatch: pytest.MonkeyPatch)
     assert toolchain._get_configured_targets() is None
 
 
+@pytest.fixture(autouse=True)
+def _no_ccache(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Deterministic run_compile: no host ccache probe, no pch work."""
+    monkeypatch.setenv("IDF_CCACHE_ENABLE", "0")
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+
+
 def _setup_build(setup_core: Path) -> tuple[Path, Path]:
     """Point CORE at a build dir; return (compile_commands, idedata cache) paths."""
     CORE.name = "test"
@@ -660,3 +667,75 @@ def test_get_core_framework_version_from_core_data():
 
     CORE.data = {KEY_ESP32: {KEY_IDF_VERSION: cv.Version(5, 5, 4)}}
     assert toolchain._get_core_framework_version() == "5.5.4"
+
+
+def test_run_compile_aborts_when_stale_pch_survives_discard(
+    setup_core: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """An undiscardable stale .gch means silently wrong output: abort."""
+    from esphome.core import EsphomeError
+
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "1")
+    _setup_build(setup_core)
+
+    with (
+        patch.object(toolchain, "need_reconfigure", return_value=False),
+        patch.object(toolchain, "run_idf_py", return_value=0),
+        patch.object(toolchain, "print_summary"),
+        patch("esphome.build_gen.espidf.prepare_pch", side_effect=RuntimeError("boom")),
+        patch(
+            "esphome.build_gen.espidf.discard_pch",
+            side_effect=EsphomeError("Could not discard the stale precompiled header"),
+        ),
+        pytest.raises(EsphomeError, match="Could not discard"),
+    ):
+        toolchain.run_compile({CONF_ESPHOME: {}}, verbose=False)
+
+
+def test_run_compile_strict_reraises_pch_failure(
+    setup_core: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """ESPHOME_PCH_STRICT must reach through the real compile flow."""
+    from esphome.core import EsphomeError
+
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "1")
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    _setup_build(setup_core)
+
+    with (
+        patch.object(toolchain, "need_reconfigure", return_value=False),
+        patch.object(toolchain, "run_idf_py", return_value=0),
+        patch.object(toolchain, "print_summary"),
+        patch(
+            "esphome.build_gen.espidf.prepare_pch",
+            side_effect=EsphomeError("ESPHOME_PCH_STRICT: no usable compile command"),
+        ),
+        pytest.raises(EsphomeError, match="no usable compile command"),
+    ):
+        toolchain.run_compile({CONF_ESPHOME: {}}, verbose=False)
+
+
+def test_run_compile_invokes_prepare_pch_and_survives_failure(
+    setup_core: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The pch hook runs before the build and a failure never aborts it."""
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "1")
+    _setup_build(setup_core)
+    # A stale .gch must be discarded on the failure path, never consumed
+    build = setup_core / "build" / "test" / "build"
+    build.mkdir(parents=True, exist_ok=True)
+    (build / "esphome_pch.h").write_text("")
+    stale_gch = build / "esphome_pch.h.gch"
+    stale_gch.write_bytes(b"stale")
+
+    with (
+        patch.object(toolchain, "need_reconfigure", return_value=False),
+        patch.object(toolchain, "run_idf_py", return_value=0),
+        patch.object(toolchain, "print_summary"),
+        patch(
+            "esphome.build_gen.espidf.prepare_pch", side_effect=RuntimeError("boom")
+        ) as prepare,
+    ):
+        assert toolchain.run_compile({CONF_ESPHOME: {}}, verbose=False) == 0
+    prepare.assert_called_once()
+    assert not stale_gch.exists()

tests/unit_tests/test_host_pch_prefix.py

@@ -0,0 +1,21 @@
+"""The host pch prefix must keep resolving; a rename would silently
+collapse the precompiled set to defines.h with strict CI still green."""
+
+from pathlib import Path
+import re
+
+from esphome.components.host import HOST_PCH_PREFIX
+
+REPO = Path(__file__).parents[2]
+
+
+def test_host_pch_prefix_resolves() -> None:
+    prefix = REPO / HOST_PCH_PREFIX
+    assert prefix.is_file()
+    body = prefix.read_text()
+    includes = re.findall(r'#include "([^"]+)"', body)
+    assert includes, "prefix wrapper folds nothing"
+    for name in includes:
+        assert (REPO / name).is_file(), f"{name} does not resolve"
+    # The C guard is what keeps build_src_flags safe on C/assembly edges
+    assert "#ifdef __cplusplus" in body

tests/unit_tests/test_platformio_pch_script.py

@@ -0,0 +1,581 @@
+"""Tests for esphome/platformio/pch.py.script against a fake SCons env."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import stat
+from unittest.mock import patch
+
+import pytest
+
+from esphome.platformio import toolchain
+
+pytestmark = pytest.mark.skipif(
+    os.name == "nt", reason="the fake compiler is a POSIX shell script"
+)
+
+_SCRIPT = Path(toolchain.__file__).parent / "pch.py.script"
+
+
+class _FakePlatform:
+    packages = {"framework-x": {}, "toolchain-y": {}}
+
+    def get_package_version(self, name: str) -> str:
+        if name == "toolchain-y":
+            raise KeyError(name)
+        return "1.2.3"
+
+    def get_package(self, name: str) -> object | None:
+        return None
+
+
+class _BrokenPlatform(_FakePlatform):
+    def get_package_version(self, name: str) -> str:
+        raise RuntimeError("manifest parse error")
+
+
+class _UnresolvedPlatform(_FakePlatform):
+    """KeyError from a package that IS installed: unresolved identity."""
+
+    def get_package_version(self, name: str) -> str:
+        raise KeyError(name)
+
+    def get_package(self, name: str) -> object:
+        return object()
+
+
+class _FakeSConsEnv(dict):
+    """Just enough of a SCons construction environment for pch.py."""
+
+    def __init__(
+        self,
+        proj_dir: Path,
+        src_dir: Path,
+        cxx: str,
+        flags: list[str],
+        platform_cls: type[_FakePlatform] = _FakePlatform,
+    ):
+        super().__init__(ENV={})
+        self._subst = {
+            "$PROJECT_DIR": str(proj_dir),
+            "$PROJECT_SRC_DIR": str(src_dir),
+            "$CXX": cxx,
+        }
+        self._flags = flags
+        self._platform_cls = platform_cls
+        self.prepended: list[str] = []
+
+    def subst(self, expr: str) -> str:  # noqa: N802
+        return self._subst[expr]
+
+    def subst_list(self, expr: str) -> list[list[str]]:  # noqa: N802
+        return [self._flags]
+
+    def PioPlatform(self) -> _FakePlatform:  # noqa: N802
+        return self._platform_cls()
+
+    def Prepend(self, CXXFLAGS: list[str]) -> None:  # noqa: N802, N803
+        self.prepended = CXXFLAGS
+
+
+def _fake_cxx(
+    tmp_path: Path,
+    fail: bool = False,
+    fail_msg: str | None = None,
+    reject_pch: bool = False,
+    probe_exit: int = 0,
+) -> Path:
+    """A compiler stand-in that records its argv and writes the -o target.
+
+    With reject_pch it builds the .gch fine but, like GCC 10 on macOS arm64,
+    warns on any consuming compile that the .gch cannot be loaded; probe_exit
+    sets the exit code of non-header compiles (the load probe).
+    """
+    cxx = tmp_path / "fake-gxx"
+    body = (
+        'printf -- ---call---\\\\n >> "$0.argv"; printf \'%s\\n\' "$@" >> "$0.argv"\n'
+    )
+    if fail:
+        body += f"echo {fail_msg or 'boom'} >&2\nexit 1\n"
+    else:
+        # Only the c++-header compile has a -o; the load probe has none
+        body += 'out=""; prev=""; mf=0; dep=0; inc=0\nfor a in "$@"; do [ "$prev" = "-o" ] && out="$a"; prev="$a"; [ "$a" = "-MF" ] && mf=1; [ "$a" = "-include" ] && inc=1; case "$a" in -M|-MM|-MD|-MMD) dep=1;; esac; done\n'
+        # Real cc1plus rejects -MF without a dependency flag
+        body += 'if [ "$mf" = 1 ] && [ "$dep" = 0 ]; then echo "cc1plus: error: to generate dependencies you must specify either \x27-M\x27 or \x27-MM\x27" >&2; exit 1; fi\n'
+        body += '[ -n "$out" ] && echo gch > "$out"\n'
+        if reject_pch:
+            # -Werror=invalid-pch makes rejection a nonzero exit; the
+            # baseline (no -include) still passes
+            body += 'case " $* " in *c++-header*) ;; *) if [ "$inc" = 1 ]; then echo "error: esphome_pch.h.gch: had text segment at different address" >&2; exit 1; fi;; esac\n'
+        body += f'case " $* " in *c++-header*) exit 0;; *) exit {probe_exit};; esac\n'
+    cxx.write_text("#!/bin/sh\n" + body)
+    cxx.chmod(cxx.stat().st_mode | stat.S_IEXEC)
+    return cxx
+
+
+def _run_script(
+    tmp_path: Path,
+    flags: list[str] | None = None,
+    fail: bool = False,
+    fail_msg: str | None = None,
+    reject_pch: bool = False,
+    probe_exit: int = 0,
+    missing_cxx: bool = False,
+    env_vars: dict[str, str] | None = None,
+    name: str = "dev",
+    platform_cls: type[_FakePlatform] = _FakePlatform,
+) -> _FakeSConsEnv:
+    proj = tmp_path / name
+    src = proj / "src"
+    (src / "esphome" / "core").mkdir(parents=True, exist_ok=True)
+    (src / "esphome" / "core" / "defines.h").write_text("#define USE_X\n")
+    cxx = _fake_cxx(
+        tmp_path,
+        fail=fail,
+        fail_msg=fail_msg,
+        reject_pch=reject_pch,
+        probe_exit=probe_exit,
+    )
+    if missing_cxx:
+        cxx = tmp_path / "no-such-gxx"
+    args = (proj, src, str(cxx), flags or ["-DX=1"], platform_cls)
+    # Distinct objects: the -include flags must land on projenv only
+    global_env = _FakeSConsEnv(*args)
+    projenv = _FakeSConsEnv(*args)
+    projenv.global_env = global_env
+    source = _SCRIPT.read_text()
+    with patch.dict(os.environ, env_vars or {}, clear=True):
+        exec(  # noqa: S102
+            compile(source, "pch.py", "exec"),
+            {"Import": lambda *_names: None, "env": global_env, "projenv": projenv},
+        )
+    return projenv
+
+
+def test_pch_script_builds_and_prepends_relative_include(tmp_path: Path) -> None:
+    scons_env = _run_script(tmp_path)
+    proj = tmp_path / "dev"
+    assert (proj / "esphome_pch.h").read_text().endswith('"esphome/core/defines.h"\n')
+    assert (proj / "esphome_pch.h.gch").is_file()
+    assert len((proj / "esphome_pch.h.gch.sum").read_text().strip()) == 64
+    # Relative include: an absolute path would poison ccache keys
+    assert scons_env.prepended == [
+        "-Winvalid-pch",
+        "-Wno-error=invalid-pch",
+        "-include",
+        "esphome_pch.h",
+    ]
+    # In production projenv["ENV"] aliases os.environ; only the -include
+    # flags are genuinely scoped to projenv (src compiles)
+    assert scons_env["ENV"]["CCACHE_SLOPPINESS"] == "pch_defines,time_macros"
+    assert scons_env["ENV"]["CCACHE_PCH_EXTSUM"] == "true"
+    assert scons_env.global_env.prepended == []
+
+
+def test_pch_script_preserves_spaced_flag_elements(tmp_path: Path) -> None:
+    """One SCons element stays one compiler argv; -include pairs are
+    stripped from the .gch compile."""
+    spaced = tmp_path / "My Configs"
+    spaced.mkdir()
+    (tmp_path / "dev" / "src").mkdir(parents=True, exist_ok=True)
+    (tmp_path / "dev" / "src" / "other.h").write_text("")
+    flags = ['-DUSB_PRODUCT=\\"Pico 2W\\"', "-I", str(spaced), "-include", "other.h"]
+    _run_script(tmp_path, flags=flags)
+    calls = (tmp_path / "fake-gxx.argv").read_text().split("---call---\n")
+    gch_call = next(c for c in calls if "c++-header" in c).splitlines()
+    assert '-DUSB_PRODUCT="Pico 2W"' in gch_call
+    assert str(spaced) in gch_call
+    assert "-include" not in gch_call
+    # The stripped src-resolvable -include is folded into the prefix header
+    pch = (tmp_path / "dev" / "esphome_pch.h").read_text()
+    assert pch.splitlines()[0] == '#include "other.h"'
+
+
+def test_pch_script_folds_joined_force_include_spelling(tmp_path: Path) -> None:
+    """-includefoo.h folds like the separated form, matching the native path."""
+    (tmp_path / "dev" / "src").mkdir(parents=True, exist_ok=True)
+    (tmp_path / "dev" / "src" / "other.h").write_text("")
+    _run_script(tmp_path, flags=["-DX=1", "-includeother.h"])
+    pch = (tmp_path / "dev" / "esphome_pch.h").read_text()
+    assert pch.splitlines()[0] == '#include "other.h"'
+
+
+def test_pch_script_leaves_absolute_force_includes_unfolded(
+    tmp_path: Path,
+) -> None:
+    """An absolute -include resolves through src_dir / name; it must still
+    stay consumer-only or the host path enters the .sum."""
+    outside = tmp_path / "outside.h"
+    outside.write_text("")
+    _run_script(tmp_path, flags=["-DX=1", "-include", str(outside)])
+    pch = (tmp_path / "dev" / "esphome_pch.h").read_text()
+    assert "outside.h" not in pch
+
+
+def test_pch_script_leaves_non_src_force_includes_unfolded(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """A user -include outside src/ must not enter the prefix header:
+    consumers keep their own copy, so folding an unguarded header would
+    include it twice."""
+    _run_script(tmp_path, flags=["-DX=1", "-include", "user_extra.h"])
+    pch = (tmp_path / "dev" / "esphome_pch.h").read_text()
+    assert "user_extra.h" not in pch
+    assert pch.splitlines()[-1] == '#include "esphome/core/defines.h"'
+    assert "not precompiling non-src force-includes" in capsys.readouterr().out
+
+
+def test_pch_script_sum_is_device_independent(tmp_path: Path) -> None:
+    """Regression: identical configs in different dirs share cache keys."""
+    sums = []
+    for name in ("dev_a", "dev_b"):
+        proj = tmp_path / name
+        _run_script(
+            tmp_path,
+            flags=["-DX=1", "-I", str(proj / "include")],
+            env_vars={"CCACHE_BASEDIR": str(proj)},
+            name=name,
+        )
+        sums.append((proj / "esphome_pch.h.gch.sum").read_text())
+        (tmp_path / "fake-gxx").unlink()
+        (tmp_path / "fake-gxx.argv").unlink(missing_ok=True)
+    assert sums[0] == sums[1]
+
+
+def test_pch_script_transient_compiler_failure_does_not_latch(
+    tmp_path: Path,
+) -> None:
+    """ENOSPC-style failures clear on their own; no .failed marker."""
+    scons_env = _run_script(tmp_path, fail=True, fail_msg="No space left on device")
+    proj = tmp_path / "dev"
+    assert not (proj / "esphome_pch.h.gch.failed").exists()
+    assert scons_env.prepended == []
+
+
+def test_pch_script_failure_marker_suppresses_retry(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    scons_env = _run_script(tmp_path, fail=True)
+    proj = tmp_path / "dev"
+    assert (proj / "esphome_pch.h.gch.failed").is_file()
+    assert not (proj / "esphome_pch.h.gch.sum").exists()
+    assert scons_env.prepended == []
+    # Second run: same checksum, no compile attempt, but says so
+    attempts = (tmp_path / "fake-gxx.argv").read_text().count("c++-header")
+    _run_script(tmp_path, fail=True)
+    out = capsys.readouterr().out
+    assert (tmp_path / "fake-gxx.argv").read_text().count("c++-header") == attempts
+    assert "delete esphome_pch.h.gch.failed to retry" in out
+
+
+def test_pch_script_probe_rejection_falls_back(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """A toolchain that cannot load its own .gch (GCC 10 on macOS arm64)
+    must not leave consumers paying for a pch every compile rejects."""
+    scons_env = _run_script(tmp_path, reject_pch=True)
+    proj = tmp_path / "dev"
+    assert not (proj / "esphome_pch.h.gch").exists()
+    assert not (proj / "esphome_pch.h.gch.sum").exists()
+    assert (proj / "esphome_pch.h.gch.failed").is_file()
+    assert scons_env.prepended == []
+    assert "toolchain cannot load the pch" in capsys.readouterr().out
+
+
+def test_pch_script_spawn_failure_is_transient(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """A spawn failure must not latch a .failed marker (matches espidf)."""
+    scons_env = _run_script(tmp_path, missing_cxx=True)
+    proj = tmp_path / "dev"
+    assert not (proj / "esphome_pch.h.gch.failed").exists()
+    assert not (proj / "esphome_pch.h.gch.sum").exists()
+    assert scons_env.prepended == []
+    assert "did not run" in capsys.readouterr().out
+
+
+def test_pch_script_probe_baseline_failure_latches_with_honest_label(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """Probe AND baseline failing is a deterministic environment problem:
+    latch, but blame the environment rather than the pch."""
+    scons_env = _run_script(tmp_path, probe_exit=1)
+    proj = tmp_path / "dev"
+    assert not (proj / "esphome_pch.h.gch").exists()
+    assert (proj / "esphome_pch.h.gch.failed").is_file()
+    assert scons_env.prepended == []
+    assert "probe cannot run at all" in capsys.readouterr().out
+
+
+def test_pch_script_unresolved_package_version_skips_pch(tmp_path: Path) -> None:
+    """A KeyError for an installed package is unresolved identity, not absence."""
+    scons_env = _run_script(tmp_path, platform_cls=_UnresolvedPlatform)
+    assert not (tmp_path / "dev" / "esphome_pch.h.gch").exists()
+    assert scons_env.prepended == []
+
+
+def test_pch_script_package_version_error_skips_pch(tmp_path: Path) -> None:
+    """Without trustworthy package identity a stale .gch could survive an
+    upgrade, so the script must not build one at all."""
+    scons_env = _run_script(tmp_path, platform_cls=_BrokenPlatform)
+    proj = tmp_path / "dev"
+    assert not (proj / "esphome_pch.h.gch").exists()
+    assert scons_env.prepended == []
+
+
+def test_pch_script_corrupt_sidecar_reads_as_stale(tmp_path: Path) -> None:
+    """A truncated/corrupt .failed marker must not disable the pch forever."""
+    _run_script(tmp_path, fail=True)
+    proj = tmp_path / "dev"
+    (proj / "esphome_pch.h.gch.failed").write_bytes(b"\xff\xfe corrupt")
+    _run_script(tmp_path)
+    assert (proj / "esphome_pch.h.gch").is_file()
+    assert (proj / "esphome_pch.h.gch.sum").is_file()
+
+
+def test_pch_script_rebuilds_when_header_missing(tmp_path: Path) -> None:
+    _run_script(tmp_path)
+    proj = tmp_path / "dev"
+    (proj / "esphome_pch.h").unlink()
+    _run_script(tmp_path)
+    assert (proj / "esphome_pch.h").is_file()
+
+
+def test_copy_pch_script(tmp_path: Path) -> None:
+    from esphome.core import CORE
+
+    CORE.build_path = tmp_path
+    toolchain.copy_pch_script()
+    assert (tmp_path / "pch.py").read_text() == _SCRIPT.read_text()
+
+
+def test_pch_script_unions_user_sloppiness(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """A user CCACHE_SLOPPINESS without the pch tokens gets them unioned on,
+    mirroring ccache_pch_env, or every src TU is a permanent miss."""
+    scons_env = _run_script(tmp_path, env_vars={"CCACHE_SLOPPINESS": "locale"})
+    assert scons_env["ENV"]["CCACHE_SLOPPINESS"] == "locale,pch_defines,time_macros"
+    assert "adding pch_defines,time_macros" in capsys.readouterr().out
+
+
+def test_pch_script_unmodelable_flag_skips_pch(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """Unbalanced quotes and multi-token elements cannot be reproduced as
+    one argv; the pch is skipped rather than built with diverging flags."""
+    for bad in ("-DFOO='bar", "-DA=1\t-DB=2"):
+        scons_env = _run_script(tmp_path, flags=["-DX=1", bad])
+        assert scons_env.prepended == []
+        assert not (tmp_path / "dev" / "esphome_pch.h.gch").exists()
+    assert "unmodelable flag" in capsys.readouterr().out
+
+
+@pytest.mark.skipif(
+    getattr(os, "geteuid", lambda: -1)() == 0, reason="root ignores file modes"
+)
+def test_pch_script_unlistable_include_dir_skips_pch(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """An unlistable subtree must not silently drop out of the digest."""
+    proj = tmp_path / "dev"
+    override = proj / "lwip_override"
+    hidden = override / "hidden"
+    hidden.mkdir(parents=True)
+    (hidden / "gen.h").write_text("")
+    hidden.chmod(0)
+    try:
+        scons_env = _run_script(tmp_path, flags=["-DX=1", "-I", str(override)])
+    finally:
+        hidden.chmod(0o755)
+    assert scons_env.prepended == []
+    assert "skipping precompiled header" in capsys.readouterr().out
+
+
+def test_pch_script_nobuild_without_projenv_is_noop(tmp_path: Path) -> None:
+    """-t nobuild never exports projenv; the script must not abort."""
+    proj = tmp_path / "dev"
+    (proj / "src").mkdir(parents=True)
+
+    def strict_import(*names: str) -> None:
+        if "projenv" in names:
+            raise RuntimeError("Import of non-existent variable 'projenv'")
+
+    env = _FakeSConsEnv(proj, proj / "src", "g++", ["-DX=1"])
+    exec(  # noqa: S102
+        compile(_SCRIPT.read_text(), "pch.py", "exec"),
+        {"Import": strict_import, "env": env},
+    )
+    assert not (proj / "esphome_pch.h").exists()
+
+
+def test_pch_script_ignores_library_trees_and_non_headers(tmp_path: Path) -> None:
+    """.piolibdeps and non-header files must not enter the digest (or be
+    read at all); package versions already cover library identity."""
+    proj = tmp_path / "dev"
+    libdeps = proj / ".piolibdeps" / "lib" / "src"
+    libdeps.mkdir(parents=True)
+    (libdeps / "lib.h").write_text("#define A 1\n")
+    override = proj / "lwip_override"
+    override.mkdir(parents=True)
+    (override / "lwipopts.h").write_text("#define TCP_MSS 1460\n")
+    (override / "notes.txt").write_text("v1\n")
+    flags = ["-DX=1", "-I", str(libdeps), "-I", str(override)]
+    _run_script(tmp_path, flags=flags)
+    first = (proj / "esphome_pch.h.gch.sum").read_text()
+    (libdeps / "lib.h").write_text("#define A 2\n")
+    (override / "notes.txt").write_text("v2\n")
+    (tmp_path / "fake-gxx.argv").unlink(missing_ok=True)
+    _run_script(tmp_path, flags=flags)
+    assert (proj / "esphome_pch.h.gch.sum").read_text() == first
+
+
+def test_pch_script_hashes_project_local_include_dirs(tmp_path: Path) -> None:
+    """Generated headers in project-local -I dirs (e.g. rp2's lwip_override)
+    must invalidate the checksum when they change."""
+    proj = tmp_path / "dev"
+    override = proj / "lwip_override"
+    override.mkdir(parents=True)
+    (override / "lwipopts.h").write_text("#define TCP_MSS 1460\n")
+    flags = ["-DX=1", "-I", str(override)]
+    _run_script(tmp_path, flags=flags)
+    first = (proj / "esphome_pch.h.gch.sum").read_text()
+    (override / "lwipopts.h").write_text("#define TCP_MSS 536\n")
+    (tmp_path / "fake-gxx.argv").unlink(missing_ok=True)
+    _run_script(tmp_path, flags=flags)
+    assert (proj / "esphome_pch.h.gch.sum").read_text() != first
+
+
+@pytest.mark.skipif(
+    getattr(os, "geteuid", lambda: -1)() == 0, reason="root ignores file modes"
+)
+def test_pch_script_unreadable_local_header_skips_pch(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """An unreadable generated header means unknown identity: no pch."""
+    proj = tmp_path / "dev"
+    override = proj / "lwip_override"
+    override.mkdir(parents=True)
+    secret = override / "lwipopts.h"
+    secret.write_text("#define TCP_MSS 1460\n")
+    secret.chmod(0)
+    scons_env = _run_script(tmp_path, flags=["-DX=1", "-I", str(override)])
+    assert not (proj / "esphome_pch.h.gch.sum").exists()
+    assert scons_env.prepended == []
+    assert "skipping precompiled header" in capsys.readouterr().out
+
+
+def test_pch_script_rejects_unrecognized_strict_value(tmp_path: Path) -> None:
+    """A typo'd knob must fail the build, not silently disable the gate."""
+    with pytest.raises(RuntimeError, match="Unrecognized ESPHOME_PCH_STRICT"):
+        _run_script(tmp_path, env_vars={"ESPHOME_PCH_STRICT": "yolo"})
+
+
+def test_pch_script_strict_tables_match_helpers(tmp_path: Path) -> None:
+    """The script's mirrored spelling tables must not drift."""
+    from esphome.helpers import FALSY_ENV_STRINGS, TRUTHY_ENV_STRINGS
+
+    proj = tmp_path / "dev"
+    (proj / "src").mkdir(parents=True)
+    # Hermetic: the constants are module-level, but the exec still runs
+    # _setup_pch, which must not touch the host toolchain
+    cxx = _fake_cxx(tmp_path)
+    env = _FakeSConsEnv(proj, proj / "src", str(cxx), ["-DX=1"])
+    namespace = {"Import": lambda *_names: None, "env": env, "projenv": env}
+    with patch.dict(os.environ, {}, clear=True):
+        exec(compile(_SCRIPT.read_text(), "pch.py", "exec"), namespace)  # noqa: S102
+    assert set(namespace["_TRUTHY"]) == set(TRUTHY_ENV_STRINGS)
+    # parse_enable_env handles the empty string separately
+    assert set(namespace["_FALSY"]) - {""} == set(FALSY_ENV_STRINGS)
+
+
+def test_pch_script_strict_reprobes_cached_gch(tmp_path: Path) -> None:
+    """Rejection is per-process: strict re-proves a cached .gch loads."""
+    _run_script(tmp_path)
+    proj = tmp_path / "dev"
+    assert (proj / "esphome_pch.h.gch").is_file()
+    (tmp_path / "fake-gxx.argv").unlink(missing_ok=True)
+    # Second run: cache fresh, but the toolchain now rejects loads
+    with pytest.raises(RuntimeError, match="not used"):
+        _run_script(tmp_path, reject_pch=True, env_vars={"ESPHOME_PCH_STRICT": "1"})
+    assert not (proj / "esphome_pch.h.gch").exists()
+
+
+def test_pch_script_strict_raises_when_pch_not_used(tmp_path: Path) -> None:
+    """ESPHOME_PCH_STRICT fails the build instead of degrading."""
+    with pytest.raises(RuntimeError, match="ESPHOME_PCH_STRICT"):
+        _run_script(tmp_path, fail=True, env_vars={"ESPHOME_PCH_STRICT": "1"})
+
+
+def test_pch_script_strict_fails_without_scons(tmp_path: Path) -> None:
+    """No SCons under PlatformIO is an anomaly; strict must not pass."""
+    proj = tmp_path / "dev"
+    (proj / "src").mkdir(parents=True)
+
+    def strict_import(*names: str) -> None:
+        if "projenv" in names:
+            raise RuntimeError("Import of non-existent variable 'projenv'")
+
+    import sys
+
+    env = _FakeSConsEnv(proj, proj / "src", "g++", ["-DX=1"])
+    with (
+        # None forces ImportError even where SCons is installed
+        patch.dict(sys.modules, {"SCons.Script": None}),
+        patch.dict(os.environ, {"ESPHOME_PCH_STRICT": "1"}, clear=True),
+        pytest.raises(RuntimeError, match="not used"),
+    ):
+        exec(  # noqa: S102
+            compile(_SCRIPT.read_text(), "pch.py", "exec"),
+            {"Import": strict_import, "env": env},
+        )
+
+
+def test_pch_script_strict_reraises_internal_errors(tmp_path: Path) -> None:
+    """The catch-all must not swallow programming errors in strict mode."""
+    with pytest.raises(TypeError):
+        _run_script(tmp_path, env_vars={"ESPHOME_PCH_STRICT": "1"}, platform_cls=None)
+
+
+@pytest.mark.parametrize(("targets", "passes"), [(["nobuild"], True), ([], False)])
+def test_pch_script_strict_projenv_skip_gated_on_nobuild(
+    tmp_path: Path, targets: list[str], passes: bool
+) -> None:
+    """-t nobuild compiles nothing, so the skip passes strict; a missing
+    projenv on a real compile must not."""
+    import sys
+    import types
+
+    proj = tmp_path / "dev"
+    (proj / "src").mkdir(parents=True)
+
+    def strict_import(*names: str) -> None:
+        if "projenv" in names:
+            raise RuntimeError("Import of non-existent variable 'projenv'")
+
+    scons = types.ModuleType("SCons")
+    scons_script = types.ModuleType("SCons.Script")
+    scons_script.COMMAND_LINE_TARGETS = targets
+    env = _FakeSConsEnv(proj, proj / "src", "g++", ["-DX=1"])
+    with (
+        patch.dict(sys.modules, {"SCons": scons, "SCons.Script": scons_script}),
+        patch.dict(os.environ, {"ESPHOME_PCH_STRICT": "1"}, clear=True),
+    ):
+        run = lambda: exec(  # noqa: S102, E731
+            compile(_SCRIPT.read_text(), "pch.py", "exec"),
+            {"Import": strict_import, "env": env},
+        )
+        if passes:
+            run()
+        else:
+            with pytest.raises(RuntimeError, match="not used"):
+                run()
+    assert not (proj / "esphome_pch.h").exists()
+
+
+def test_pch_script_strict_passes_on_success(tmp_path: Path) -> None:
+    scons_env = _run_script(tmp_path, env_vars={"ESPHOME_PCH_STRICT": "1"})
+    # Strict escalates the consumer edges too
+    assert "-Werror=invalid-pch" in scons_env.prepended
+    assert "-Wno-error=invalid-pch" not in scons_env.prepended

tests/unit_tests/test_writer.py

@@ -677,6 +677,32 @@ def test_clean_build_partial_exists(
     assert "dependencies.lock" not in caplog.text
 
 
+@patch("esphome.writer.CORE")
+def test_clean_build_partial_removes_pch_artifacts(
+    mock_core: MagicMock,
+    tmp_path: Path,
+) -> None:
+    """The PlatformIO pch sidecars live at the project root and must go in
+    a partial clean, like the native backend's under .pioenvs."""
+    names = (
+        "esphome_pch.h",
+        "esphome_pch.h.gch",
+        "esphome_pch.h.gch.sum",
+        "esphome_pch.h.gch.failed",
+    )
+    for name in names:
+        (tmp_path / name).write_text("x")
+    mock_core.relative_pioenvs_path.return_value = tmp_path / ".pioenvs"
+    mock_core.relative_piolibdeps_path.return_value = tmp_path / ".piolibdeps"
+    mock_core.relative_build_path.side_effect = lambda name: tmp_path / name
+    mock_core.relative_internal_path.side_effect = tmp_path.joinpath
+
+    clean_build()
+
+    for name in names:
+        assert not (tmp_path / name).exists()
+
+
 @patch("esphome.writer.CORE")
 def test_clean_build_nothing_exists(
     mock_core: MagicMock,