Merge branch 'esp32-pio-pch' into nrf52-pch

.github/workflows/ci-docker.yml

@@ -21,6 +21,7 @@ on:
       - "esphome/core/**"
       - "esphome/writer.py"
       - "esphome/build_gen/**"
+      - "esphome/build_helpers/**"
       - "esphome/espidf/**"
       - "esphome/platformio/**"
       - "esphome/components/bk72xx/**"
@@ -197,6 +198,7 @@ jobs:
         # the default.
         id:
           - esp8266-arduino
+          - esp8266-arduino-native
           - esp32-arduino-platformio
           - esp32-arduino-esp-idf
           - esp32-idf-platformio
@@ -207,6 +209,16 @@ 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.
+        # 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/build_gen/arduino8266.py

@@ -39,8 +39,13 @@ from esphome.build_helpers.pch import (
     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 (
@@ -1231,6 +1236,7 @@ def write_project(paths: InstalledPaths, ccache: str | None) -> bool:
             "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
@@ -1264,6 +1270,7 @@ def write_project(paths: InstalledPaths, ccache: str | None) -> bool:
             _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 "
@@ -1283,13 +1290,37 @@ def write_project(paths: InstalledPaths, ccache: str | None) -> bool:
             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
+            # -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 -Wno-error=invalid-pch -include {PCH_HEADER_NAME}"
+                f"-Winvalid-pch {escalation} -include {PCH_HEADER_NAME}"
             ]
             lines.append(f"srccxxflags = {' '.join(cxx_parts)}")
-            src_cxx_override = ("$srccxxflags", gch)
+            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),

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

@@ -291,30 +291,10 @@ target_link_options(${{COMPONENT_LIB}} PUBLIC
 
 
 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 ""
-    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>:-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"))
+    """Consumer block for the component CMakeLists. Baked at generation:
+    a strict-knob flip takes effect on the next esphome compile; a
+    hand-run idf.py keeps the old one."""
+    return pch.pch_cmake_consumer("${COMPONENT_LIB}", "${app_sources}")
 
 
 def prepare_pch() -> None:
@@ -323,6 +303,7 @@ def prepare_pch() -> None:
     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:
@@ -334,6 +315,7 @@ def prepare_pch() -> None:
             "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"),

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
 

esphome/build_helpers/pch.py

@@ -7,7 +7,8 @@ it too; Arduino.h visibility there is intended (esphome#8693).
 
 from __future__ import annotations
 
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
+from contextlib import suppress
 from dataclasses import dataclass
 import hashlib
 import json
@@ -64,6 +65,10 @@ PCH_ARTIFACT_NAMES = (
 # The core defines header every backend anchors its prefix on.
 PCH_CORE_HEADER = "esphome/core/defines.h"
 
+# Guarded curated-prefix wrapper for PlatformIO backends without framework
+# force-includes (host, esp32); folded by the pch script via build_src_flags.
+PCH_PREFIX_HEADER = "esphome/core/pch_prefix.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
@@ -102,6 +107,81 @@ def pch_enabled() -> bool:
     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 pch_cmake_consumer(target: str, sources_var: str) -> str:
+    """Emit the CMake block making ``target``'s C++ sources consume the
+    pch; empty when disabled. OBJECT_DEPENDS is on the header, not the
+    .gch (pch-baked headers drop out of TU depfiles); the -include stays
+    relative — an absolute path would poison ccache keys."""
+    if not pch_enabled():
+        return ""
+    escalation = pch_consumer_escalation()
+    return f"""
+# ESPHome precompiled header (see esphome/build_helpers/pch.py).
+# The touch keeps OBJECT_DEPENDS satisfiable when the build system itself
+# wiped the build dir after the header was written (west --pristine)
+if(NOT EXISTS "${{CMAKE_BINARY_DIR}}/{PCH_HEADER_NAME}")
+  file(TOUCH "${{CMAKE_BINARY_DIR}}/{PCH_HEADER_NAME}")
+endif()
+target_compile_options({target} PRIVATE
+    "$<$<COMPILE_LANGUAGE:CXX>:-Winvalid-pch>"
+    "$<$<COMPILE_LANGUAGE:CXX>:{escalation}>"
+    "$<$<COMPILE_LANGUAGE:CXX>:-include>"
+    "$<$<COMPILE_LANGUAGE:CXX>:{PCH_HEADER_NAME}>"
+)
+set_source_files_properties({sources_var} PROPERTIES
+    OBJECT_DEPENDS "${{CMAKE_BINARY_DIR}}/{PCH_HEADER_NAME}")
+"""
+
+
 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.
@@ -132,10 +212,37 @@ def ccache_pch_env() -> dict[str, str]:
     return env
 
 
+def guarded_prepare(build_dir: Path, prepare: Callable[[], None]) -> None:
+    """Run a backend's pch preparation; an optional speedup must never
+    abort the build. Strict is read first so its own knob error cannot
+    mask the real failure; discard_pch raises if a stale .gch survives;
+    the header is ensured so OBJECT_DEPENDS stays satisfiable."""
+    try:
+        prepare()
+    except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
+        strict = pch_strict()
+        discard_pch(build_dir)
+        if strict:
+            raise
+        header = build_dir / PCH_HEADER_NAME
+        if not header.exists():
+            try:
+                header.touch()
+            except OSError as err:
+                # The coming OBJECT_DEPENDS error would hide the real cause
+                _LOGGER.warning("Could not create the pch placeholder: %s", err)
+        _LOGGER.warning(
+            "Precompiled header setup failed; compiling without it", exc_info=True
+        )
+
+
 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)."""
-    return ["post:pch.py"] if pch_enabled() else []
+    if not pch_enabled():
+        pch_disabled_degraded()
+        return []
+    return ["post:pch.py"]
 
 
 def pch_header_text(include_headers: Iterable[str]) -> str:
@@ -303,15 +410,30 @@ def discard_pch(build_dir: Path) -> None:
 
     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.
+    .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()
-    gch.unlink(missing_ok=True)
-    Path(f"{gch}.sum").unlink(missing_ok=True)
+    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():
-        os.utime(header)
+        with suppress(OSError):
+            os.utime(header)
 
 
 def prepare_pch(
@@ -334,6 +456,7 @@ def prepare_pch(
     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
@@ -360,61 +483,118 @@ def prepare_pch(
             "Could not establish the pch identity; compiling without it: %s", err
         )
         discard_pch(build_dir)
-        return
-    if gch.is_file() and _read_stamp(sum_path) == checksum:
-        _log_pch_in_use()
+        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()
-    try:
-        result = subprocess.run(
-            cmd,
-            cwd=cmd_dir,
-            # C locale keeps diagnostics matchable by _TRANSIENT_ERRORS
-            env={**os.environ, "LC_ALL": "C"},
-            capture_output=True,
-            text=True,
-            check=False,
-            timeout=300,
-        )
-        error = None
-        if result.returncode < 0:
-            # Killed by a signal (OOM, ^C): environmental, do not latch
-            _LOGGER.warning(
-                "Precompiled header compile was killed (signal %d); retrying "
-                "next build",
-                -result.returncode,
-            )
-            discard_pch(build_dir)
-            return
-        if result.returncode != 0:
-            error = result.stderr.strip() or f"exit code {result.returncode}"
-        elif not gch.is_file():
-            error = "compiler produced no .gch"
-    except (OSError, subprocess.SubprocessError) as err:
-        # Transient (timeout, spawn/IO): warn and retry next build, no marker
-        _LOGGER.warning("Precompiled header compile did not run: %s", err)
-        discard_pch(build_dir)
+    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:
-        _LOGGER.warning(
-            "Precompiled header failed; compiling without it: %s", error[:400]
-        )
-        # This path latches, so keep the full compiler output recoverable
-        _LOGGER.debug("Full pch compile output: %s", error)
-        discard_pch(build_dir)
-        if any(m in error for m in _TRANSIENT_ERRORS):
-            # Resource exhaustion clears on its own; retry next build
-            return
-        # Skip retries until a header/flag/backend-identity/command change
-        failed_marker.write_text(checksum + "\n", encoding="utf-8")
-        os.utime(header)
+        _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")

esphome/components/esp32/__init__.py

@@ -10,6 +10,7 @@ import subprocess
 from typing import Any
 
 from esphome import yaml_util
+from esphome.build_helpers.pch import PCH_PREFIX_HEADER, pch_enabled, pch_extra_scripts
 import esphome.codegen as cg
 from esphome.components.const import CONF_ENABLE_OTA_DOWNGRADE_PROTECTION
 from esphome.config_helpers import filter_source_files_from_defines
@@ -57,6 +58,7 @@ from esphome.coroutine import CoroPriority, coroutine_with_priority
 from esphome.espidf.component import generate_idf_components
 import esphome.final_validate as fv
 from esphome.helpers import copy_file_if_changed, rmtree, write_file_if_changed
+from esphome.platformio.toolchain import copy_pch_script
 from esphome.schema_extractors import SCHEMA_EXTRACT, schema_extractor
 from esphome.types import ConfigType
 from esphome.writer import clean_build, clean_cmake_cache
@@ -2455,6 +2457,11 @@ async def to_code(config):
 
         cg.add_platformio_option("lib_ldf_mode", "off")
         cg.add_platformio_option("lib_compat_mode", "strict")
+        # CI-speed only: this toolchain is being dropped, so the pch gets
+        # the same curated prefix as host with no further investment
+        cg.add_platformio_option("extra_scripts", pch_extra_scripts())
+        if pch_enabled():
+            cg.add_platformio_option("build_src_flags", f"-include {PCH_PREFIX_HEADER}")
         cg.add_platformio_option("platform", conf[CONF_PLATFORM_VERSION])
         cg.add_platformio_option("board", config[CONF_BOARD])
         cg.add_platformio_option("board_upload.flash_size", config[CONF_FLASH_SIZE])
@@ -3372,6 +3379,8 @@ def _write_idf_component_yml():
 def copy_files():
     _write_sdkconfig()
     _write_idf_component_yml()
+    if not CORE.using_toolchain_esp_idf:
+        copy_pch_script()
 
     if "partitions.csv" not in CORE.data[KEY_ESP32][KEY_EXTRA_BUILD_FILES]:
         flash_size = CORE.data[KEY_ESP32][KEY_FLASH_SIZE]

esphome/components/host/__init__.py

@@ -1,3 +1,4 @@
+from esphome.build_helpers.pch import PCH_PREFIX_HEADER, 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
@@ -55,9 +56,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 {PCH_PREFIX_HEADER}")
 
 
 # Called by writer.py
 def copy_files() -> None:
     copy_ccache_script()
+    copy_pch_script()

esphome/components/nrf52/__init__.py

@@ -1,13 +1,24 @@
 from __future__ import annotations
 
 import asyncio
+from functools import partial
 import logging
 from pathlib import Path
 import re
 import shutil
+import stat
 import subprocess
 
 from esphome import pins
+from esphome.build_helpers import pch
+from esphome.build_helpers.pch import (
+    PCH_DEFAULT_HEADERS,
+    PCH_HEADER_NAME,
+    mark_pch_emitted,
+    pch_cmake_consumer,
+    pch_enabled,
+    pch_header_text,
+)
 import esphome.codegen as cg
 from esphome.components.zephyr import (
     add_extra_script,
@@ -805,6 +816,9 @@ def _generate_cmake_lists() -> bool:
             ")",
         ]
 
+    if consumer := pch_cmake_consumer("app", "${APP_SOURCES}"):
+        lines += consumer.splitlines()
+
     if link_flags:
         lines += [
             "",
@@ -819,6 +833,66 @@ def _generate_cmake_lists() -> bool:
     )
 
 
+def _app_build_dir(build_dir: Path) -> Path:
+    """The CMake binary dir of the app image: sysbuild nests it in a
+    domain dir named after the app source dir. Probed on disk (the
+    non-sysbuild zephyr/ output dir has no CMakeCache.txt) so it stays
+    truthful mid-build, unlike an SDK-version check."""
+    sysbuild_app = build_dir / "zephyr"
+    try:
+        cache = (sysbuild_app / "CMakeCache.txt").stat()
+    except (FileNotFoundError, NotADirectoryError):
+        return build_dir
+    # Other stat errors propagate; is_file() would silently mislocate the pch
+    return sysbuild_app if stat.S_ISREG(cache.st_mode) else build_dir
+
+
+def _prepare_pch(app_dir: Path) -> None:
+    """Build the .gch between the cmake and compile phases of west."""
+    if not pch_enabled():
+        pch.discard_pch(app_dir)
+        pch.pch_disabled_degraded()
+        return
+    # First, so OBJECT_DEPENDS is satisfied even when the pch degrades
+    app_dir.mkdir(parents=True, exist_ok=True)
+    write_file_if_changed(
+        app_dir / PCH_HEADER_NAME, pch_header_text(PCH_DEFAULT_HEADERS)
+    )
+    # New layout first (Zephyr >= 3.4 nests under zephyr/); fixed candidates
+    # keep the .sum identity deterministic and skip walking generated/
+    generated = app_dir / "zephyr" / "include" / "generated"
+    autoconf = None
+    for candidate in (generated / "zephyr" / "autoconf.h", generated / "autoconf.h"):
+        if candidate.exists():
+            autoconf = candidate
+            break
+    if autoconf is None:
+        # Fail closed: autoconf.h is the .sum's Kconfig identity
+        _LOGGER.warning("No autoconf.h found; compiling without the pch")
+        pch.discard_pch(app_dir)
+        pch.pch_degraded("autoconf.h missing")
+        return
+    try:
+        autoconf_text = autoconf.read_text(encoding="utf-8")
+    except OSError as err:
+        _LOGGER.warning(
+            "Could not read %s; compiling without the pch: %s", autoconf, err
+        )
+        pch.discard_pch(app_dir)
+        pch.pch_degraded(f"autoconf unreadable: {err}")
+        return
+    pch.prepare_pch(
+        app_dir,
+        PCH_DEFAULT_HEADERS,
+        (
+            str(CORE.data[KEY_CORE][KEY_FRAMEWORK_VERSION]),
+            zephyr_data()[KEY_BOARD],
+            autoconf_text,
+            *get_project_compile_flags(),
+        ),
+    )
+
+
 def _copy_if_exists(src: Path, dst: Path) -> None:
     if src.is_file():
         shutil.copy2(src, dst)
@@ -871,6 +945,58 @@ def run_compile(args, config: ConfigType) -> bool:
         str(source_dir),
     ]
 
+    if pch_enabled():
+        # Consumers carry the -include; gate the ccache relaxation on it
+        # (Zephyr auto-enables ccache as the compiler launcher when found)
+        mark_pch_emitted()
+        env.update(pch.ccache_pch_env())
+
+        # Configure first so the .gch compiles from settled compile DB
+        # flags. Only when the app DB is missing: input changes wipe the
+        # build dir, so an existing DB is settled and --cmake-only would
+        # reconfigure for nothing.
+        prepare = True
+        app_dir = _app_build_dir(build_dir)
+        if not (app_dir / "compile_commands.json").is_file():
+            if not run_command_ok(
+                west_cmd + ["--cmake-only", "--", "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON"],
+                env=env,
+                stream_output=True,
+                cwd=str(paths["framework_path"]),
+            ):
+                raise EsphomeError("nRF52 native build configure failed")
+            # The configure phase creates the sysbuild domain dir: re-resolve
+            app_dir = _app_build_dir(build_dir)
+            # kernel.h needs the build-time syscall headers; under sysbuild
+            # the target exists only in the app domain's ninja
+            if not run_command_ok(
+                [
+                    "cmake",
+                    "--build",
+                    str(app_dir),
+                    "--target",
+                    "zephyr_generated_headers",
+                ],
+                env=env,
+                stream_output=True,
+                cwd=str(paths["framework_path"]),
+            ):
+                # A pch-only prerequisite: degrade, let the real build report.
+                # Also skip the .gch compile: it would fail on the missing
+                # headers and latch .gch.failed until an identity change
+                _LOGGER.warning(
+                    "Zephyr header generation failed; compiling without the pch"
+                )
+                pch.discard_pch(app_dir)
+                pch.pch_degraded("zephyr_generated_headers failed")
+                prepare = False
+    else:
+        prepare = True
+        app_dir = _app_build_dir(build_dir)
+
+    if prepare:
+        pch.guarded_prepare(app_dir, partial(_prepare_pch, app_dir))
+
     if not run_command_ok(
         west_cmd,
         env=env,

esphome/core/__init__.py

@@ -1143,13 +1143,14 @@ class EsphomeCore:
     def add_platformio_option(
         self, key: str, value: str | list[str], *, replace: bool = False
     ) -> None:
-        """Set a platformio.ini option; list values append to an existing list
-        unless ``replace`` is True, which overwrites any existing value."""
+        """Set a platformio.ini option; values append to an existing list
+        (a string as one element) unless ``replace`` is True, which
+        overwrites any existing value."""
         new_val = value
         old_val = self.platformio_options.get(key)
         if not replace and isinstance(old_val, list):
-            assert isinstance(value, list)
-            new_val = old_val + value
+            # A user platformio_options string must merge, not assert
+            new_val = old_val + ([value] if isinstance(value, str) else value)
         self.platformio_options[key] = new_val
 
     def _get_variable_generator(self, id):

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/toolchain.py

@@ -1,6 +1,5 @@
 """ESP-IDF direct build API for ESPHome."""
 
-from contextlib import suppress
 from dataclasses import dataclass, field
 import hashlib
 import json
@@ -529,19 +528,11 @@ 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
+    # After every reconfigure so compile_commands and sdkconfig are settled
+    from esphome.build_gen.espidf import prepare_pch
+    from esphome.build_helpers.pch import guarded_prepare
 
-    try:
-        prepare_pch()
-    except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
-        # Discard so a stale .gch can never be consumed
-        with suppress(OSError):
-            discard_pch()
-        _LOGGER.warning(
-            "Precompiled header setup failed; compiling without it", exc_info=True
-        )
+    guarded_prepare(CORE.relative_build_path("build"), prepare_pch)
 
     # Build
     args = []

esphome/platformio/pch.py.script

@@ -20,11 +20,22 @@ except Exception as err:  # noqa: BLE001 -- not exported under -t nobuild
 # 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, and stamp flow in sync with build_helpers/pch.py.
+# 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"
 
@@ -117,26 +128,12 @@ def _compile_gch(cxx, flags, header: Path, gch: Path, proj_dir: Path):
         raise OSError(f"compiler killed by signal {-result.returncode}")
     if result.returncode != 0:
         return result.stderr
-    # -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 []
-    )
+    return _probe_gch(cxx, flags, header, proj_dir)
+
+
+def _probe_run(cxx, flags, extra, proj_dir: Path):
     probe = subprocess.run(  # noqa: PLW1510
-        [
-            cxx,
-            *flags,
-            *dep_redirect,
-            "-Winvalid-pch",
-            "-include",
-            str(header),
-            "-fsyntax-only",
-            "-x",
-            "c++",
-            "-",
-        ],
+        [cxx, *flags, *extra, "-fsyntax-only", "-x", "c++", "-"],
         cwd=proj_dir,
         env={**os.environ, "LC_ALL": "C"},
         input="",
@@ -145,9 +142,34 @@ def _compile_gch(cxx, flags, header: Path, gch: Path, proj_dir: Path):
     )
     if probe.returncode < 0:
         raise OSError(f"probe killed by signal {-probe.returncode}")
-    if probe.returncode != 0 or ".gch" in probe.stderr:
-        return f"toolchain cannot load the pch: {probe.stderr.strip()}"
-    return None
+    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:
@@ -158,11 +180,18 @@ def _read_stamp(path: Path) -> str:
         return ""
 
 
-def _setup_pch() -> None:
+def _setup_pch() -> bool | None:
     if projenv is None:
-        # Expected under -t nobuild; anything else must leave a trail
         print(f"ESPHome: projenv unavailable ({_projenv_error}); skipping pch")
-        return
+        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
@@ -286,12 +315,22 @@ def _setup_pch() -> None:
     checksum = digest.hexdigest()
 
     # The ccache .sum sidecar doubles as the freshness stamp
-    if (
-        not header.is_file()
-        or not gch.is_file()
-        or not sum_path.is_file()
-        or (_read_stamp(sum_path) != checksum)
-    ):
+    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(
@@ -351,14 +390,27 @@ def _setup_pch() -> None:
     # -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", "-Wno-error=invalid-pch", "-include", header.name]
+        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:
-    _setup_pch()
+    _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/writer.py

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

script/determine-jobs.py

@@ -543,6 +543,11 @@ _SMOKE_HARNESS_TRIGGER_FILES = frozenset(
 
 ESP32_PLATFORMIO_TRIGGER_FILES = _SMOKE_HARNESS_TRIGGER_FILES | {
     "esphome/build_gen/platformio.py",
+    # The pch machinery the strict smoke job polices, and the modules it
+    # imports; the rest of build_helpers/ does not affect PlatformIO builds
+    "esphome/build_helpers/pch.py",
+    "esphome/build_helpers/ccache.py",
+    "esphome/build_helpers/idedata.py",
 }
 
 

tests/script/test_determine_jobs.py

@@ -1013,6 +1013,10 @@ _ESP32_PLATFORMIO_FULL_LIST_FILES = [
     # PlatformIO subsystem (path-prefix trigger) + build generator
     ["esphome/platformio/runner.py"],
     ["esphome/platformio/toolchain.py"],
+    # The pch modules are standalone triggers, not the whole build_helpers/
+    ["esphome/build_helpers/pch.py"],
+    ["esphome/build_helpers/ccache.py"],
+    ["esphome/build_helpers/idedata.py"],
     ["esphome/build_gen/platformio.py"],
     # Workflow / harness files
     ["script/test_build_components.py"],
@@ -1071,6 +1075,9 @@ def test_esp32_platformio_components_to_test_returns_full_list_on_infrastructure
         # Non-PlatformIO files in esphome/build_gen/ do NOT trigger the
         # full list -- only esphome/build_gen/platformio.py is a trigger.
         (["esphome/build_gen/espidf.py"], [], []),
+        # build_helpers modules the pch does not import are not triggers.
+        (["esphome/build_helpers/size_summary.py"], [], []),
+        (["esphome/build_helpers/ninja.py"], [], []),
         # Docs / unrelated files -> empty.
         (["README.md"], [], []),
         ([], [], []),

tests/unit_tests/build_gen/test_arduino8266.py

@@ -1842,3 +1842,53 @@ def test_write_project_pch_no_device_path_poison(tmp_path: Path) -> None:
             (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

@@ -550,6 +550,9 @@ def test_prepare_pch_writes_header_and_sum(tmp_path: Path) -> None:
     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")
@@ -601,6 +604,11 @@ def test_component_cmakelists_pch_block(monkeypatch: pytest.MonkeyPatch) -> None
 
     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()
@@ -891,6 +899,125 @@ def test_prepare_pch_signal_kill_is_transient(tmp_path: Path) -> None:
     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
@@ -1103,3 +1230,182 @@ def test_prepare_pch_transient_compiler_failure_does_not_latch(
         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_pch.py

@@ -216,3 +216,166 @@ def test_ccache_pch_env_warns_on_falsy_extsum(
         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_cmake_consumer_substitutes_target_and_sources(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("ESPHOME_PCH_ENABLE", raising=False)
+    monkeypatch.delenv("ESPHOME_PCH_STRICT", raising=False)
+    block = pch.pch_cmake_consumer("app", "${APP_SOURCES}")
+    assert "target_compile_options(app PRIVATE" in block
+    assert '"$<$<COMPILE_LANGUAGE:CXX>:-Winvalid-pch>"' in block
+    assert "-Wno-error=invalid-pch" in block
+    assert '"$<$<COMPILE_LANGUAGE:CXX>:esphome_pch.h>"' in block
+    assert "set_source_files_properties(${APP_SOURCES} PROPERTIES" in block
+    assert 'OBJECT_DEPENDS "${CMAKE_BINARY_DIR}/esphome_pch.h"' in block
+    # Placeholder guard: survives a build-system-side pristine wipe
+    assert 'file(TOUCH "${CMAKE_BINARY_DIR}/esphome_pch.h")' in block
+
+
+def test_pch_cmake_consumer_strict_escalates(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("ESPHOME_PCH_ENABLE", raising=False)
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    assert "-Werror=invalid-pch" in pch.pch_cmake_consumer("app", "${APP_SOURCES}")
+
+
+def test_pch_cmake_consumer_empty_when_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+    assert pch.pch_cmake_consumer("app", "${APP_SOURCES}") == ""
+
+
+def test_guarded_prepare_logs_placeholder_failure(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A failed placeholder touch must be traceable, not silent."""
+    monkeypatch.delenv("ESPHOME_PCH_STRICT", raising=False)
+
+    def boom() -> None:
+        raise RuntimeError("boom")
+
+    # Missing build dir: the touch raises and only warns
+    pch.guarded_prepare(tmp_path / "missing", boom)
+    assert "Could not create the pch placeholder" in caplog.text
+
+
+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/components/esp32/test_pch_wiring.py

@@ -0,0 +1,43 @@
+"""The pch script must reach PlatformIO builds only; the native ESP-IDF
+toolchain has its own pch flow in build_gen/espidf.py."""
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from esphome.components import esp32
+from esphome.const import Toolchain
+from esphome.core import CORE
+
+
+@pytest.mark.parametrize(
+    ("toolchain", "copied"),
+    [(Toolchain.PLATFORMIO, True), (Toolchain.ESP_IDF, False)],
+)
+def test_copy_files_gates_pch_script_on_toolchain(
+    toolchain: Toolchain, copied: bool, tmp_path: Path
+) -> None:
+    CORE.toolchain = toolchain
+    CORE.build_path = tmp_path
+    from esphome.components.esp32 import (
+        KEY_ESP32,
+        KEY_EXTRA_BUILD_FILES,
+        KEY_FLASH_SIZE,
+    )
+
+    with (
+        patch.object(esp32, "_write_sdkconfig") as write_sdkconfig,
+        patch.object(esp32, "_write_idf_component_yml"),
+        patch.object(esp32, "copy_pch_script") as copy_script,
+        patch.object(esp32, "write_file_if_changed"),
+        patch.object(esp32, "get_partition_csv"),
+        patch.dict(
+            CORE.data,
+            {KEY_ESP32: {KEY_EXTRA_BUILD_FILES: {}, KEY_FLASH_SIZE: "4MB"}},
+        ),
+    ):
+        esp32.copy_files()
+    # Proves execution reached (and passed) the gate on both rows
+    assert write_sdkconfig.called
+    assert copy_script.called is copied

tests/unit_tests/components/nrf52/test_pch.py

@@ -0,0 +1,322 @@
+"""nrf52 sdk-nrf pch wiring: the CMake consumer block, the prepare wrapper,
+and the two-phase west split in run_compile."""
+
+from collections.abc import Generator
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+import pytest
+
+from esphome.components import nrf52
+from esphome.components.zephyr.const import KEY_BOARD
+from esphome.const import KEY_CORE, KEY_FRAMEWORK_VERSION, Toolchain
+from esphome.core import CORE, EsphomeError
+
+
+@pytest.fixture(autouse=True)
+def pch_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("ESPHOME_PCH_ENABLE", raising=False)
+    monkeypatch.delenv("ESPHOME_PCH_STRICT", raising=False)
+
+
+@pytest.fixture
+def build_dir(tmp_path: Path) -> Path:
+    d = tmp_path / "build" / ".pioenvs" / "livingroom"
+    d.mkdir(parents=True)
+    return d
+
+
+_AUTOCONF_TEXT = "#define CONFIG_GPIO 1\n"
+
+
+def _write_autoconf(build_dir: Path) -> Path:
+    autoconf = build_dir / "zephyr" / "include" / "generated" / "zephyr" / "autoconf.h"
+    autoconf.parent.mkdir(parents=True)
+    autoconf.write_text(_AUTOCONF_TEXT)
+    return autoconf
+
+
+def test_prepare_pch_disabled_discards_and_degrades(
+    monkeypatch: pytest.MonkeyPatch, build_dir: Path
+) -> None:
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+    gch = build_dir / "esphome_pch.h.gch"
+    gch.write_bytes(b"x")
+    nrf52._prepare_pch(build_dir)
+    assert not gch.exists()
+
+
+def test_prepare_pch_disabled_strict_raises(
+    monkeypatch: pytest.MonkeyPatch, build_dir: Path
+) -> None:
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    with pytest.raises(EsphomeError, match="ESPHOME_PCH_STRICT"):
+        nrf52._prepare_pch(build_dir)
+
+
+def test_prepare_pch_missing_autoconf_degrades(
+    build_dir: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    with patch.object(nrf52.pch, "prepare_pch") as prepare:
+        nrf52._prepare_pch(build_dir)
+    assert not prepare.called
+    assert "No autoconf.h found" in caplog.text
+    # The header is written first so OBJECT_DEPENDS stays satisfied
+    assert (build_dir / "esphome_pch.h").is_file()
+
+
+def test_prepare_pch_missing_autoconf_strict_raises(
+    monkeypatch: pytest.MonkeyPatch, build_dir: Path
+) -> None:
+    monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+    with pytest.raises(EsphomeError, match="autoconf.h missing"):
+        nrf52._prepare_pch(build_dir)
+
+
+def test_prepare_pch_unreadable_autoconf_fails_closed(
+    build_dir: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    # A directory named autoconf.h: read_text raises OSError
+    autoconf = build_dir / "zephyr" / "include" / "generated" / "autoconf.h"
+    autoconf.mkdir(parents=True)
+    with patch.object(nrf52.pch, "prepare_pch") as prepare:
+        nrf52._prepare_pch(build_dir)
+    assert not prepare.called
+    assert "Could not read" in caplog.text
+
+
+def test_app_build_dir_sysbuild_layout(build_dir: Path) -> None:
+    app = build_dir / "zephyr"
+    app.mkdir()
+    (app / "CMakeCache.txt").write_text("")
+    assert nrf52._app_build_dir(build_dir) == app
+
+
+def test_app_build_dir_top_level_layout(build_dir: Path) -> None:
+    # Non-sysbuild: build_dir/zephyr is the Zephyr output dir, no cache
+    (build_dir / "zephyr").mkdir()
+    assert nrf52._app_build_dir(build_dir) == build_dir
+
+
+def test_app_build_dir_ignores_cache_directory(build_dir: Path) -> None:
+    (build_dir / "zephyr" / "CMakeCache.txt").mkdir(parents=True)
+    assert nrf52._app_build_dir(build_dir) == build_dir
+
+
+def test_app_build_dir_propagates_stat_errors(build_dir: Path) -> None:
+    # is_file() would swallow this and mislocate the pch
+    with (
+        patch.object(Path, "stat", side_effect=PermissionError("denied")),
+        pytest.raises(PermissionError),
+    ):
+        nrf52._app_build_dir(build_dir)
+
+
+def test_prepare_pch_extras_carry_build_identity(build_dir: Path) -> None:
+    _write_autoconf(build_dir)
+    with (
+        patch.dict(CORE.data, {KEY_CORE: {KEY_FRAMEWORK_VERSION: "2.9.2"}}),
+        patch.object(
+            nrf52, "zephyr_data", return_value={KEY_BOARD: "adafruit_feather"}
+        ),
+        patch.object(nrf52, "get_project_compile_flags", return_value=["-Os"]),
+        patch.object(nrf52.pch, "prepare_pch") as prepare,
+    ):
+        nrf52._prepare_pch(build_dir)
+    assert (build_dir / "esphome_pch.h").is_file()
+    (passed_dir, headers, extras) = prepare.call_args.args
+    assert passed_dir == build_dir
+    assert headers == nrf52.PCH_DEFAULT_HEADERS
+    assert list(extras) == ["2.9.2", "adafruit_feather", _AUTOCONF_TEXT, "-Os"]
+
+
+def _generate_cmake(tmp_path: Path) -> str:
+    CORE.config_path = tmp_path / "test.yaml"
+    CORE.build_path = tmp_path / "build"
+    CORE.name = "livingroom"
+    with (
+        patch(
+            "esphome.components.zephyr.library.generate_zephyr_modules",
+            return_value=[],
+        ),
+        patch.object(nrf52, "get_project_compile_flags", return_value=["-Os"]),
+        patch.object(nrf52, "get_project_link_flags", return_value=[]),
+    ):
+        nrf52._generate_cmake_lists()
+    return (tmp_path / "build" / "zephyr" / "CMakeLists.txt").read_text()
+
+
+def test_cmake_lists_include_pch_consumer_block(tmp_path: Path) -> None:
+    # Content contract is pinned by the shared pch_cmake_consumer tests;
+    # here only that the block reaches the generated CMakeLists
+    text = _generate_cmake(tmp_path)
+    assert "target_compile_options(app PRIVATE" in text
+    assert 'OBJECT_DEPENDS "${CMAKE_BINARY_DIR}/esphome_pch.h"' in text
+
+
+def test_cmake_lists_pch_block_disabled(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+    assert "esphome_pch.h" not in _generate_cmake(tmp_path)
+
+
+CompileCtx = tuple[Mock, Mock, Path]
+
+
+class TestRunCompilePhases:
+    """The pch pre-build block in run_compile: header write, conditional
+    cmake-only phase, and the never-abort-the-build exception contract."""
+
+    @pytest.fixture
+    def compile_ctx(self, tmp_path: Path) -> Generator[CompileCtx, None, None]:
+        CORE.config_path = tmp_path / "test.yaml"
+        CORE.build_path = tmp_path / "build"
+        CORE.name = "livingroom"
+        CORE.toolchain = Toolchain.SDK_NRF
+        with (
+            patch.object(nrf52, "check_and_install"),
+            patch.object(nrf52, "_generate_cmake_lists", return_value=False),
+            patch.object(
+                nrf52,
+                "get_build_paths",
+                return_value={
+                    "python_executable": "python3",
+                    "framework_path": tmp_path,
+                },
+            ),
+            patch.object(nrf52, "get_build_env", return_value={}),
+            patch.object(nrf52, "zephyr_data", return_value={KEY_BOARD: "board"}),
+            patch.object(nrf52, "run_command_ok") as run_cmd,
+            patch.object(nrf52, "_prepare_pch") as prepare,
+        ):
+            yield run_cmd, prepare, CORE.relative_pioenvs_path(CORE.name)
+
+    def _run(self) -> None:
+        nrf52.run_compile(None, {})
+
+    def test_missing_db_runs_cmake_phase(self, compile_ctx: CompileCtx) -> None:
+        run_cmd, prepare, build_dir = compile_ctx
+        # cmake-only ok, generated headers ok, final build fails
+        results = iter([True, True, False])
+
+        def west(cmd, **kwargs):
+            # Phase 1 configures the sysbuild app domain
+            app = build_dir / "zephyr"
+            app.mkdir(parents=True, exist_ok=True)
+            (app / "CMakeCache.txt").write_text("")
+            return next(results)
+
+        run_cmd.side_effect = west
+        with pytest.raises(EsphomeError, match="nRF52 native build failed"):
+            self._run()
+        assert "--cmake-only" in run_cmd.call_args_list[0].args[0]
+        # Generated syscall headers are built in the app domain pre-pch
+        headers_cmd = run_cmd.call_args_list[1].args[0]
+        assert headers_cmd[:2] == ["cmake", "--build"]
+        assert str(build_dir / "zephyr") in headers_cmd
+        assert "zephyr_generated_headers" in headers_cmd
+        assert "--cmake-only" not in run_cmd.call_args_list[2].args[0]
+        # The pch is prepared in the app domain dir, not the sysbuild root
+        assert prepare.call_args.args[0] == build_dir / "zephyr"
+
+    def test_generated_headers_failure_degrades(
+        self, compile_ctx, caplog: pytest.LogCaptureFixture
+    ) -> None:
+        run_cmd, prepare, _ = compile_ctx
+        # headers target fails, the real build still runs (and fails here)
+        run_cmd.side_effect = [True, False, False]
+        with pytest.raises(EsphomeError, match="nRF52 native build failed"):
+            self._run()
+        assert "Zephyr header generation failed" in caplog.text
+        # The doomed .gch compile is skipped: it would latch .gch.failed
+        assert not prepare.called
+
+    def test_generated_headers_failure_strict_raises(
+        self, monkeypatch: pytest.MonkeyPatch, compile_ctx: CompileCtx
+    ) -> None:
+        monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+        run_cmd, prepare, _ = compile_ctx
+        run_cmd.side_effect = [True, False]
+        with pytest.raises(EsphomeError, match="ESPHOME_PCH_STRICT"):
+            self._run()
+        assert not prepare.called
+
+    def test_cmake_phase_failure_raises(self, compile_ctx: CompileCtx) -> None:
+        run_cmd, prepare, _ = compile_ctx
+        run_cmd.side_effect = [False]
+        with pytest.raises(EsphomeError, match="configure failed"):
+            self._run()
+        assert not prepare.called
+
+    def test_ccache_pch_env_reaches_west(self, compile_ctx: CompileCtx) -> None:
+        run_cmd, _, _ = compile_ctx
+        run_cmd.side_effect = [False]
+        # clear=True also drops ambient CCACHE_*/ESPHOME_PCH_* overrides
+        with (
+            patch.dict("os.environ", {}, clear=True),
+            pytest.raises(EsphomeError, match="configure failed"),
+        ):
+            self._run()
+        env = run_cmd.call_args.kwargs["env"]
+        assert env["CCACHE_PCH_EXTSUM"] == "true"
+        assert env["CCACHE_SLOPPINESS"] == "pch_defines,time_macros"
+
+    @pytest.mark.parametrize("sysbuild", [False, True])
+    def test_settled_db_skips_cmake_phase(
+        self, sysbuild: bool, compile_ctx: CompileCtx
+    ) -> None:
+        run_cmd, prepare, build_dir = compile_ctx
+        app = build_dir / "zephyr" if sysbuild else build_dir
+        app.mkdir(parents=True)
+        # A present top-level cache keeps the pristine wipe from dropping
+        # the DB; the app-dir cache is the sysbuild layout marker
+        (build_dir / "CMakeCache.txt").write_text("")
+        (app / "CMakeCache.txt").write_text("")
+        (app / "compile_commands.json").write_text("[]")
+        run_cmd.side_effect = [False]
+        with pytest.raises(EsphomeError, match="nRF52 native build failed"):
+            self._run()
+        assert run_cmd.call_count == 1
+        assert "--cmake-only" not in run_cmd.call_args.args[0]
+        assert prepare.call_args.args[0] == app
+
+    def test_disabled_skips_header_and_cmake_phase(
+        self, monkeypatch: pytest.MonkeyPatch, compile_ctx: CompileCtx
+    ) -> None:
+        monkeypatch.setenv("ESPHOME_PCH_ENABLE", "0")
+        run_cmd, prepare, build_dir = compile_ctx
+        run_cmd.side_effect = [False]
+        with pytest.raises(EsphomeError, match="nRF52 native build failed"):
+            self._run()
+        assert run_cmd.call_count == 1
+        assert not (build_dir / "esphome_pch.h").exists()
+        # The wrapper still runs: it discards stale sidecars and feeds strict
+        assert prepare.called
+
+    def test_prepare_failure_never_aborts_the_build(
+        self, compile_ctx, caplog: pytest.LogCaptureFixture
+    ) -> None:
+        run_cmd, prepare, build_dir = compile_ctx
+        build_dir.mkdir(parents=True)
+        # Keep the pristine wipe from dropping the dir the fallback touches
+        (build_dir / "CMakeCache.txt").write_text("")
+        prepare.side_effect = RuntimeError("boom")
+        run_cmd.side_effect = [True, True, False]
+        with pytest.raises(EsphomeError, match="nRF52 native build failed"):
+            self._run()
+        assert run_cmd.call_count == 3
+        assert "Precompiled header setup failed" in caplog.text
+        # The fallback still satisfies OBJECT_DEPENDS
+        assert (build_dir / "esphome_pch.h").is_file()
+
+    def test_prepare_failure_strict_raises(
+        self, monkeypatch: pytest.MonkeyPatch, compile_ctx: CompileCtx
+    ) -> None:
+        monkeypatch.setenv("ESPHOME_PCH_STRICT", "1")
+        run_cmd, prepare, _ = compile_ctx
+        prepare.side_effect = RuntimeError("boom")
+        run_cmd.side_effect = [True, True]
+        with pytest.raises(RuntimeError, match="boom"):
+            self._run()

tests/unit_tests/test_core.py

@@ -568,6 +568,16 @@ class TestEsphomeCore:
         target.config_path = Path("foo/config")
         return target
 
+    def test_add_platformio_option_merges_string_into_list(self, target) -> None:
+        """A user platformio_options string lands after a component's list
+        (FINAL priority) and must merge as one element, not assert."""
+        target.add_platformio_option("extra_scripts", ["post:pch.py"])
+        target.add_platformio_option("extra_scripts", "pre:mine.py")
+        assert target.platformio_options["extra_scripts"] == [
+            "post:pch.py",
+            "pre:mine.py",
+        ]
+
     def test_reset(self, target):
         """Call reset on target and compare to new instance"""
         other = core.EsphomeCore().__dict__

tests/unit_tests/test_espidf_toolchain.py

@@ -669,6 +669,52 @@ def test_get_core_framework_version_from_core_data():
     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_helpers.pch.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:

tests/unit_tests/test_pch_prefix.py

@@ -0,0 +1,21 @@
+"""The 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.build_helpers.pch import PCH_PREFIX_HEADER
+
+REPO = Path(__file__).parents[2]
+
+
+def test_pch_prefix_resolves() -> None:
+    prefix = REPO / PCH_PREFIX_HEADER
+    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

@@ -100,12 +100,14 @@ def _fake_cxx(
         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\nfor a in "$@"; do [ "$prev" = "-o" ] && out="$a"; prev="$a"; [ "$a" = "-MF" ] && mf=1; case "$a" in -M|-MM|-MD|-MMD) dep=1;; esac; done\n'
+        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:
-            body += 'case " $* " in *c++-header*) ;; *) echo "warning: esphome_pch.h.gch: had text segment at different address" >&2;; esac\n'
+            # -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)
@@ -293,13 +295,17 @@ def test_pch_script_spawn_failure_is_transient(
     assert "did not run" in capsys.readouterr().out
 
 
-def test_pch_script_probe_nonzero_exit_falls_back(tmp_path: Path) -> None:
-    """A probe failure whose stderr never mentions .gch must still count."""
+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:
@@ -458,3 +464,118 @@ def test_pch_script_unreadable_local_header_skips_pch(
     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