From 58d6bf2d61f872344b41e0949fe7ce8b1e2eeb35 Mon Sep 17 00:00:00 2001
From: SHT <1373636680@qq.com>
Date: Sun, 16 Aug 2026 08:13:20 +0800
Subject: [PATCH] fix(cron): log and document the .pth bootstrap fallback
 (#86816 review)

- WARN when the venv site-packages layout is unresolvable and the script
  falls back to plain PYTHONPATH execution, so 'editable installs
  invisible' failures are diagnosable.
- Docstring: note that runpy does not set __package__/__spec__ the way a
  direct python script.py invocation does.
---
 cron/scheduler.py | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/cron/scheduler.py b/cron/scheduler.py
index 94226a7d46..e7816502de 100644
--- a/cron/scheduler.py
+++ b/cron/scheduler.py
@@ -3124,12 +3124,22 @@ def _windows_cron_bootstrap_argv(
     Bootstrap with ``site.addsitedir()`` on the venv ``site-packages``, then
     exec the script as ``__main__``.  ``runpy.run_path`` keeps ``__file__``
     correct; ``sys.path[0]`` is set to the script's directory to preserve the
-    ``python script.py`` import semantics.  Falls back to a plain invocation
-    if the venv layout is unresolvable — the pre-existing PYTHONPATH
-    behaviour is strictly better than failing to run at all.
+    ``python script.py`` import semantics.  Note: ``runpy`` does not set
+    ``__package__``/``__spec__`` the way a direct invocation does, so
+    package-relative imports (``from . import x``) may behave differently.
+    Falls back to a plain invocation if the venv layout is unresolvable —
+    the pre-existing PYTHONPATH behaviour is strictly better than failing
+    to run at all.
     """
     site_packages = Path(env_overlay.get("VIRTUAL_ENV", "")) / "Lib" / "site-packages"
     if not site_packages.is_dir():
+        # Silent here would make the "editable installs invisible" failure
+        # undiagnosable; the pre-existing PYTHONPATH-only behaviour applies.
+        logger.warning(
+            "Windows cron script: venv site-packages %s not found; running "
+            "without .pth processing (editable installs may be unimportable)",
+            site_packages,
+        )
         return [python_exe, script_path]
     bootstrap = (
         "import os, runpy, site, sys;"