prefect-client 3.8.8.dev4__tar.gz → 3.8.9.dev1__tar.gz

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prefect-client
-Version: 3.8.8.dev4
+Version: 3.8.9.dev1
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io
@@ -14,13 +14,12 @@ Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: <3.15,>=3.10
+Requires-Python: <3.15,>=3.11
 Requires-Dist: amplitude-analytics<2.0.0,>=1.2.1
 Requires-Dist: anyio<5.0.0,>=4.4.0
 Requires-Dist: asgi-lifespan<3.0,>=1.0
@@ -95,7 +94,7 @@ or other resource-constrained environments.
 
 ## Getting started
 
-`prefect-client` shares the same installation requirements as prefect. To install, make sure you are on Python 3.10 or
+`prefect-client` shares the same installation requirements as prefect. To install, make sure you are on Python 3.11 or
 later and run the following command:
 
 ```bash

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/README.md

@@ -26,7 +26,7 @@ or other resource-constrained environments.
 
 ## Getting started
 
-`prefect-client` shares the same installation requirements as prefect. To install, make sure you are on Python 3.10 or
+`prefect-client` shares the same installation requirements as prefect. To install, make sure you are on Python 3.11 or
 later and run the following command:
 
 ```bash

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/pyproject.toml

@@ -7,7 +7,7 @@ name = "prefect-client"
 dynamic = ["version"]
 description = "Workflow orchestration and management."
 readme = "README.md"
-requires-python = ">=3.10,<3.15"
+requires-python = ">=3.11,<3.15"
 license = { text = "Apache-2.0" }
 authors = [{ name = "Prefect Technologies, Inc.", email = "help@prefect.io" }]
 classifiers = [
@@ -16,7 +16,6 @@ classifiers = [
     "Intended Audience :: System Administrators",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/__init__.py

@@ -2,7 +2,6 @@
 
 # Setup version and path constants
 
-import sys
 from . import _build_info
 import importlib
 import pathlib
@@ -212,8 +211,9 @@ def __getattr__(attr_name: str) -> Any:
             return getattr(module, attr_name)
     except ModuleNotFoundError as ex:
         mname, _, attr = (ex.name or "").rpartition(".")
-        ctx = {"name": mname, "obj": attr} if sys.version_info >= (3, 10) else {}
-        raise AttributeError(f"module {mname} has no attribute {attr}", **ctx) from ex
+        raise AttributeError(
+            f"module {mname} has no attribute {attr}", name=mname, obj=attr
+        ) from ex
 
 
 # Initialize plugins on import if enabled

prefect_client-3.8.9.dev1/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.8.9.dev1"
+__build_date__ = "2026-10-07 08:22:05.387495+00:00"
+__git_commit__ = "6c7fefcb8729546e9a7b5b63e310669370348106"
+__dirty__ = False

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/_internal/_logging.py

@@ -1,14 +1,8 @@
 import logging
-import sys
 
 from typing_extensions import Self
 
-if sys.version_info < (3, 11):
-
-    def getLevelNamesMapping() -> dict[str, int]:
-        return getattr(logging, "_nameToLevel").copy()
-else:
-    getLevelNamesMapping = logging.getLevelNamesMapping  # novermin
+getLevelNamesMapping = logging.getLevelNamesMapping
 
 
 class SafeLogger(logging.Logger):

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/_internal/plugins/collections.py

@@ -8,6 +8,7 @@ typically to register Blocks or other Prefect-aware classes.
 Public API is re-exported from `prefect.plugins`.
 """
 
+import importlib
 from importlib.metadata import EntryPoints, entry_points
 from types import ModuleType
 from typing import Any, Union
@@ -40,26 +41,45 @@ def safe_load_entrypoints(entrypoints: EntryPoints) -> dict[str, Union[Exception
     return results
 
 
-def load_prefect_collections() -> dict[str, Union[ModuleType, Exception]]:
+def load_prefect_collections(
+    reload: bool = False,
+) -> dict[str, Union[ModuleType, Exception]]:
     """
     Load all Prefect collections that define an entrypoint in the group
     `prefect.collections`.
+
+    Results are cached. With `reload=True`, import and metadata caches are
+    invalidated and entry points that are new or failed on a previous call are
+    loaded, so packages installed or repaired after the first call are picked up.
     """
     global _collections
 
-    if _collections is not None:
+    if _collections is not None and not reload:
         return _collections
 
+    if _collections is not None:
+        importlib.invalidate_caches()
+
     collection_entrypoints: EntryPoints = entry_points(group="prefect.collections")
-    collections: dict[str, Union[Exception, Any]] = safe_load_entrypoints(
+    if _collections is not None:
+        known = {
+            name
+            for name, result in _collections.items()
+            if not isinstance(result, Exception)
+        }
+        collection_entrypoints = EntryPoints(
+            ep for ep in collection_entrypoints if (ep.name or ep.value) not in known
+        )
+    loaded: dict[str, Union[Exception, Any]] = safe_load_entrypoints(
         collection_entrypoints
     )
+    collections = {**_collections, **loaded} if _collections is not None else loaded
 
     # TODO: Consider the utility of this once we've established this pattern.
     #       We cannot use a logger here because logging is not yet initialized.
     #       It would be nice if logging was initialized so we could log failures
     #       at least.
-    for name, result in collections.items():
+    for name, result in loaded.items():
         if isinstance(result, Exception):
             print(
                 # TODO: Use exc_info if we have a logger

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/_internal/plugins/manager.py

@@ -7,7 +7,6 @@ from __future__ import annotations
 import importlib.metadata as md
 import inspect
 import logging
-import sys
 from typing import Any
 
 import pluggy
@@ -55,12 +54,7 @@ def load_entry_point_plugins(
         deny: If set, skip plugins with names in this set
         logger: Logger for reporting load failures
     """
-    # Python 3.10+ supports group parameter, 3.9 requires dict access
-    if sys.version_info >= (3, 10):
-        entry_points_list = md.entry_points(group=ENTRYPOINTS_GROUP)
-    else:
-        # Python 3.9 returns a dict-like object
-        entry_points_list = md.entry_points().get(ENTRYPOINTS_GROUP, [])
+    entry_points_list = md.entry_points(group=ENTRYPOINTS_GROUP)
 
     for ep in entry_points_list:
         if allow and ep.name not in allow:

prefect_client-3.8.9.dev1/src/prefect/_internal/server_maintenance.py

@@ -0,0 +1,46 @@
+"""
+Process-wide record of requests waiting out Prefect API maintenance.
+
+When the API answers with a `Prefect-Maintenance: true` header, the HTTP clients
+retry indefinitely, sleeping for the `Retry-After` they were given. Health checks
+read this record so that a process deliberately waiting is not reported as stuck.
+"""
+
+import datetime
+import threading
+
+import prefect.types._datetime
+
+_backoff_ends_at: datetime.datetime | None = None
+_backoff_lock = threading.Lock()
+
+
+def record_maintenance_backoff(retry_seconds: float) -> None:
+    """
+    Record that a request is sleeping for `retry_seconds` before retrying a
+    maintenance response.
+    """
+    global _backoff_ends_at
+    ends_at = prefect.types._datetime.now("UTC") + datetime.timedelta(
+        seconds=retry_seconds
+    )
+    with _backoff_lock:
+        # Concurrent requests each back off; the latest end wins.
+        if _backoff_ends_at is None or ends_at > _backoff_ends_at:
+            _backoff_ends_at = ends_at
+
+
+def maintenance_backoff_ends_at() -> datetime.datetime | None:
+    """
+    When the latest maintenance back-off in this process ends, or `None` if no
+    request has backed off for maintenance.
+    """
+    with _backoff_lock:
+        return _backoff_ends_at
+
+
+def reset_maintenance_backoff() -> None:
+    """Forget any recorded maintenance back-off (for tests)."""
+    global _backoff_ends_at
+    with _backoff_lock:
+        _backoff_ends_at = None

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/blocks/core.py

@@ -81,10 +81,7 @@ R = TypeVar("R")
 P = ParamSpec("P")
 
 ResourceTuple = tuple[dict[str, Any], list[dict[str, Any]]]
-UnionTypes: tuple[object, ...] = (Union,)
-if hasattr(types, "UnionType"):
-    # Python 3.10+ only
-    UnionTypes = (*UnionTypes, types.UnionType)
+UnionTypes: tuple[object, ...] = (Union, types.UnionType)
 
 
 def _nested_type_args(annotation: Any) -> tuple[Any, ...]:

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/bundles/__init__.py

@@ -174,15 +174,11 @@ def _is_local_module(module_name: str, module_path: str | None = None) -> bool:
     if module_name in sys.builtin_module_names:
         return False
 
-    # Check if it's in the standard library (Python 3.10+)
-    if hasattr(sys, "stdlib_module_names"):
-        # Check both full module name and base module name
-        base_module = module_name.split(".")[0]
-        if (
-            module_name in sys.stdlib_module_names
-            or base_module in sys.stdlib_module_names
-        ):
-            return False
+    # Check if it's in the standard library
+    # Check both full module name and base module name
+    base_module = module_name.split(".")[0]
+    if module_name in sys.stdlib_module_names or base_module in sys.stdlib_module_names:
+        return False
 
     # If we have the module path, check if it's in site-packages or dist-packages
     if module_path:

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/client/base.py

@@ -20,6 +20,7 @@ from typing_extensions import Self
 
 import prefect
 from prefect._internal.compatibility.starlette import status
+from prefect._internal.server_maintenance import record_maintenance_backoff
 from prefect.client import constants
 from prefect.client.attribution import get_attribution_headers
 from prefect.client.schemas.objects import CsrfToken
@@ -46,6 +47,20 @@ APP_LIFESPANS_REF_COUNTS: dict[tuple[int, int], int] = {}
 APP_LIFESPANS_LOCKS: dict[int, anyio.Lock] = defaultdict(anyio.Lock)
 
 
+def _record_if_maintenance_backoff(
+    response: Optional[Response],
+    exc_info: Optional[tuple[Any, ...]],
+    retry_seconds: float,
+) -> None:
+    # After a retryable exception, `response` is still the previous attempt's.
+    if (
+        exc_info is None
+        and response is not None
+        and response.headers.get("Prefect-Maintenance") == "true"
+    ):
+        record_maintenance_backoff(retry_seconds)
+
+
 logger: Logger = get_logger("client")
 
 
@@ -356,6 +371,7 @@ class PrefectHttpxAsyncClient(httpx.AsyncClient):
                 f" {try_count}/{PREFECT_CLIENT_MAX_RETRIES.value() + 1}.",
                 exc_info=exc_info,
             )
+            _record_if_maintenance_backoff(response, exc_info, retry_seconds)
             await anyio.sleep(retry_seconds)
 
         assert response is not None, (
@@ -628,6 +644,7 @@ class PrefectHttpxSyncClient(httpx.Client):
                 f" {try_count}/{PREFECT_CLIENT_MAX_RETRIES.value() + 1}.",
                 exc_info=exc_info,
             )
+            _record_if_maintenance_backoff(response, exc_info, retry_seconds)
             time.sleep(retry_seconds)
 
         assert response is not None, (

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/client/schemas/__init__.py

@@ -1,5 +1,4 @@
 import importlib
-import sys
 from typing import Any, TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -90,5 +89,6 @@ def __getattr__(attr_name: str) -> Any:
         return getattr(module, attr_name)
     except ModuleNotFoundError as ex:
         mname, _, attr = (ex.name or "").rpartition(".")
-        ctx = {"name": mname, "obj": attr} if sys.version_info >= (3, 10) else {}
-        raise AttributeError(f"module {mname} has no attribute {attr}", **ctx) from ex
+        raise AttributeError(
+            f"module {mname} has no attribute {attr}", name=mname, obj=attr
+        ) from ex

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/filesystems.py

@@ -191,13 +191,15 @@ class LocalFileSystem(WritableFileSystem, WritableDeploymentStorage):
             with open(from_path / Path(".prefectignore")) as f:
                 ignore_patterns = f.readlines()
             included_files = filter_files(
-                root=from_path, ignore_patterns=ignore_patterns
+                root=from_path, ignore_patterns=ignore_patterns, as_posix=True
             )
 
             def ignore_func(directory, files):
                 relative_path = Path(directory).relative_to(from_path)
                 files_to_ignore = [
-                    f for f in files if str(relative_path / f) not in included_files
+                    f
+                    for f in files
+                    if (relative_path / f).as_posix() not in included_files
                 ]
                 return files_to_ignore
         else:
@@ -210,13 +212,15 @@ class LocalFileSystem(WritableFileSystem, WritableDeploymentStorage):
     async def _get_ignore_func(self, local_path: str, ignore_file: str):
         with open(ignore_file) as f:
             ignore_patterns = f.readlines()
-        included_files = filter_files(root=local_path, ignore_patterns=ignore_patterns)
+        included_files = filter_files(
+            root=local_path, ignore_patterns=ignore_patterns, as_posix=True
+        )
 
         def ignore_func(directory, files):
             relative_path = Path(directory).relative_to(local_path)
 
             files_to_ignore = [
-                f for f in files if str(relative_path / f) not in included_files
+                f for f in files if (relative_path / f).as_posix() not in included_files
             ]
             return files_to_ignore
 
@@ -278,13 +282,15 @@ class LocalFileSystem(WritableFileSystem, WritableDeploymentStorage):
             with open(ignore_file) as f:
                 ignore_patterns = f.readlines()
             included_files = filter_files(
-                root=local_path, ignore_patterns=ignore_patterns
+                root=local_path, ignore_patterns=ignore_patterns, as_posix=True
             )
 
             def ignore_func(directory, files):
                 relative_path = Path(directory).relative_to(local_path)
                 files_to_ignore = [
-                    f for f in files if str(relative_path / f) not in included_files
+                    f
+                    for f in files
+                    if (relative_path / f).as_posix() not in included_files
                 ]
                 return files_to_ignore
         else:
@@ -539,13 +545,13 @@ class RemoteFileSystem(WritableFileSystem, WritableDeploymentStorage):
                 ignore_patterns = f.readlines()
 
             included_files = filter_files(
-                local_path, ignore_patterns, include_dirs=True
+                local_path, ignore_patterns, include_dirs=True, as_posix=True
             )
 
         counter = 0
         for f in Path(local_path).rglob("*"):
             relative_path = f.relative_to(local_path)
-            if included_files and str(relative_path) not in included_files:
+            if included_files and relative_path.as_posix() not in included_files:
                 continue
 
             if to_path.endswith("/"):
@@ -595,13 +601,13 @@ class RemoteFileSystem(WritableFileSystem, WritableDeploymentStorage):
                 ignore_patterns = f.readlines()
 
             included_files = filter_files(
-                local_path, ignore_patterns, include_dirs=True
+                local_path, ignore_patterns, include_dirs=True, as_posix=True
             )
 
         counter = 0
         for f in Path(local_path).rglob("*"):
             relative_path = f.relative_to(local_path)
-            if included_files and str(relative_path) not in included_files:
+            if included_files and relative_path.as_posix() not in included_files:
                 continue
 
             if to_path.endswith("/"):

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/logging/formatters.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import logging
-import sys
 import traceback
 from types import TracebackType
 from typing import Any, Literal, Optional, Tuple, Type, Union
@@ -119,10 +118,8 @@ class PrefectFormatter(logging.Formatter):
         init_kwargs: dict[str, Any] = {}
         style_kwargs: dict[str, Any] = {}
 
-        # defaults added in 3.10
-        if sys.version_info >= (3, 10):
-            init_kwargs["defaults"] = defaults
-            style_kwargs["defaults"] = defaults
+        init_kwargs["defaults"] = defaults
+        style_kwargs["defaults"] = defaults
 
         init_kwargs["validate"] = validate
 

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/logging/loggers.py

@@ -380,11 +380,7 @@ def print_as_log(*args: Any, **kwargs: Any) -> None:
 
     msg = buffer.getvalue().rstrip()
 
-    if isinstance(logger, logging.LoggerAdapter) and sys.version_info < (3, 11):
-        if logger.isEnabledFor(logging.INFO):
-            logger.logger._log(logging.INFO, msg, (), extra=logger.extra, stacklevel=1)
-    else:
-        logger.info(msg, stacklevel=2)
+    logger.info(msg, stacklevel=2)
 
 
 @contextmanager

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/utilities/callables/__init__.py

@@ -492,7 +492,7 @@ def parameter_schema(fn: Callable[..., Any]) -> ParameterSchema:
     try:
         signature = inspect.signature(fn, eval_str=True)  # novm
     except (NameError, TypeError):
-        # `eval_str` is not available in Python < 3.10
+        # Some annotations can't be resolved (e.g. defined under TYPE_CHECKING)
         signature = inspect.signature(fn)
 
     docstrings = parameter_docstrings(inspect.getdoc(fn))

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/utilities/filesystem/AGENTS.md

@@ -8,7 +8,7 @@ Path normalization, file filtering compatible with `.gitignore`/`.prefectignore`
 
 ## Entry Points
 
-- `filter_files(root, ignore_patterns, include_dirs=True) -> set[str]` — return the set of paths under `root` that should be *ignored* according to pathspec patterns. Intended as input to `shutil.copytree`'s `ignore` callback.
+- `filter_files(root, ignore_patterns, include_dirs=True, *, as_posix=False) -> set[str]` — return the set of included paths under `root` according to pathspec patterns. Returned paths are relative to `root` and use platform-native separators by default. Callers comparing against `Path.as_posix()` must opt in with `as_posix=True`. Used to build `shutil.copytree`'s `ignore` callback.
 - `tmpchdir(path)` — context manager that `chdir`s into `path` and restores the previous cwd on exit.
 - `get_open_file_limit() -> int` — platform-specific maximum open-file count, with a conservative Windows default.
 

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/utilities/filesystem/__init__.py

@@ -38,12 +38,19 @@ def filter_files(
     root: str = ".",
     ignore_patterns: Optional[Iterable[AnyStr]] = None,
     include_dirs: bool = True,
+    *,
+    as_posix: bool = False,
 ) -> set[str]:
     """
     This function accepts a root directory path and a list of file patterns to ignore, and returns
-    a list of files that excludes those that should be ignored.
+    a set of paths that excludes those that should be ignored.
 
     The specification matches that of [.gitignore files](https://git-scm.com/docs/gitignore).
+
+    Returned paths are relative to `root` and use platform-native separators
+    by default. Set `as_posix=True` to return forward-slash-separated paths.
+    When `include_dirs=True`, ancestor directories of included files are also
+    included so directory traversal can reach those files.
     """
     spec = pathspec.GitIgnoreSpec.from_lines(ignore_patterns or [])
     ignored_files = {p.path for p in spec.match_tree_entries(root)}
@@ -66,6 +73,8 @@ def filter_files(
                 parent_dirs.add(parent_str)
         included_files |= parent_dirs
 
+    if as_posix:
+        return {Path(path).as_posix() for path in included_files}
     return included_files
 
 

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/workers/AGENTS.md

@@ -48,6 +48,7 @@ Work-pool-level launchers are configured via `prefect work-pool storage configur
 ## Pitfalls
 
 - `backend_id` is `None` until the first heartbeat succeeds; `PREFECT__WORKER_ID` is not set until then. Code that reads `self.backend_id` early in the lifecycle may get `None`.
+- Requests answered with `Prefect-Maintenance: true` retry indefinitely, so any API call can block for an entire Cloud maintenance window. Worker health must be served before the first API call and must not count that wait as a missed poll (`_is_within_polling_window()` handles this).
 - Direct `ProcessWorker.run()` execution uses `FlowRunExecutorContext` with `propose_submitting=False` because `BaseWorker` already proposed Submitting. Generated commands use `WorkspaceResolvingEngineCommandStarter` and pass its `hook_runner`; explicitly configured commands use `EngineCommandStarter` and retain their own pull-step behavior. Consume the executor's normalized infrastructure status rather than the raw child exit code. The ad hoc bundle path still uses deprecated `Runner.execute_bundle()` and remains a migration gap (see `runner/AGENTS.md`).
 
 ## Related

{prefect_client-3.8.8.dev4 → prefect_client-3.8.9.dev1}/src/prefect/workers/base.py

@@ -6,10 +6,9 @@ import copy
 import datetime
 import logging
 import os
-import threading
 import uuid
 import warnings
-from contextlib import AsyncExitStack
+from contextlib import AsyncExitStack, ExitStack
 from functools import partial
 from importlib.metadata import distributions
 from typing import (
@@ -39,6 +38,7 @@ from prefect._internal.infrastructure_exit_codes import get_infrastructure_exit_
 from prefect._internal.launchers import resolve_bundle_step_with_launcher
 from prefect._internal.observers import FlowRunCancellingObserver
 from prefect._internal.schemas.validators import return_v_or_none
+from prefect._internal.server_maintenance import maintenance_backoff_ends_at
 from prefect.client.orchestration import PrefectClient, get_client
 from prefect.client.schemas.objects import Flow as APIFlow
 from prefect.client.schemas.objects import (
@@ -126,6 +126,28 @@ def _is_transient_api_error(exc: httpx.HTTPError) -> bool:
     return isinstance(exc, httpx.TransportError)
 
 
+def _is_within_polling_window(
+    last_polled_time: datetime.datetime, query_interval_seconds: float
+) -> bool:
+    """
+    Whether a worker that last polled at `last_polled_time` is within its
+    polling window of `query_interval_seconds` x 30.
+
+    While the Prefect API is in maintenance, requests wait out the `Retry-After`
+    it sends, so the window counts from the later of `last_polled_time` and the
+    end of the latest maintenance back-off.
+    """
+    window_start = last_polled_time
+    backoff_ends_at = maintenance_backoff_ends_at()
+    if backoff_ends_at is not None and backoff_ends_at > window_start:
+        window_start = backoff_ends_at
+
+    seconds_since_window_start = (
+        prefect.types._datetime.now("UTC") - window_start
+    ).total_seconds()
+    return seconds_since_window_start <= query_interval_seconds * 30
+
+
 class BaseJobConfiguration(BaseModel):
     command: Optional[str] = Field(
         default=None,
@@ -843,9 +865,25 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
             with_healthcheck: If set, the worker will start a healthcheck server.
             printer: A `print`-like function where logs will be reported.
         """
-        healthcheck_server = None
-        healthcheck_thread = None
+        healthcheck_stack = ExitStack()
         try:
+            if with_healthcheck:
+                from prefect.workers.server import (
+                    _run_healthcheck_server,  # pyright: ignore[reportPrivateUsage]
+                )
+
+                # Started before setup, which syncs with the API: while the API is
+                # in maintenance that sync waits, and the healthcheck must still
+                # answer.
+                query_interval_seconds = PREFECT_WORKER_QUERY_SECONDS.value()
+                healthcheck_stack.enter_context(
+                    _run_healthcheck_server(
+                        lambda: self.is_worker_still_polling(
+                            query_interval_seconds=query_interval_seconds
+                        )
+                    )
+                )
+
             async with self as worker:
                 polling_service = partial(
                     critical_service_loop,
@@ -882,21 +920,6 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
 
                     start_client_metrics_server()
 
-                    if with_healthcheck:
-                        from prefect.workers.server import build_healthcheck_server
-
-                        # we'll start the ASGI server in a separate thread so that
-                        # uvicorn does not block the main thread
-                        healthcheck_server = build_healthcheck_server(
-                            worker=worker,
-                            query_interval_seconds=PREFECT_WORKER_QUERY_SECONDS.value(),
-                        )
-                        healthcheck_thread = threading.Thread(
-                            name="healthcheck-server-thread",
-                            target=healthcheck_server.run,
-                            daemon=True,
-                        )
-                        healthcheck_thread.start()
                     printer(f"Worker {worker.name!r} started!")
 
                 # If running once, wait for active runs to finish before teardown
@@ -910,12 +933,7 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
                         await anyio.sleep(0.1)
         finally:
             stop_client_metrics_server()
-
-            if healthcheck_server and healthcheck_thread:
-                self._logger.debug("Stopping healthcheck server...")
-                healthcheck_server.should_exit = True
-                healthcheck_thread.join()
-                self._logger.debug("Healthcheck server stopped.")
+            healthcheck_stack.close()
 
         printer(f"Worker {worker.name!r} stopped!")
 
@@ -1294,18 +1312,21 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
         the loop services - we will evaluate if the _last_polled_time
         was within that interval x 30 (so 10s -> 5m)
 
+        While the Prefect API is in maintenance, requests wait out the
+        `Retry-After` it sends, so the window counts from the later of
+        `self._last_polled_time` and the end of the latest maintenance back-off.
+
         The instance property `self._last_polled_time`
         is currently set/updated in `get_and_submit_flow_runs()`
         """
-        threshold_seconds = query_interval_seconds * 30
-
-        seconds_since_last_poll = (
-            prefect.types._datetime.now("UTC") - self._last_polled_time
-        ).total_seconds()
-
-        is_still_polling = seconds_since_last_poll <= threshold_seconds
+        is_still_polling = _is_within_polling_window(
+            self._last_polled_time, query_interval_seconds
+        )
 
         if not is_still_polling:
+            seconds_since_last_poll = (
+                prefect.types._datetime.now("UTC") - self._last_polled_time
+            ).total_seconds()
             self._logger.error(
                 f"Worker has not polled in the last {seconds_since_last_poll} seconds "
                 "and should be restarted"