prefect-client 3.8.4.dev6__tar.gz → 3.8.5.dev1__tar.gz

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prefect-client
-Version: 3.8.4.dev6
+Version: 3.8.5.dev1
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io
@@ -64,7 +64,7 @@ Requires-Dist: uvicorn!=0.29.0,>=0.14.0
 Requires-Dist: websockets<17.0,>=15.0.1
 Requires-Dist: whenever<0.11.0,>=0.7.3; python_version >= '3.13'
 Provides-Extra: notifications
-Requires-Dist: apprise<2.0.0,>=1.1.0; extra == 'notifications'
+Requires-Dist: apprise<2.0.0,>=1.13.0; extra == 'notifications'
 Description-Content-Type: text/markdown
 
 <p align="center"><img src="https://github.com/PrefectHQ/prefect/assets/3407835/c654cbc6-63e8-4ada-a92a-efd2f8f24b85" width=1000></p>

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5.dev1}/pyproject.toml

@@ -74,7 +74,7 @@ Documentation = "https://docs.prefect.io"
 Source = "https://github.com/PrefectHQ/prefect"
 Tracker = "https://github.com/PrefectHQ/prefect/issues"
 [project.optional-dependencies]
-notifications = ["apprise>=1.1.0, <2.0.0"]
+notifications = ["apprise>=1.13.0, <2.0.0"]
 
 
 [tool.hatch.version]

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

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.8.5.dev1"
+__build_date__ = "2026-08-27 11:29:02.793270+00:00"
+__git_commit__ = "38041e65c47f7e3c350fce8f7e5c64de3bc1e103"
+__dirty__ = False

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5.dev1}/src/prefect/bundles/__init__.py

@@ -11,6 +11,7 @@ import logging
 import multiprocessing
 import multiprocessing.context
 import os
+import stat
 import subprocess
 import sys
 import tempfile
@@ -395,6 +396,41 @@ def _pickle_local_modules_by_value(flow: Flow[Any, Any]):
                 )
 
 
+def _resolve_include_files_base_dir(value: Path | str) -> Path:
+    """Resolve and validate an explicitly configured include-files base directory."""
+    try:
+        candidate = Path(value).expanduser()
+    except RuntimeError as exc:
+        raise ValueError(
+            f"Invalid include_files_base_dir {str(value)!r}: {exc}"
+        ) from exc
+
+    if not candidate.is_absolute():
+        candidate = Path.cwd() / candidate
+
+    try:
+        base_dir = candidate.resolve(strict=True)
+        if not stat.S_ISDIR(base_dir.stat().st_mode):
+            raise ValueError(
+                f"include_files_base_dir {str(value)!r} must be a directory."
+            )
+
+        # Open the directory to verify that collection can read it. `os.access` is
+        # not sufficient because its result can differ from the actual operation.
+        with os.scandir(base_dir):
+            pass
+    except FileNotFoundError as exc:
+        raise ValueError(
+            f"include_files_base_dir {str(value)!r} does not exist."
+        ) from exc
+    except NotADirectoryError as exc:
+        raise ValueError(
+            f"include_files_base_dir {str(value)!r} must be a directory."
+        ) from exc
+
+    return base_dir
+
+
 def create_bundle_for_flow_run(
     flow: Flow[Any, Any],
     flow_run: FlowRun,
@@ -463,12 +499,16 @@ def create_bundle_for_flow_run(
     files_key: str | None = None
     zip_path: Path | None = None
     include_files = getattr(flow, "include_files", None)
+    include_files_base_dir = getattr(flow, "include_files_base_dir", None)
 
     if include_files:
         try:
-            # Get base directory from flow file location
-            flow_file = Path(inspect.getfile(flow.fn))
-            base_dir = flow_file.parent.resolve()
+            if include_files_base_dir is None:
+                # Preserve the existing default relative to the flow definition.
+                flow_file = Path(inspect.getfile(flow.fn))
+                base_dir = flow_file.parent.resolve()
+            else:
+                base_dir = _resolve_include_files_base_dir(include_files_base_dir)
 
             # Pipeline: collect -> filter -> check -> zip
             collector = FileCollector(base_dir)
@@ -498,6 +538,8 @@ def create_bundle_for_flow_run(
                         files_key,
                     )
         except (OSError, TypeError, AttributeError) as e:
+            if include_files_base_dir is not None:
+                raise
             # Handle cases where flow has no file (dynamic flow) or other IO errors
             logger.warning(
                 "Could not collect included files: %s. Files will not be bundled.",

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5.dev1}/src/prefect/bundles/_ignore_filter.py

@@ -87,23 +87,9 @@ def _read_ignore_file(path: Path) -> list[str]:
     return [line for line in lines if line.strip() and not line.startswith("#")]
 
 
-def load_ignore_patterns(flow_dir: Path) -> list[str]:
-    """
-    Load patterns from cascading .prefectignore files.
-
-    Load order (patterns combined via union):
-    1. Project root .prefectignore (if found via pyproject.toml detection)
-    2. Flow directory .prefectignore (if different from project root)
-
-    Missing .prefectignore files emit debug log, not warning.
-
-    Args:
-        flow_dir: Flow file's directory (base for relative paths).
-
-    Returns:
-        Combined list of pattern strings from all .prefectignore files.
-    """
-    patterns: list[str] = []
+def _load_ignore_pattern_sources(flow_dir: Path) -> list[tuple[Path, list[str]]]:
+    """Load ignore patterns together with the directory they are relative to."""
+    sources: list[tuple[Path, list[str]]] = []
 
     # 1. Find and load project root .prefectignore
     project_root = find_project_root(flow_dir)
@@ -111,7 +97,7 @@ def load_ignore_patterns(flow_dir: Path) -> list[str]:
         project_ignore = project_root / ".prefectignore"
         if project_ignore.exists():
             logger.debug(f"Loading .prefectignore from project root: {project_ignore}")
-            patterns.extend(_read_ignore_file(project_ignore))
+            sources.append((project_root.resolve(), _read_ignore_file(project_ignore)))
         else:
             logger.debug(f"No .prefectignore found at project root: {project_root}")
     else:
@@ -123,11 +109,34 @@ def load_ignore_patterns(flow_dir: Path) -> list[str]:
         # Only load if different from project root's .prefectignore
         if project_root is None or flow_dir.resolve() != project_root.resolve():
             logger.debug(f"Loading .prefectignore from flow directory: {flow_ignore}")
-            patterns.extend(_read_ignore_file(flow_ignore))
+            sources.append((flow_dir.resolve(), _read_ignore_file(flow_ignore)))
     else:
         logger.debug(f"No .prefectignore found in flow directory: {flow_dir}")
 
-    return patterns
+    return sources
+
+
+def load_ignore_patterns(flow_dir: Path) -> list[str]:
+    """
+    Load patterns from cascading .prefectignore files.
+
+    Load order (later matching patterns override earlier patterns):
+    1. Project root .prefectignore (if found via pyproject.toml detection)
+    2. Flow directory .prefectignore (if different from project root)
+
+    Missing .prefectignore files emit debug log, not warning.
+
+    Args:
+        flow_dir: Flow file's directory (base for relative paths).
+
+    Returns:
+        Combined list of pattern strings from all .prefectignore files.
+    """
+    return [
+        pattern
+        for _, patterns in _load_ignore_pattern_sources(flow_dir)
+        for pattern in patterns
+    ]
 
 
 class IgnoreFilter:
@@ -155,14 +164,16 @@ class IgnoreFilter:
             flow_dir: Base directory for file collection (typically flow file's parent).
         """
         self.flow_dir = flow_dir.resolve()
-        self._spec: pathspec.GitIgnoreSpec | None = None
+        self._specs: list[tuple[Path, pathspec.GitIgnoreSpec]] = []
         self._load_patterns()
 
     def _load_patterns(self) -> None:
         """Load patterns and compile into pathspec."""
-        patterns = load_ignore_patterns(self.flow_dir)
-        if patterns:
-            self._spec = pathspec.GitIgnoreSpec.from_lines(patterns)
+        for pattern_root, patterns in _load_ignore_pattern_sources(self.flow_dir):
+            if patterns:
+                self._specs.append(
+                    (pattern_root, pathspec.GitIgnoreSpec.from_lines(patterns))
+                )
 
     def filter(
         self,
@@ -202,11 +213,25 @@ class IgnoreFilter:
                 result.excluded_by_ignore.append(file)
                 continue
 
-            # Check against ignore spec
+            # Check against ignore specs in cascade order. A later source only
+            # overrides the current decision when one of its patterns matches.
             excluded = False
-            if self._spec is not None:
-                if self._spec.match_file(rel_path):
-                    excluded = True
+            for pattern_root, spec in self._specs:
+                try:
+                    pattern_path = str(file.relative_to(pattern_root))
+                except ValueError:
+                    try:
+                        pattern_path = str(file.resolve().relative_to(pattern_root))
+                    except ValueError:
+                        continue
+
+                normalized_path = pathspec.util.normalize_file(pattern_path)
+                if any(
+                    pattern.include is not None
+                    and pattern.match_file(normalized_path) is not None
+                    for pattern in spec.patterns
+                ):
+                    excluded = spec.match_file(normalized_path)
 
             if excluded:
                 result.excluded_by_ignore.append(file)

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5.dev1}/src/prefect/events/filters.py

@@ -14,6 +14,14 @@ from prefect.utilities.collections import AutoEnum
 from .schemas.events import Event, Resource, ResourceSpecification
 
 
+class AutomationFilterId(PrefectBaseModel):
+    """Filter by `Automation.id`."""
+
+    any_: Optional[list[UUID]] = Field(
+        default=None, description="A list of automation ids to include"
+    )
+
+
 class AutomationFilterCreated(PrefectBaseModel):
     """Filter by `Automation.created`."""
 
@@ -52,6 +60,9 @@ class AutomationFilterTags(PrefectBaseModel):
 
 
 class AutomationFilter(PrefectBaseModel):
+    id: Optional[AutomationFilterId] = Field(
+        default=None, description="Filter criteria for `Automation.id`"
+    )
     name: Optional[AutomationFilterName] = Field(
         default=None, description="Filter criteria for `Automation.name`"
     )

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5.dev1}/src/prefect/events/worker.py

@@ -6,10 +6,12 @@ from uuid import UUID
 from typing_extensions import Self
 
 from prefect._internal.concurrency.services import QueueService
+from prefect.logging import get_logger
 from prefect.settings import (
     PREFECT_API_KEY,
     PREFECT_API_URL,
     PREFECT_CLOUD_API_URL,
+    get_current_settings,
 )
 from prefect.utilities.context import temporary_context
 
@@ -23,8 +25,12 @@ from .related import related_resources_from_run_context
 from .schemas.events import Event
 
 if TYPE_CHECKING:
+    import logging
+
     from prefect.client.orchestration import PrefectClient
 
+logger: "logging.Logger" = get_logger(__name__)
+
 
 class ProcessPoolForwardingEventsClient(EventsClient):
     """An events client that forwards events to a parent process queue."""
@@ -69,8 +75,6 @@ class EventsWorker(QueueService[Event]):
     def __init__(
         self, client_type: Type[EventsClient], client_options: Tuple[Tuple[str, Any]]
     ):
-        from prefect.settings import get_current_settings
-
         self._max_queue_size = get_current_settings().events.worker_max_queue_size
         super().__init__(client_type, client_options)
         self.client_type = client_type
@@ -113,10 +117,29 @@ class EventsWorker(QueueService[Event]):
             return
 
         exclude = {resource.id for resource in event.involved_resources}
-        event.related += await related_resources_from_run_context(
+        related = await related_resources_from_run_context(
             client=self._orchestration_client, exclude=exclude
         )
 
+        # The event was validated when it was created, before these resources were
+        # known, so only attach as many as keep the event within the same maximum that
+        # the Event schema validates.  Otherwise the event is no longer valid to send.
+        maximum = get_current_settings().server.events.maximum_related_resources
+        room = max(maximum - len(event.related), 0)
+        if len(related) > room:
+            logger.warning(
+                "Attaching only %s of the %s related resources from the run context "
+                "to event %s, which already has %s of a maximum %s related resources",
+                room,
+                len(related),
+                event.id,
+                len(event.related),
+                maximum,
+            )
+            related = related[:room]
+
+        event.related += related
+
     @classmethod
     def set_client_override(
         cls, client_type: Optional[Type[EventsClient]], **client_kwargs: Any

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5.dev1}/src/prefect/flows.py

@@ -2397,6 +2397,10 @@ class InfrastructureBoundFlow(Flow[P, R]):
         job_variables: Infrastructure configuration that will override the base job
             configuration of the work pool.
         launcher: Optional upload and execution launcher overrides.
+        include_files: Optional file patterns to include with the flow bundle.
+        include_files_base_dir: Optional base directory for `include_files`. Relative
+            paths are resolved from the working directory when the bundle is created.
+            Defaults to the flow file's directory.
         worker_cls: The class of the worker to use to spin up infrastructure and submit
             the flow to it.
     """
@@ -2409,6 +2413,7 @@ class InfrastructureBoundFlow(Flow[P, R]):
         worker_cls: type["BaseWorker[Any, Any, Any]"],
         launcher: BundleLauncher | None = None,
         include_files: Sequence[str] | None = None,
+        include_files_base_dir: Path | str | None = None,
         **kwargs: Any,
     ):
         super().__init__(*args, **kwargs)
@@ -2419,6 +2424,9 @@ class InfrastructureBoundFlow(Flow[P, R]):
         self.include_files: list[str] | None = (
             list(include_files) if include_files is not None else None
         )
+        self.include_files_base_dir: str | None = (
+            str(include_files_base_dir) if include_files_base_dir is not None else None
+        )
 
     @overload
     def __call__(self: "Flow[P, NoReturn]", *args: P.args, **kwargs: P.kwargs) -> None:
@@ -2648,7 +2656,7 @@ class InfrastructureBoundFlow(Flow[P, R]):
             get_result_store,
             resolve_result_storage,
         )
-        from prefect.states import Pending, Scheduled
+        from prefect.states import Failed, Pending, Scheduled
         from prefect.tasks import Task
 
         # Get parameters to error early if they are invalid
@@ -2753,14 +2761,28 @@ class InfrastructureBoundFlow(Flow[P, R]):
                 parent_task_run_id=getattr(parent_task_run, "id", None),
             )
 
-            result = create_bundle_for_flow_run(flow=flow, flow_run=flow_run)
-            upload_bundle_to_storage(
-                result["bundle"],
-                bundle_key,
-                upload_command,
-                zip_path=result["zip_path"],
-                upload_step=upload_step,
-            )
+            try:
+                result = create_bundle_for_flow_run(flow=flow, flow_run=flow_run)
+                upload_bundle_to_storage(
+                    result["bundle"],
+                    bundle_key,
+                    upload_command,
+                    zip_path=result["zip_path"],
+                    upload_step=upload_step,
+                )
+            except Exception as exc:
+                try:
+                    client.set_flow_run_state(
+                        flow_run.id,
+                        state=Failed(message=f"Flow run submission failed: {exc}"),
+                        force=True,
+                    )
+                except Exception:
+                    logger.exception(
+                        "Failed to update flow run %s after submission failed",
+                        flow_run.id,
+                    )
+                raise
 
             # Set flow run to scheduled now that the bundle is uploaded and ready to be executed
             client.set_flow_run_state(flow_run.id, state=Scheduled())
@@ -2795,6 +2817,7 @@ class InfrastructureBoundFlow(Flow[P, R]):
         job_variables: Optional[dict[str, Any]] = None,
         launcher: BundleLauncher | None = NotSet,  # type: ignore
         include_files: Optional[list[str]] = NotSet,  # type: ignore
+        include_files_base_dir: Path | str | None = NotSet,  # type: ignore
     ) -> "InfrastructureBoundFlow[P, R]":
         new_flow = super().with_options(
             name=name,
@@ -2828,6 +2851,9 @@ class InfrastructureBoundFlow(Flow[P, R]):
             include_files=include_files
             if include_files is not NotSet
             else self.include_files,
+            include_files_base_dir=include_files_base_dir
+            if include_files_base_dir is not NotSet
+            else self.include_files_base_dir,
         )
         return new_infrastructure_bound_flow
 
@@ -2839,7 +2865,25 @@ def bind_flow_to_infrastructure(
     job_variables: dict[str, Any] | None = None,
     launcher: BundleLauncher | None = None,
     include_files: Sequence[str] | None = None,
+    *,
+    include_files_base_dir: Path | str | None = None,
 ) -> InfrastructureBoundFlow[P, R]:
+    """Bind a flow to execution on a specific infrastructure work pool.
+
+    Args:
+        flow: The flow to bind.
+        work_pool: The name of the work pool to use.
+        worker_cls: The worker class that submits the flow.
+        job_variables: Infrastructure overrides for the work pool's base job template.
+        launcher: Optional upload and execution launcher overrides.
+        include_files: Optional file patterns to include with the flow bundle.
+        include_files_base_dir: Optional base directory for `include_files`. Relative
+            paths are resolved from the working directory when the bundle is created.
+            Defaults to the flow file's directory.
+
+    Returns:
+        An infrastructure-bound copy of the flow.
+    """
     new = InfrastructureBoundFlow[P, R](
         flow.fn,
         work_pool=work_pool,
@@ -2847,6 +2891,7 @@ def bind_flow_to_infrastructure(
         worker_cls=worker_cls,
         launcher=launcher,
         include_files=include_files,
+        include_files_base_dir=include_files_base_dir,
     )
     # Copy all attributes from the original flow
     for attr, value in flow.__dict__.items():
@@ -2856,6 +2901,9 @@ def bind_flow_to_infrastructure(
     new.worker_cls = worker_cls
     new.launcher = normalize_launcher(launcher)
     new.include_files = list(include_files) if include_files is not None else None
+    new.include_files_base_dir = (
+        str(include_files_base_dir) if include_files_base_dir is not None else None
+    )
     return new
 
 

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5.dev1}/src/prefect/logging/handlers.py

@@ -9,7 +9,7 @@ import traceback
 import uuid
 import warnings
 from contextlib import asynccontextmanager
-from typing import TYPE_CHECKING, Any, Callable, Dict, TextIO, Type
+from typing import TYPE_CHECKING, Any, Callable, Dict, TextIO, Type, cast
 
 from rich.console import Console
 from rich.highlighter import Highlighter, NullHighlighter
@@ -334,8 +334,29 @@ class _SafeStreamHandler(StreamHandler):
     it to handleError(), which prints a noisy traceback to sys.stderr. We
     suppress that for ValueError so background threads logging after stream
     teardown stay silent.
+
+    Context-managed locking also prevents asynchronous cancellation from
+    leaving the handler locked on Python 3.12 and earlier.
     """
 
+    def handle(self, record: logging.LogRecord) -> bool:
+        filtered = self.filter(record)
+        if isinstance(filtered, logging.LogRecord):
+            record = filtered
+        if filtered:
+            lock = self.lock
+            assert lock is not None
+            with lock:
+                self.emit(record)
+        return cast(bool, filtered)
+
+    def flush(self) -> None:
+        lock = self.lock
+        assert lock is not None
+        with lock:
+            if self.stream and hasattr(self.stream, "flush"):
+                self.stream.flush()
+
     def handleError(self, record: logging.LogRecord) -> None:
         _, exc, _ = sys.exc_info()
         if isinstance(exc, ValueError) and "closed file" in str(exc):

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5.dev1}/src/prefect/runner/AGENTS.md

@@ -23,7 +23,7 @@ Thin facade over single-responsibility extracted classes. New behavior belongs i
 | FlowRunExecutorContext | _flow_run_executor.py | Async context manager for one-shot execution outside Runner (workers, CLI, bundles) |
 | DirectSubprocessStarter | _starter_direct.py | Runs Flow object via run_flow_in_subprocess |
 | EngineCommandStarter | _starter_engine.py | Spawns `python -m prefect.engine` subprocess |
-| WorkspaceResolvingEngineCommandStarter | _workspace_starter.py | Resolves workspace (pull steps) via `_workspace_resolver` subprocess then delegates to EngineCommandStarter; used by `prefect flow-run execute` |
+| WorkspaceResolvingEngineCommandStarter | _workspace_starter.py | Starts a managed supervisor that prepares the workspace, launches the selected engine command, and records the prepared runtime for hooks |
 | BundleExecutionStarter | _starter_bundle.py | Executes serialized bundle in SpawnProcess |
 
 ## Key Contracts
@@ -45,7 +45,7 @@ Thin facade over single-responsibility extracted classes. New behavior belongs i
 - `execute_bundle()` -- deprecated (Mar 2026); use `execute_bundle()` from `prefect.bundles.execute`
 - `reschedule_current_flow_runs()` -- deprecated (Mar 2026); SIGTERM rescheduling is now handled inline by the CLI execute path
 
-These will be removed once internal callers are migrated. Direct ProcessWorker flow runs already use `FlowRunExecutorContext` with `EngineCommandStarter`; only its ad hoc bundle path still calls deprecated `Runner.execute_bundle()`. Keep lifecycle behavior in the extracted classes and do not route direct worker execution back through Runner.
+These will be removed once internal callers are migrated. Direct ProcessWorker flow runs already use `FlowRunExecutorContext`; generated commands use `WorkspaceResolvingEngineCommandStarter`, while explicitly configured commands use `EngineCommandStarter`. Only the ad hoc bundle path still calls deprecated `Runner.execute_bundle()`. Keep lifecycle behavior in the extracted classes and do not route direct worker execution back through Runner.
 
 ## EventEmitter WebSocket Degradation
 
@@ -108,7 +108,7 @@ The cancelling precheck (step 1a) still runs unconditionally even when `propose_
 
 ## ProcessWorker Execution Paths
 
-Direct ProcessWorker runs use `FlowRunExecutorContext` with `EngineCommandStarter` and `propose_submitting=False`. The executor owns process tracking, cancellation, Attempt Control Session evidence, crash inference, and normalized infrastructure status. Ad hoc ProcessWorker submissions still call deprecated `Runner.execute_bundle()` and remain a migration target.
+Direct ProcessWorker runs use `FlowRunExecutorContext` with `propose_submitting=False`. Generated commands use `WorkspaceResolvingEngineCommandStarter` so command selection follows workspace preparation; explicitly configured commands use `EngineCommandStarter` and retain their own pull-step semantics. The executor owns process tracking, cancellation, Attempt Control Session evidence, crash inference, and normalized infrastructure status. Ad hoc ProcessWorker submissions still call deprecated `Runner.execute_bundle()` and remain a migration target.
 
 ## BlockStorageAdapter Pull Behavior
 
@@ -133,19 +133,19 @@ These validations exist to prevent git argument injection. Do not bypass them wh
 
 ## Workspace Resolver Subprocess
 
-`_workspace_resolver.py` prepares a flow run workspace in an isolated subprocess (storage pull, pull steps, CWD/env/sys.path capture). Runs as `python -m prefect.runner._workspace_resolver`.
+`_workspace_resolver.py` prepares a flow run workspace inside the managed workspace supervisor (storage pull, pull steps, and CWD/environment/sys.path capture).
 
 **Stdout is reserved for the JSON `PreparedWorkspaceResult` payload only.** Pull step output (including inherited stdout from child processes) is redirected to stderr. Parse `process.stdout` for the result, `process.stderr` for diagnostics. Violating this breaks callers silently.
 
-**Caller-facing API:** Use `WorkspaceResolvingEngineCommandStarter` (`_workspace_starter.py`) rather than calling the resolver directly. It wraps the subprocess call, memoizes the resolved workspace (one subprocess call per starter instance), and provides `resolve_flow()` that loads the flow inside the resolved workspace context. Pass `starter.resolve_flow` as the `resolve_flow` argument to `FlowRunExecutorContext.create_executor()` — using a separate lambda bypasses the workspace context and will fail to find the flow.
+**Caller-facing API:** Use `WorkspaceResolvingEngineCommandStarter` (`_workspace_starter.py`) rather than calling the resolver directly when the caller owns workspace preparation. Pass `starter.hook_runner` as the `hook_runner` argument to `FlowRunExecutorContext.create_executor()`. The hook runner reads the prepared runtime manifest and loads hooks in a subprocess using the same command prefix, working directory, and environment as the engine. Treat explicitly configured commands as opaque; ProcessWorker launches them with `EngineCommandStarter` so their existing pull behavior is not duplicated.
 
-**Env/sys.path isolation:** `_prepared_workspace_context` mutates `os.environ` and `sys.path` in the caller process but does NOT change `os.getcwd()`. The parent working directory is preserved.
+**Environment isolation:** Workspace preparation, engine execution, and hook loading stay in child processes. Do not install a prepared workspace's environment, CWD, or `sys.path` in the long-lived runner process.
 
 **Local path in-place execution:** When no pull steps are configured and the entrypoint file exists at `deployment.path` but not in the workspace root, `prepare_workspace` sets `working_directory` to the local path — not under `workspace_root`. The workspace directory is still created but is not the execution root. This is the "image-baked" pattern: code lives at a fixed local path (e.g., inside a container), not in object storage.
 
 **Pull-step directory fallback:** When pull steps run but none produces a `directory` output or changes CWD, `_ensure_entrypoint_in_workspace` copies storage into the workspace root as a fallback. This handles setup-only pull steps (e.g., `run_shell_script` for environment prep) that do not control the working directory themselves.
 
-**Automatic dependency installation:** By default, `WorkspaceResolvingEngineCommandStarter` does not install dependencies before starting a flow run. When no explicit command is passed and `PREFECT_RUNNER_AUTO_INSTALL_DEPENDENCIES` is true, it auto-selects `uv run --no-default-groups --project <project_root> -m prefect.flow_engine` — but only when all three conditions hold: `pyproject.toml` exists at `project_root`, the `project.dependencies` list includes `prefect`, and `uv` is found via the workspace's `PATH` env var (not the system PATH). If the setting is false or any condition fails, the command falls back to `None`. Explicit commands always take precedence.
+**Automatic dependency installation:** By default, `WorkspaceResolvingEngineCommandStarter` does not install dependencies before starting a flow run. When no explicit command is passed and `PREFECT_RUNNER_AUTO_INSTALL_DEPENDENCIES` is true, it auto-selects `uv run --no-default-groups --project <project_root>` with the worker-supplied workspace bootstrap — but only when all three conditions hold: `pyproject.toml` exists at `project_root`, the `project.dependencies` list includes `prefect`, and `uv` is found via the workspace's `PATH` env var (not the system PATH). The bootstrap uses the prepared entrypoint with `prefect.flow_engine` when that module exposes its executable `_main`; older selected runtimes fall back to `prefect.engine` with `PREFECT__FLOW_ENTRYPOINT`, preserving the prepared workspace. If the setting is false or any condition fails, the command falls back to `None`. Explicit commands always take precedence.
 
 ## Reference
 

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5.dev1}/src/prefect/runner/_cancellation_manager.py

@@ -19,7 +19,7 @@ if TYPE_CHECKING:
     from prefect.client.schemas.objects import FlowRun
     from prefect.runner._control_channel import ControlChannel
     from prefect.runner._event_emitter import EventEmitter
-    from prefect.runner._hook_runner import HookRunner
+    from prefect.runner._hook_runner import FlowRunHookRunner
     from prefect.runner._process_manager import ProcessManager
     from prefect.runner._state_proposer import StateProposer
 
@@ -42,7 +42,7 @@ class CancellationManager:
         self,
         *,
         process_manager: ProcessManager,
-        hook_runner: HookRunner,
+        hook_runner: FlowRunHookRunner,
         state_proposer: StateProposer,
         event_emitter: EventEmitter,
         client: PrefectClient,

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5.dev1}/src/prefect/runner/_flow_run_executor.py

@@ -18,7 +18,7 @@ from prefect.logging import get_logger
 from prefect.runner._cancellation_manager import CancellationManager
 from prefect.runner._control_channel import ControlChannel
 from prefect.runner._event_emitter import EventEmitter
-from prefect.runner._hook_runner import HookRunner
+from prefect.runner._hook_runner import FlowRunHookRunner, HookRunner
 from prefect.runner._process_manager import ProcessHandle, ProcessManager
 from prefect.runner._state_proposer import StateProposer
 from prefect.settings.context import get_current_settings
@@ -94,7 +94,7 @@ class FlowRunExecutor:
         starter: ProcessStarter,
         process_manager: ProcessManager,
         state_proposer: StateProposer,
-        hook_runner: HookRunner,
+        hook_runner: FlowRunHookRunner,
         get_attempt_conclusion: Callable[[UUID], AttemptConclusion | None],
         propose_submitting: bool = True,
     ) -> None:
@@ -267,6 +267,7 @@ class FlowRunExecutorContext:
     async def __aenter__(self) -> FlowRunExecutorContext:
         self._stack = AsyncExitStack()
         await self._stack.__aenter__()
+        self._after_exit_callbacks: list[Callable[[], object]] = []
         self._logger = get_logger("runner.executor_context")
 
         # Step 1: client
@@ -339,7 +340,15 @@ class FlowRunExecutorContext:
         exc_value: BaseException | None,
         traceback: TracebackType | None,
     ) -> bool | None:
-        return await self._stack.__aexit__(exc_type, exc_value, traceback)
+        try:
+            return await self._stack.__aexit__(exc_type, exc_value, traceback)
+        finally:
+            for callback in reversed(self._after_exit_callbacks):
+                callback()
+
+    def call_after_exit(self, callback: Callable[[], object]) -> None:
+        """Keep attempt resources alive until cancellation work has drained."""
+        self._after_exit_callbacks.append(callback)
 
     def _handle_cancellation_observer_failure(self, flow_run_ids: set) -> None:
         """Handle failure of both cancellation observer mechanisms.
@@ -369,10 +378,15 @@ class FlowRunExecutorContext:
         self,
         flow_run: FlowRun,
         starter: ProcessStarter,
-        resolve_flow: Callable[[FlowRun], Awaitable[Flow[Any, Any]]],
+        resolve_flow: Callable[[FlowRun], Awaitable[Flow[Any, Any]]] | None = None,
         propose_submitting: bool = True,
+        hook_runner: FlowRunHookRunner | None = None,
     ) -> FlowRunExecutor:
-        hook_runner = HookRunner(resolve_flow=resolve_flow)
+        if (resolve_flow is None) == (hook_runner is None):
+            raise ValueError("Provide exactly one of resolve_flow or hook_runner.")
+        if hook_runner is None:
+            assert resolve_flow is not None
+            hook_runner = HookRunner(resolve_flow=resolve_flow)
         # Wire the real resolver into CancellationManager for on_cancellation hooks
         self._cancellation_manager._hook_runner = hook_runner
         return FlowRunExecutor(

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5.dev1}/src/prefect/runner/_hook_runner.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Awaitable, Callable
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Protocol
 
 from prefect._internal.concurrency.api import create_call, from_async
 from prefect._internal.engine import get_hook_name
@@ -13,6 +13,12 @@ if TYPE_CHECKING:
     from prefect.states import State
 
 
+class FlowRunHookRunner(Protocol):
+    async def run_cancellation_hooks(self, flow_run: FlowRun, state: State) -> None: ...
+
+    async def run_crashed_hooks(self, flow_run: FlowRun, state: State) -> None: ...
+
+
 async def _run_hooks(
     hooks: list[Any],
     flow_run: FlowRun,