griptape-nodes 0.65.6__py3-none-any.whl → 0.66.1__py3-none-any.whl

griptape_nodes/retained_mode/managers/library_manager.py

@@ -11,6 +11,7 @@ import sys
 import sysconfig
 from collections import defaultdict
 from dataclasses import dataclass, field
+from enum import StrEnum
 from importlib.resources import files
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Generic, NamedTuple, TypeVar, cast
@@ -57,9 +58,16 @@ from griptape_nodes.retained_mode.events.library_events import (
     CheckLibraryUpdateRequest,
     CheckLibraryUpdateResultFailure,
     CheckLibraryUpdateResultSuccess,
+    DiscoveredLibrary,
+    DiscoverLibrariesRequest,
+    DiscoverLibrariesResultFailure,
+    DiscoverLibrariesResultSuccess,
     DownloadLibraryRequest,
     DownloadLibraryResultFailure,
     DownloadLibraryResultSuccess,
+    EvaluateLibraryFitnessRequest,
+    EvaluateLibraryFitnessResultFailure,
+    EvaluateLibraryFitnessResultSuccess,
     GetAllInfoForAllLibrariesRequest,
     GetAllInfoForAllLibrariesResultFailure,
     GetAllInfoForAllLibrariesResultSuccess,
@@ -106,6 +114,9 @@ from griptape_nodes.retained_mode.events.library_events import (
     ReloadAllLibrariesRequest,
     ReloadAllLibrariesResultFailure,
     ReloadAllLibrariesResultSuccess,
+    ScanSandboxDirectoryRequest,
+    ScanSandboxDirectoryResultFailure,
+    ScanSandboxDirectoryResultSuccess,
     SwitchLibraryRefRequest,
     SwitchLibraryRefResultFailure,
     SwitchLibraryRefResultSuccess,
@@ -123,8 +134,15 @@ from griptape_nodes.retained_mode.events.object_events import ClearAllObjectStat
 from griptape_nodes.retained_mode.events.os_events import (
     DeleteFileRequest,
     DeleteFileResultFailure,
+    WriteFileRequest,
 )
 from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
+from griptape_nodes.retained_mode.events.resource_events import (
+    GetResourceInstanceStatusRequest,
+    GetResourceInstanceStatusResultSuccess,
+    ListCompatibleResourceInstancesRequest,
+    ListCompatibleResourceInstancesResultSuccess,
+)
 from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 from griptape_nodes.retained_mode.managers.fitness_problems.libraries import (
     AdvancedLibraryLoadFailureProblem,
@@ -133,6 +151,7 @@ from griptape_nodes.retained_mode.managers.fitness_problems.libraries import (
     CreateConfigCategoryProblem,
     DuplicateLibraryProblem,
     EngineVersionErrorProblem,
+    IncompatibleRequirementsProblem,
     InvalidVersionStringProblem,
     LibraryJsonDecodeProblem,
     LibraryLoadExceptionProblem,
@@ -147,11 +166,6 @@ from griptape_nodes.retained_mode.managers.fitness_problems.libraries import (
     SandboxDirectoryMissingProblem,
     UpdateConfigCategoryProblem,
 )
-from griptape_nodes.retained_mode.managers.library_lifecycle.library_directory import LibraryDirectory
-from griptape_nodes.retained_mode.managers.library_lifecycle.library_provenance.local_file import (
-    LibraryProvenanceLocalFile,
-)
-from griptape_nodes.retained_mode.managers.library_lifecycle.library_status import LibraryStatus
 from griptape_nodes.retained_mode.managers.os_manager import OSManager
 from griptape_nodes.retained_mode.managers.settings import LIBRARIES_TO_DOWNLOAD_KEY, LIBRARIES_TO_REGISTER_KEY
 from griptape_nodes.utils.async_utils import subprocess_run
@@ -230,20 +244,30 @@ class LibraryManager:
     LIBRARY_CONFIG_FILENAME = "griptape_nodes_library.json"
     LIBRARY_CONFIG_GLOB_PATTERN = "griptape[_-]nodes[_-]library.json"
 
-    @dataclass
-    class LibraryInfo:
-        """Information about a library that was attempted to be loaded.
+    # Sandbox library constants
+    UNRESOLVED_SANDBOX_CLASS_NAME = "<NOT YET RESOLVED>"
+    SANDBOX_CATEGORY_NAME = "Griptape Nodes Sandbox"
 
-        Includes the status of the library, the file path, and any problems encountered during loading.
-        """
+    _library_file_path_to_info: dict[str, LibraryInfo]
 
-        status: LibraryStatus
-        library_path: str
-        library_name: str | None = None
-        library_version: str | None = None
-        problems: list[LibraryProblem] = field(default_factory=list)
+    class LibraryLifecycleState(StrEnum):
+        """Lifecycle states for library loading."""
 
-    _library_file_path_to_info: dict[str, LibraryInfo]
+        FAILURE = "failure"
+        DISCOVERED = "discovered"
+        METADATA_LOADED = "metadata_loaded"
+        EVALUATED = "evaluated"
+        DEPENDENCIES_INSTALLED = "dependencies_installed"
+        LOADED = "loaded"
+
+    class LibraryFitness(StrEnum):
+        """Fitness of the library that was attempted to be loaded."""
+
+        GOOD = "GOOD"  # No errors detected during loading. Registered.
+        FLAWED = "FLAWED"  # Some errors detected, but recoverable. Registered.
+        UNUSABLE = "UNUSABLE"  # Errors detected and not recoverable. Not registered.
+        MISSING = "MISSING"  # File not found. Not registered.
+        NOT_EVALUATED = "NOT_EVALUATED"  # Library has not been evaluated yet.
 
     @dataclass
     class RegisteredEventHandler(Generic[TRegisteredEventData]):
@@ -257,6 +281,39 @@ class LibraryManager:
         library_data: LibrarySchema
         event_data: TRegisteredEventData | None = None
 
+    @dataclass
+    class LibraryInfo:
+        """Information about a library that was attempted to be loaded.
+
+        Tracks the lifecycle state (where we are in the loading process) and fitness (health/quality).
+        Includes the file path and any problems encountered during loading.
+
+        Attributes:
+            lifecycle_state: Current phase of the library loading lifecycle (DISCOVERED → METADATA_LOADED →
+                           EVALUATED → DEPENDENCIES_INSTALLED → LOADED or FAILURE at any phase)
+            fitness: Health/quality assessment of the library (GOOD, FLAWED, UNUSABLE, MISSING, NOT_EVALUATED)
+            library_path: Absolute path to the library JSON file or sandbox directory
+            is_sandbox: True if this is a sandbox library (user-created nodes in workspace), False for regular libraries
+            library_name: Name of the library from metadata (None until METADATA_LOADED phase)
+            library_version: Schema version from metadata (None until METADATA_LOADED phase)
+            problems: List of issues encountered during any phase (version incompatibilities, node load failures, etc.)
+                     Problems accumulate across lifecycle phases and determine final fitness level.
+        """
+
+        lifecycle_state: LibraryManager.LibraryLifecycleState
+        fitness: LibraryManager.LibraryFitness
+        library_path: str
+        is_sandbox: bool
+        library_name: str | None = None
+        library_version: str | None = None
+        problems: list[LibraryProblem] = field(default_factory=list)
+
+    class RegisterLibraryPrerequisites(NamedTuple):
+        """Prerequisites established for library loading."""
+
+        library_info: LibraryManager.LibraryInfo
+        file_path: str
+
     # Stable module namespace mappings for workflow serialization
     # These mappings ensure that dynamically loaded modules can be reliably imported
     # in generated workflow code by providing stable, predictable import paths.
@@ -284,8 +341,6 @@ class LibraryManager:
         self._library_event_handler_mappings: dict[
             type[Payload], dict[str, LibraryManager.RegisteredEventHandler[Any]]
         ] = {}
-        # LibraryDirectory owns the FSMs and manages library lifecycle
-        self._library_directory = LibraryDirectory()
         self._libraries_loading_complete = asyncio.Event()
 
         event_manager.assign_manager_to_request_type(
@@ -327,6 +382,7 @@ class LibraryManager:
         event_manager.assign_manager_to_request_type(
             LoadMetadataForAllLibrariesRequest, self.load_metadata_for_all_libraries_request
         )
+        event_manager.assign_manager_to_request_type(ScanSandboxDirectoryRequest, self.scan_sandbox_directory_request)
         event_manager.assign_manager_to_request_type(
             UnloadLibraryFromRegistryRequest, self.unload_library_from_registry_request
         )
@@ -371,25 +427,25 @@ class LibraryManager:
 
         # Status emojis mapping
         status_emoji = {
-            LibraryStatus.GOOD: "[green]OK[/green]",
-            LibraryStatus.FLAWED: "[yellow]![/yellow]",
-            LibraryStatus.UNUSABLE: "[red]X[/red]",
-            LibraryStatus.MISSING: "[red]?[/red]",
+            LibraryManager.LibraryFitness.GOOD: "[green]OK[/green]",
+            LibraryManager.LibraryFitness.FLAWED: "[yellow]![/yellow]",
+            LibraryManager.LibraryFitness.UNUSABLE: "[red]X[/red]",
+            LibraryManager.LibraryFitness.MISSING: "[red]?[/red]",
         }
 
         # Status text mapping (colored)
         status_text = {
-            LibraryStatus.GOOD: "[green](GOOD)[/green]",
-            LibraryStatus.FLAWED: "[yellow](FLAWED)[/yellow]",
-            LibraryStatus.UNUSABLE: "[red](UNUSABLE)[/red]",
-            LibraryStatus.MISSING: "[red](MISSING)[/red]",
+            LibraryManager.LibraryFitness.GOOD: "[green](GOOD)[/green]",
+            LibraryManager.LibraryFitness.FLAWED: "[yellow](FLAWED)[/yellow]",
+            LibraryManager.LibraryFitness.UNUSABLE: "[red](UNUSABLE)[/red]",
+            LibraryManager.LibraryFitness.MISSING: "[red](MISSING)[/red]",
         }
 
         # Add rows for each library info
         for lib_info in library_infos:
             # Library column with emoji, name, version, colored status, and file path underneath
-            emoji = status_emoji.get(lib_info.status, "ERROR: Unknown/Unexpected Library Status")
-            colored_status = status_text.get(lib_info.status, "(UNKNOWN)")
+            emoji = status_emoji.get(lib_info.fitness, "ERROR: Unknown/Unexpected Library Status")
+            colored_status = status_text.get(lib_info.fitness, "(UNKNOWN)")
             name = lib_info.library_name if lib_info.library_name else "*UNKNOWN*"
 
             library_version = lib_info.library_version
@@ -536,7 +592,9 @@ class LibraryManager:
         result = GetLibraryMetadataResultSuccess(metadata=metadata, result_details=details)
         return result
 
-    def load_library_metadata_from_file_request(self, request: LoadLibraryMetadataFromFileRequest) -> ResultPayload:
+    def load_library_metadata_from_file_request(  # noqa: PLR0911
+        self, request: LoadLibraryMetadataFromFileRequest
+    ) -> LoadLibraryMetadataFromFileResultSuccess | LoadLibraryMetadataFromFileResultFailure:
         """Load library metadata from a JSON file without loading the actual node modules.
 
         This method provides a lightweight way to get library schema information
@@ -553,7 +611,7 @@ class LibraryManager:
             return LoadLibraryMetadataFromFileResultFailure(
                 library_path=file_path,
                 library_name=None,
-                status=LibraryStatus.MISSING,
+                status=LibraryManager.LibraryFitness.MISSING,
                 problems=[LibraryNotFoundProblem(library_path=str(json_path))],
                 result_details=details,
             )
@@ -567,7 +625,7 @@ class LibraryManager:
             return LoadLibraryMetadataFromFileResultFailure(
                 library_path=file_path,
                 library_name=None,
-                status=LibraryStatus.UNUSABLE,
+                status=LibraryManager.LibraryFitness.UNUSABLE,
                 problems=[LibraryJsonDecodeProblem()],
                 result_details=details,
             )
@@ -576,7 +634,7 @@ class LibraryManager:
             return LoadLibraryMetadataFromFileResultFailure(
                 library_path=file_path,
                 library_name=None,
-                status=LibraryStatus.UNUSABLE,
+                status=LibraryManager.LibraryFitness.UNUSABLE,
                 problems=[LibraryLoadExceptionProblem(error_message=str(err))],
                 result_details=details,
             )
@@ -600,7 +658,7 @@ class LibraryManager:
             return LoadLibraryMetadataFromFileResultFailure(
                 library_path=file_path,
                 library_name=library_name,
-                status=LibraryStatus.UNUSABLE,
+                status=LibraryManager.LibraryFitness.UNUSABLE,
                 problems=problems,
                 result_details=details,
             )
@@ -609,11 +667,23 @@ class LibraryManager:
             return LoadLibraryMetadataFromFileResultFailure(
                 library_path=file_path,
                 library_name=library_name,
-                status=LibraryStatus.UNUSABLE,
+                status=LibraryManager.LibraryFitness.UNUSABLE,
                 problems=[LibrarySchemaExceptionProblem(error_message=str(err))],
                 result_details=details,
             )
 
+        # Make sure the version string is copacetic.
+        library_version = library_data.metadata.library_version
+        if library_version is None:
+            details = f"Attempted to load Library '{library_data.name}' JSON file from '{json_path}'. Failed because version string '{library_data.metadata.library_version}' wasn't valid. Must be in major.minor.patch format."
+            return LoadLibraryMetadataFromFileResultFailure(
+                library_path=file_path,
+                library_name=library_data.name,
+                status=LibraryManager.LibraryFitness.UNUSABLE,
+                problems=[InvalidVersionStringProblem(version_string=str(library_data.metadata.library_version))],
+                result_details=details,
+            )
+
         # Get git remote and ref if this library is in a git repository
         library_dir = json_path.parent.absolute()
         try:
@@ -659,13 +729,35 @@ class LibraryManager:
             else:
                 failed_libraries.append(cast("LoadLibraryMetadataFromFileResultFailure", metadata_result))
 
-        # Generate sandbox library metadata
-        sandbox_result = self._generate_sandbox_library_metadata()
-        if isinstance(sandbox_result, LoadLibraryMetadataFromFileResultSuccess):
-            successful_libraries.append(sandbox_result)
-        elif isinstance(sandbox_result, LoadLibraryMetadataFromFileResultFailure):
-            failed_libraries.append(sandbox_result)
-        # If sandbox_result is None, sandbox was not configured or no files found - skip it
+        # Generate sandbox library metadata if configured
+        sandbox_library_dir = self._get_sandbox_directory()
+        if sandbox_library_dir:
+            # Try to load existing JSON first - only scan if load fails
+            sandbox_json_path = sandbox_library_dir / LibraryManager.LIBRARY_CONFIG_FILENAME
+            sandbox_result = self.load_library_metadata_from_file_request(
+                LoadLibraryMetadataFromFileRequest(file_path=str(sandbox_json_path))
+            )
+
+            # If load failed, it either didn't exist or was malformed. Try scanning, which will generate a fresh one.
+            if isinstance(sandbox_result, LoadLibraryMetadataFromFileResultFailure):
+                scan_result = self.scan_sandbox_directory_request(
+                    ScanSandboxDirectoryRequest(directory_path=str(sandbox_library_dir))
+                )
+                # Map scan result to load result for consistency
+                if isinstance(scan_result, ScanSandboxDirectoryResultSuccess):
+                    sandbox_result = LoadLibraryMetadataFromFileResultSuccess(
+                        library_schema=scan_result.library_schema,
+                        file_path=str(sandbox_json_path),
+                        git_remote=None,
+                        git_ref=None,
+                        result_details=scan_result.result_details,
+                    )
+                # else: Keep the load failure result
+
+            if isinstance(sandbox_result, LoadLibraryMetadataFromFileResultSuccess):
+                successful_libraries.append(sandbox_result)
+            else:
+                failed_libraries.append(sandbox_result)
 
         details = (
             f"Successfully loaded metadata for {len(successful_libraries)} libraries, {len(failed_libraries)} failed"
@@ -678,130 +770,305 @@ class LibraryManager:
 
     def _generate_sandbox_library_metadata(
         self,
+        sandbox_directory: Path,
     ) -> LoadLibraryMetadataFromFileResultSuccess | LoadLibraryMetadataFromFileResultFailure | None:
         """Generate sandbox library metadata by scanning Python files without importing them.
 
-        Returns None if no sandbox directory is configured or no files are found.
-        """
-        config_mgr = GriptapeNodes.ConfigManager()
-        sandbox_library_subdir = config_mgr.get_config_value("sandbox_library_directory")
-        if not sandbox_library_subdir:
-            logger.debug("No sandbox directory specified in config. Skipping sandbox library metadata generation.")
-            return None
+        Args:
+            sandbox_directory: Path to sandbox directory to scan.
 
-        # Prepend the workflow directory; if the sandbox dir starts with a slash, the workflow dir will be ignored.
-        sandbox_library_dir = config_mgr.workspace_path / sandbox_library_subdir
-        sandbox_library_dir_as_posix = sandbox_library_dir.as_posix()
+        Returns None if no files are found.
+        """
+        sandbox_library_dir_as_posix = sandbox_directory.as_posix()
 
-        if not sandbox_library_dir.exists():
+        if not sandbox_directory.exists():
             details = "Sandbox directory does not exist. If you wish to create a Sandbox directory to develop custom nodes: in the Griptape Nodes editor, go to Settings -> Libraries and navigate to the Sandbox Settings."
             return LoadLibraryMetadataFromFileResultFailure(
                 library_path=sandbox_library_dir_as_posix,
                 library_name=LibraryManager.SANDBOX_LIBRARY_NAME,
-                status=LibraryStatus.MISSING,
+                status=LibraryManager.LibraryFitness.MISSING,
                 problems=[SandboxDirectoryMissingProblem()],
                 result_details=ResultDetails(message=details, level=logging.INFO),
             )
 
-        sandbox_node_candidates = self._find_files_in_dir(directory=sandbox_library_dir, extension=".py")
+        sandbox_node_candidates = self._find_files_in_dir(directory=sandbox_directory, extension=".py")
         if not sandbox_node_candidates:
             logger.debug(
-                "No candidate files found in sandbox directory '%s'. Skipping sandbox library metadata generation.",
-                sandbox_library_dir,
+                "No candidate files found in sandbox directory '%s'. Creating empty sandbox library metadata.",
+                sandbox_directory,
             )
-            return None
+            # Continue with empty list - create valid schema with 0 nodes
+            sandbox_node_candidates = []
+
+        # Try to load existing library JSON for smart merging
+        json_path = sandbox_directory / LibraryManager.LIBRARY_CONFIG_FILENAME
+        metadata_result = self.load_library_metadata_from_file_request(
+            LoadLibraryMetadataFromFileRequest(file_path=str(json_path))
+        )
 
-        # For metadata-only generation, we create placeholder node definitions
-        # based on file names since we can't inspect the classes without importing
-        node_definitions = []
-        for candidate in sandbox_node_candidates:
-            # Use the full file name (with extension) as a placeholder to make it clear this is a file candidate
-            file_name = candidate.name
-
-            # Create a placeholder node definition - we can't get the actual class metadata
-            # without importing, so we use defaults
-            node_metadata = NodeMetadata(
-                category="Griptape Nodes Sandbox",
-                description=f"'{file_name}' may contain one or more nodes defined in this candidate file.",
-                display_name=file_name,
-                icon="square-dashed",
-                color=None,
+        existing_schema = None
+        if isinstance(metadata_result, LoadLibraryMetadataFromFileResultSuccess):
+            existing_schema = metadata_result.library_schema
+            logger.debug("Loaded existing sandbox library JSON from '%s'", json_path)
+        else:
+            logger.debug(
+                "No existing sandbox library JSON or failed to load from '%s': %s. Will generate fresh schema.",
+                json_path,
+                metadata_result.result_details,
             )
-            node_definition = NodeDefinition(
-                class_name=file_name,
-                file_path=str(candidate),
-                metadata=node_metadata,
+
+        if existing_schema is not None:
+            # Smart merge: preserve existing customizations, add new files, remove deleted files
+            logger.debug(
+                "Merging existing sandbox library JSON with discovered files in sandbox directory '%s'",
+                sandbox_directory,
+            )
+            node_definitions = self._merge_sandbox_nodes(
+                existing_schema=existing_schema,
+                discovered_files=sandbox_node_candidates,
+                sandbox_directory=sandbox_directory,
             )
-            node_definitions.append(node_definition)
 
-        if not node_definitions:
+            if not node_definitions:
+                logger.debug(
+                    "No valid node files found after merge in sandbox directory '%s'. Creating empty sandbox library metadata.",
+                    sandbox_directory,
+                )
+                # Continue with empty list - create valid schema with 0 nodes
+                node_definitions = []
+
+            # Preserve existing library metadata
+            library_name = existing_schema.name
+            library_metadata = existing_schema.metadata
+            categories = existing_schema.categories
+
+            # Update schema version to latest
+            library_schema_version = LibrarySchema.LATEST_SCHEMA_VERSION
+
+        else:
+            # No existing JSON or it failed to load - generate fresh schema
             logger.debug(
-                "No valid node files found in sandbox directory '%s'. Skipping sandbox library metadata generation.",
-                sandbox_library_dir,
+                "Generating fresh sandbox library schema for sandbox directory '%s'",
+                sandbox_directory,
             )
-            return None
 
-        # Create the library schema
-        sandbox_category = CategoryDefinition(
-            title="Sandbox",
-            description=f"Nodes loaded from the {LibraryManager.SANDBOX_LIBRARY_NAME}.",
-            color="#c7621a",
-            icon="Folder",
-        )
+            # Create placeholder node definitions (original behavior)
+            node_definitions = []
+            for candidate in sandbox_node_candidates:
+                # Use placeholder class name to make it obvious when discovery hasn't run yet
+                class_name = self.UNRESOLVED_SANDBOX_CLASS_NAME
+                file_name = candidate.name
+
+                # Create a placeholder node definition - we can't get the actual class metadata
+                # without importing, so we use defaults
+                node_metadata = NodeMetadata(
+                    category=self.SANDBOX_CATEGORY_NAME,
+                    description=f"'{file_name}' may contain one or more nodes defined in this candidate file.",
+                    display_name=file_name,
+                    icon="square-dashed",
+                    color=None,
+                )
+                node_definition = NodeDefinition(
+                    class_name=class_name,
+                    file_path=str(candidate.relative_to(sandbox_directory)),
+                    metadata=node_metadata,
+                )
+                node_definitions.append(node_definition)
 
-        engine_version = GriptapeNodes().handle_engine_version_request(request=GetEngineVersionRequest())
-        if not isinstance(engine_version, GetEngineVersionResultSuccess):
-            details = "Could not get engine version for sandbox library generation."
-            return LoadLibraryMetadataFromFileResultFailure(
-                library_path=sandbox_library_dir_as_posix,
-                library_name=LibraryManager.SANDBOX_LIBRARY_NAME,
-                status=LibraryStatus.UNUSABLE,
-                problems=[EngineVersionErrorProblem()],
-                result_details=details,
+            if not node_definitions:
+                logger.debug(
+                    "No valid node files found in sandbox directory '%s'. Creating empty sandbox library metadata.",
+                    sandbox_directory,
+                )
+                # Continue with empty list - create valid schema with 0 nodes
+                node_definitions = []
+
+            # Create default metadata
+            sandbox_category = CategoryDefinition(
+                title="Sandbox",
+                description=f"Nodes loaded from the {LibraryManager.SANDBOX_LIBRARY_NAME}.",
+                color="#c7621a",
+                icon="Folder",
             )
 
-        engine_version_str = f"{engine_version.major}.{engine_version.minor}.{engine_version.patch}"
-        library_metadata = LibraryMetadata(
-            author="Author needs to be specified when library is published.",
-            description="Nodes loaded from the sandbox library.",
-            library_version=engine_version_str,
-            engine_version=engine_version_str,
-            tags=["sandbox"],
-            is_griptape_nodes_searchable=False,
-        )
-        categories = [
-            {"Griptape Nodes Sandbox": sandbox_category},
-        ]
+            engine_version = GriptapeNodes().handle_engine_version_request(request=GetEngineVersionRequest())
+            if not isinstance(engine_version, GetEngineVersionResultSuccess):
+                details = "Could not get engine version for sandbox library generation."
+                return LoadLibraryMetadataFromFileResultFailure(
+                    library_path=sandbox_library_dir_as_posix,
+                    library_name=LibraryManager.SANDBOX_LIBRARY_NAME,
+                    status=LibraryManager.LibraryFitness.UNUSABLE,
+                    problems=[EngineVersionErrorProblem()],
+                    result_details=details,
+                )
+
+            engine_version_str = f"{engine_version.major}.{engine_version.minor}.{engine_version.patch}"
+            library_metadata = LibraryMetadata(
+                author="Author needs to be specified when library is published.",
+                description="Nodes loaded from the sandbox library.",
+                library_version=engine_version_str,
+                engine_version=engine_version_str,
+                tags=["sandbox"],
+                is_griptape_nodes_searchable=False,
+            )
+            categories = [
+                {self.SANDBOX_CATEGORY_NAME: sandbox_category},
+            ]
+            library_name = LibraryManager.SANDBOX_LIBRARY_NAME
+            library_schema_version = LibrarySchema.LATEST_SCHEMA_VERSION
+
+        # Create the library schema (now using variables set by either path)
         library_schema = LibrarySchema(
-            name=LibraryManager.SANDBOX_LIBRARY_NAME,
-            library_schema_version=LibrarySchema.LATEST_SCHEMA_VERSION,
+            name=library_name,
+            library_schema_version=library_schema_version,
             metadata=library_metadata,
             categories=categories,
             nodes=node_definitions,
         )
 
-        # Get git remote and ref if the sandbox directory is in a git repository
-        try:
-            git_remote = get_git_remote(sandbox_library_dir)
-        except GitRemoteError as e:
-            logger.debug("Failed to get git remote for sandbox library %s: %s", sandbox_library_dir, e)
-            git_remote = None
+        # Sandbox libraries are never git repositories - always set to None
+        git_remote = None
+        git_ref = None
 
-        try:
-            git_ref = get_current_ref(sandbox_library_dir)
-        except GitRefError as e:
-            logger.debug("Failed to get git ref for sandbox library %s: %s", sandbox_library_dir, e)
-            git_ref = None
-
-        details = f"Successfully generated sandbox library metadata with {len(node_definitions)} nodes from {sandbox_library_dir}"
+        details = f"Successfully generated sandbox library metadata with {len(node_definitions)} nodes from {sandbox_directory}"
         return LoadLibraryMetadataFromFileResultSuccess(
             library_schema=library_schema,
-            file_path=str(sandbox_library_dir),
+            file_path=str(sandbox_directory),
             git_remote=git_remote,
             git_ref=git_ref,
             result_details=details,
         )
 
+    def _merge_sandbox_nodes(
+        self,
+        existing_schema: LibrarySchema,
+        discovered_files: list[Path],
+        sandbox_directory: Path,
+    ) -> list[NodeDefinition]:
+        """Merge existing node definitions with newly discovered files.
+
+        Args:
+            existing_schema: Previously saved library schema
+            discovered_files: List of .py files found in sandbox directory
+            sandbox_directory: Path to sandbox directory for computing relative paths
+
+        Returns:
+            Merged list of NodeDefinitions
+        """
+        # Create mapping of discovered files for quick lookup (use absolute resolved paths)
+        discovered_file_paths = {str(f.resolve()): f for f in discovered_files}
+
+        # Keep existing nodes that still have corresponding files
+        merged_nodes = []
+        existing_file_paths = set()
+
+        for existing_node in existing_schema.nodes:
+            # Resolve the file path to absolute for comparison
+            try:
+                existing_file_path = str(Path(existing_node.file_path).resolve())
+            except Exception as e:
+                logger.warning(
+                    "Could not resolve path for existing node '%s' at '%s': %s. Skipping.",
+                    existing_node.class_name,
+                    existing_node.file_path,
+                    e,
+                )
+                continue
+
+            # Keep node if file still exists
+            if existing_file_path in discovered_file_paths:
+                merged_nodes.append(existing_node)
+                existing_file_paths.add(existing_file_path)
+                logger.debug(
+                    "Preserved existing sandbox node definition: %s (%s)",
+                    existing_node.class_name,
+                    existing_node.file_path,
+                )
+            else:
+                logger.debug(
+                    "Removing sandbox node '%s' - file no longer exists: %s",
+                    existing_node.class_name,
+                    existing_node.file_path,
+                )
+
+        # Add new files as placeholder nodes
+        for discovered_file in discovered_files:
+            discovered_file_path = str(discovered_file.resolve())
+
+            if discovered_file_path not in existing_file_paths:
+                # Create placeholder node definition for new file
+                class_name = self.UNRESOLVED_SANDBOX_CLASS_NAME
+                file_name = discovered_file.name
+
+                node_metadata = NodeMetadata(
+                    category=self.SANDBOX_CATEGORY_NAME,
+                    description=f"'{file_name}' may contain one or more nodes defined in this candidate file.",
+                    display_name=file_name,
+                    icon="square-dashed",
+                    color=None,
+                )
+                node_definition = NodeDefinition(
+                    class_name=class_name,
+                    file_path=str(discovered_file.relative_to(sandbox_directory)),
+                    metadata=node_metadata,
+                )
+                merged_nodes.append(node_definition)
+                logger.debug(
+                    "Added new placeholder sandbox node: %s (%s)",
+                    file_name,
+                    discovered_file.relative_to(sandbox_directory),
+                )
+
+        return merged_nodes
+
+    def _get_sandbox_directory(self) -> Path | None:
+        """Get the configured sandbox directory path.
+
+        Returns:
+            Path to sandbox directory if configured and exists, None otherwise.
+        """
+        config_mgr = GriptapeNodes.ConfigManager()
+        sandbox_library_subdir = config_mgr.get_config_value("sandbox_library_directory")
+        if not sandbox_library_subdir:
+            return None
+
+        sandbox_library_dir = config_mgr.workspace_path / sandbox_library_subdir
+        if not sandbox_library_dir.exists():
+            return None
+
+        return sandbox_library_dir
+
+    def scan_sandbox_directory_request(
+        self,
+        request: ScanSandboxDirectoryRequest,
+    ) -> ScanSandboxDirectoryResultSuccess | ScanSandboxDirectoryResultFailure:
+        """Handle ScanSandboxDirectoryRequest.
+
+        Scans specified sandbox directory and generates/merges library metadata.
+        """
+        sandbox_directory = Path(request.directory_path)
+
+        # Generate/merge library metadata
+        result = self._generate_sandbox_library_metadata(sandbox_directory=sandbox_directory)
+
+        # Note: result should never be None after Step 1 fix, but handle defensively
+        if result is None:
+            details = f"Internal error: _generate_sandbox_library_metadata returned None for {sandbox_directory}"
+            return ScanSandboxDirectoryResultFailure(result_details=ResultDetails(message=details, level=logging.ERROR))
+
+        if isinstance(result, LoadLibraryMetadataFromFileResultFailure):
+            # Failure during generation
+            return ScanSandboxDirectoryResultFailure(result_details=result.result_details)
+
+        # Success
+        return ScanSandboxDirectoryResultSuccess(
+            library_schema=result.library_schema,
+            result_details=ResultDetails(
+                message=f"Scanned sandbox directory: {len(result.library_schema.nodes)} node definitions",
+                level=logging.INFO,
+            ),
+        )
+
     def get_node_metadata_from_library_request(self, request: GetNodeMetadataFromLibraryRequest) -> ResultPayload:
         # Does this library exist?
         try:
@@ -842,206 +1109,443 @@ class LibraryManager:
         )
         return result
 
-    async def register_library_from_file_request(self, request: RegisterLibraryFromFileRequest) -> ResultPayload:  # noqa: C901, PLR0911, PLR0912, PLR0915 (complex logic needs branches)
-        file_path = request.file_path
+    async def register_library_from_file_request(self, request: RegisterLibraryFromFileRequest) -> ResultPayload:  # noqa: PLR0911 (result determination needs returns)
+        """Register a library by name or path, progressing through all lifecycle phases.
 
-        # Convert to Path object if it's a string
-        json_path = Path(file_path)
+        Supports loading by library_name OR file_path (mutually exclusive), with optional
+        discovery integration. Creates LibraryInfo if not already tracked.
 
-        # Check if the file exists
-        if not json_path.exists():
-            self._library_file_path_to_info[file_path] = LibraryManager.LibraryInfo(
-                library_path=file_path,
-                library_name=None,
-                status=LibraryStatus.MISSING,
-                problems=[LibraryNotFoundProblem(library_path=file_path)],
-            )
-            details = f"Attempted to load Library JSON file. Failed because no file could be found at the specified path: {json_path}"
-            return RegisterLibraryFromFileResultFailure(result_details=details)
-
-        # Use the new metadata loading functionality
-        metadata_request = LoadLibraryMetadataFromFileRequest(file_path=file_path)
-        metadata_result = self.load_library_metadata_from_file_request(metadata_request)
+        Args:
+            request: RegisterLibraryFromFileRequest containing library_name OR file_path,
+                    perform_discovery_if_not_found, and load_as_default_library
 
-        if not isinstance(metadata_result, LoadLibraryMetadataFromFileResultSuccess):
-            # Metadata loading failed, use the detailed error information from the failure result
-            failure_result = cast("LoadLibraryMetadataFromFileResultFailure", metadata_result)
+        Returns:
+            RegisterLibraryFromFileResultSuccess if loaded, RegisterLibraryFromFileResultFailure otherwise
+        """
+        # Phase 1: Establish prerequisites
+        prereq_result = await self._establish_register_library_prerequisites(request)
 
-            self._library_file_path_to_info[file_path] = LibraryManager.LibraryInfo(
-                library_path=file_path,
-                library_name=failure_result.library_name,
-                status=failure_result.status,
-                problems=failure_result.problems,
-            )
-            return RegisterLibraryFromFileResultFailure(result_details=str(failure_result.result_details))
+        # FAILURE CHECK FIRST
+        if isinstance(prereq_result, RegisterLibraryFromFileResultFailure):
+            return prereq_result
 
-        # Get the validated library data
-        library_data = metadata_result.library_schema
+        # SUCCESS CHECK (library already loaded)
+        if isinstance(prereq_result, RegisterLibraryFromFileResultSuccess):
+            return prereq_result
 
-        # Make sure the version string is copacetic.
-        library_version = library_data.metadata.library_version
-        if library_version is None:
-            self._library_file_path_to_info[file_path] = LibraryManager.LibraryInfo(
-                library_path=file_path,
-                library_name=library_data.name,
-                status=LibraryStatus.UNUSABLE,
-                problems=[InvalidVersionStringProblem(version_string=str(library_data.metadata.library_version))],
-            )
-            details = f"Attempted to load Library '{library_data.name}' JSON file from '{json_path}'. Failed because version string '{library_data.metadata.library_version}' wasn't valid. Must be in major.minor.patch format."
-            return RegisterLibraryFromFileResultFailure(result_details=details)
+        # Extract prerequisites
+        library_info = prereq_result.library_info
+        file_path = prereq_result.file_path
 
-        # Get the directory containing the JSON file to resolve relative paths
-        base_dir = json_path.parent.absolute()
-        # Add the directory to the Python path to allow for relative imports
-        sys.path.insert(0, str(base_dir))
+        # Phase 2: Progress through lifecycle phases
+        progression_result = await self._progress_library_through_lifecycle(
+            library_info=library_info, file_path=file_path, request=request
+        )
 
-        # Install dependencies and add library venv to sys.path if library has dependencies
-        if library_data.metadata.dependencies and library_data.metadata.dependencies.pip_dependencies:
-            venv_path = self._get_library_venv_path(library_data.name, file_path)
+        # FAILURE CHECK
+        if isinstance(progression_result, RegisterLibraryFromFileResultFailure):
+            return progression_result
 
-            install_request = InstallLibraryDependenciesRequest(library_file_path=file_path)
-            install_result = await self.install_library_dependencies_request(install_request)
+        # Phase 3: Return appropriate result based on fitness
+        # At this point, library_name must be set (it's set during METADATA_LOADED phase)
+        if library_info.library_name is None:
+            details = "Library loaded but library_name was not set during metadata loading"
+            return RegisterLibraryFromFileResultFailure(result_details=details)
 
-            if isinstance(install_result, InstallLibraryDependenciesResultFailure):
-                details = (
-                    f"Failed to install dependencies for library '{library_data.name}': {install_result.result_details}"
+        match library_info.fitness:
+            case LibraryManager.LibraryFitness.GOOD:
+                details = f"Successfully loaded Library '{library_info.library_name}' from JSON file at {file_path}"
+                return RegisterLibraryFromFileResultSuccess(
+                    library_name=library_info.library_name,
+                    result_details=ResultDetails(message=details, level=logging.INFO),
+                )
+            case LibraryManager.LibraryFitness.FLAWED:
+                details = f"Successfully loaded Library JSON file from '{file_path}', but one or more nodes failed to load. Check the log for more details."
+                return RegisterLibraryFromFileResultSuccess(
+                    library_name=library_info.library_name,
+                    result_details=ResultDetails(message=details, level=logging.WARNING),
                 )
+            case LibraryManager.LibraryFitness.UNUSABLE:
+                details = f"Attempted to load Library JSON file from '{file_path}'. Failed because no nodes were loaded. Check the log for more details."
+                return RegisterLibraryFromFileResultFailure(result_details=details)
+            case _:
+                details = f"Attempted to load Library JSON file from '{file_path}'. Failed because an unknown/unexpected fitness '{library_info.fitness}' was returned."
                 return RegisterLibraryFromFileResultFailure(result_details=details)
 
-            if isinstance(install_result, InstallLibraryDependenciesResultSuccess):
-                logger.info(
-                    "Installed %d dependencies for library '%s'",
-                    install_result.dependencies_installed,
-                    library_data.name,
+    async def _establish_register_library_prerequisites(  # noqa: C901, PLR0911, PLR0912 (prerequisite validation needs branches)
+        self, request: RegisterLibraryFromFileRequest
+    ) -> (
+        LibraryManager.RegisterLibraryPrerequisites
+        | RegisterLibraryFromFileResultSuccess
+        | RegisterLibraryFromFileResultFailure
+    ):
+        """Validate request and establish library identity.
+
+        Returns:
+            RegisterLibraryPrerequisites: Ready for lifecycle progression
+            RegisterLibraryFromFileResultSuccess: Library already loaded (early exit)
+            RegisterLibraryFromFileResultFailure: Validation or lookup failed
+        """
+        # Validate request has either library_name or file_path (but not both)
+        if not request.library_name and not request.file_path:
+            return RegisterLibraryFromFileResultFailure(
+                result_details="Attempted to register a library. Failed because neither library name nor file path were specified."
+            )
+
+        if request.library_name and request.file_path:
+            return RegisterLibraryFromFileResultFailure(
+                result_details="Attempted to register a library. Failed because both library name and file path were specified."
+            )
+
+        library_name = request.library_name
+        file_path = request.file_path
+
+        # If file_path provided but not library_name, load metadata to get the name
+        if file_path and not library_name:
+            lib_info = self._library_file_path_to_info.get(file_path)
+
+            # If we don't have LibraryInfo yet, load metadata to get the name
+            if not lib_info or not lib_info.library_name:
+                metadata_result = self.load_library_metadata_from_file_request(
+                    LoadLibraryMetadataFromFileRequest(file_path=file_path)
                 )
 
-            # Add venv site-packages to sys.path so node imports can find dependencies
-            if venv_path.exists():
-                site_packages = str(
-                    Path(
-                        sysconfig.get_path(
-                            "purelib",
-                            vars={"base": str(venv_path), "platbase": str(venv_path)},
-                        )
+                if isinstance(metadata_result, LoadLibraryMetadataFromFileResultFailure):
+                    return RegisterLibraryFromFileResultFailure(result_details=metadata_result.result_details)
+
+                library_name = metadata_result.library_schema.name
+
+                # Update or create LibraryInfo
+                if lib_info:
+                    lib_info.library_name = library_name
+                    lib_info.library_version = metadata_result.library_schema.metadata.library_version
+                    lib_info.lifecycle_state = LibraryManager.LibraryLifecycleState.METADATA_LOADED
+                else:
+                    # Create new LibraryInfo since it doesn't exist yet
+                    lib_info = LibraryManager.LibraryInfo(
+                        lifecycle_state=LibraryManager.LibraryLifecycleState.METADATA_LOADED,
+                        library_path=file_path,
+                        is_sandbox=False,
+                        library_name=library_name,
+                        library_version=metadata_result.library_schema.metadata.library_version,
+                        fitness=LibraryManager.LibraryFitness.NOT_EVALUATED,
+                        problems=[],
                     )
-                )
-                sys.path.insert(0, site_packages)
-                logger.debug("Added library '%s' venv to sys.path: %s", library_data.name, site_packages)
+                    self._library_file_path_to_info[file_path] = lib_info
+            else:
+                library_name = lib_info.library_name
 
-        # Load the advanced library module if specified
-        advanced_library_instance = None
-        if library_data.advanced_library_path:
-            try:
-                advanced_library_instance = self._load_advanced_library_module(
-                    library_data=library_data,
-                    base_dir=base_dir,
-                )
-            except Exception as err:
-                self._library_file_path_to_info[file_path] = LibraryManager.LibraryInfo(
-                    library_path=file_path,
-                    library_name=library_data.name,
-                    library_version=library_version,
-                    status=LibraryStatus.UNUSABLE,
-                    problems=[
-                        AdvancedLibraryLoadFailureProblem(
-                            advanced_library_path=library_data.advanced_library_path, error_message=str(err)
-                        )
-                    ],
-                )
-                details = f"Attempted to load Library '{library_data.name}' from '{json_path}'. Failed to load Advanced Library module: {err}"
-                return RegisterLibraryFromFileResultFailure(result_details=details)
+        # At this point, library_name must be set (either from request or from metadata)
+        if not library_name:
+            return RegisterLibraryFromFileResultFailure(result_details="Failed to determine library name")
 
-        # Create or get the library
+        # Check if already loaded in registry
         try:
-            # Try to create a new library
-            library = LibraryRegistry.generate_new_library(
-                library_data=library_data,
-                mark_as_default_library=request.load_as_default_library,
-                advanced_library=advanced_library_instance,
-            )
-
-        except KeyError as err:
-            # Library already exists
-            self._library_file_path_to_info[file_path] = LibraryManager.LibraryInfo(
-                library_path=file_path,
-                library_name=library_data.name,
-                library_version=library_version,
-                status=LibraryStatus.UNUSABLE,
-                problems=[DuplicateLibraryProblem()],
+            LibraryRegistry.get_library(name=library_name)
+            return RegisterLibraryFromFileResultSuccess(
+                library_name=library_name,
+                result_details=f"Library '{library_name}' already loaded",
             )
-
-            details = f"Attempted to load Library JSON file from '{json_path}'. Failed because a Library '{library_data.name}' already exists. Error: {err}."
+        except KeyError:
+            pass  # Not loaded, continue
+
+        # Look up LibraryInfo by library_name (supports lazy loading)
+        library_info = self.get_library_info_by_library_name(library_name)
+
+        # If not found and discovery is allowed, try discovery
+        if library_info is None and request.perform_discovery_if_not_found:
+            discover_result = self.discover_libraries_request(DiscoverLibrariesRequest())
+            if isinstance(discover_result, DiscoverLibrariesResultSuccess):
+                library_info = self.get_library_info_by_library_name(library_name)
+
+        # If still not found, fail
+        if library_info is None:
+            details = f"Library '{library_name}' not found"
+            if request.perform_discovery_if_not_found:
+                details += " (discovery was attempted)"
             return RegisterLibraryFromFileResultFailure(result_details=details)
 
-        # We are at least potentially viable.
-        # Record all problems that occurred
-        problems = []
+        file_path = library_info.library_path
 
-        # Check the library's custom config settings.
-        if library_data.settings is not None:
-            # Assign them into the config space.
-            for library_data_setting in library_data.settings:
-                # Does the category exist?
-                get_category_request = GetConfigCategoryRequest(
-                    category=library_data_setting.category,
-                    failure_log_level=logging.DEBUG,  # Missing category is expected, suppress error toast
+        # Check if already loaded in registry (by name if we have it)
+        if library_info.library_name:
+            try:
+                LibraryRegistry.get_library(name=library_info.library_name)
+            except KeyError:
+                # Library not in registry, continue with loading
+                pass
+            else:
+                # Already loaded and good to go
+                return RegisterLibraryFromFileResultSuccess(
+                    library_name=library_info.library_name,
+                    result_details=f"Library '{library_info.library_name}' already loaded",
                 )
-                get_category_result = GriptapeNodes.handle_request(get_category_request)
-                if not isinstance(get_category_result, GetConfigCategoryResultSuccess):
-                    # That's OK, we'll invent it. Or at least we'll try.
-                    create_new_category_request = SetConfigCategoryRequest(
-                        category=library_data_setting.category, contents=library_data_setting.contents
+
+        # Prerequisites established - ready for lifecycle progression
+        return LibraryManager.RegisterLibraryPrerequisites(library_info=library_info, file_path=file_path)
+
+    async def _progress_library_through_lifecycle(  # noqa: C901, PLR0911, PLR0912, PLR0915 (lifecycle state machine needs branches/statements/returns)
+        self,
+        library_info: LibraryManager.LibraryInfo,
+        file_path: str,
+        request: RegisterLibraryFromFileRequest,
+    ) -> None | RegisterLibraryFromFileResultFailure:
+        """Progress library through lifecycle states until LOADED.
+
+        Advances library_info through states: DISCOVERED → METADATA_LOADED →
+        EVALUATED → DEPENDENCIES_INSTALLED → LOADED.
+
+        Modifies library_info in place as it progresses through states.
+
+        Returns:
+            None: Successfully progressed to LOADED state
+            RegisterLibraryFromFileResultFailure: Failed during progression
+        """
+        while True:
+            current_state = library_info.lifecycle_state
+
+            match current_state:
+                case LibraryManager.LibraryLifecycleState.LOADED:
+                    # Terminal state: inconsistent (marked LOADED but not in registry)
+                    details = f"Library '{library_info.library_name}' marked as LOADED but not in registry"
+                    self._library_file_path_to_info[library_info.library_path] = library_info
+                    return RegisterLibraryFromFileResultFailure(result_details=details)
+
+                case LibraryManager.LibraryLifecycleState.FAILURE:
+                    # Terminal state: failure
+                    details = f"Library '{library_info.library_name}' is in FAILURE state and cannot be loaded"
+                    self._library_file_path_to_info[library_info.library_path] = library_info
+                    return RegisterLibraryFromFileResultFailure(result_details=details)
+
+                case LibraryManager.LibraryLifecycleState.DISCOVERED:
+                    # DISCOVERED → METADATA_LOADED
+                    # All libraries (including sandbox) load metadata from JSON file
+                    metadata_result = self.load_library_metadata_from_file_request(
+                        LoadLibraryMetadataFromFileRequest(file_path=library_info.library_path)
                     )
-                    create_new_category_result = GriptapeNodes.handle_request(create_new_category_request)
-                    if not isinstance(create_new_category_result, SetConfigCategoryResultSuccess):
-                        problems.append(CreateConfigCategoryProblem(category_name=library_data_setting.category))
-                        details = f"Failed attempting to create new config category '{library_data_setting.category}' for library '{library_data.name}'."
-                        logger.error(details)
-                        continue  # SKIP IT
-                else:
-                    # We had an existing category. Union our changes into it (not replacing anything that matched).
-                    existing_category_contents = merge_dicts(
-                        library_data_setting.contents, get_category_result.contents, add_keys=True, merge_lists=True
+
+                    if isinstance(metadata_result, LoadLibraryMetadataFromFileResultFailure):
+                        self._library_file_path_to_info[library_info.library_path] = library_info
+                        return RegisterLibraryFromFileResultFailure(result_details=metadata_result.result_details)
+
+                    # Update library_info with metadata results
+                    library_info.library_name = metadata_result.library_schema.name
+                    library_info.library_version = metadata_result.library_schema.metadata.library_version
+                    library_info.lifecycle_state = LibraryManager.LibraryLifecycleState.METADATA_LOADED
+
+                case LibraryManager.LibraryLifecycleState.METADATA_LOADED:
+                    # METADATA_LOADED → EVALUATED
+                    # Need to load schema to pass to evaluate request
+                    metadata_result = self.load_library_metadata_from_file_request(
+                        LoadLibraryMetadataFromFileRequest(file_path=library_info.library_path)
+                    )
+
+                    if isinstance(metadata_result, LoadLibraryMetadataFromFileResultFailure):
+                        self._library_file_path_to_info[library_info.library_path] = library_info
+                        return RegisterLibraryFromFileResultFailure(result_details=metadata_result.result_details)
+
+                    evaluate_result = self.evaluate_library_fitness_request(
+                        EvaluateLibraryFitnessRequest(schema=metadata_result.library_schema)
                     )
-                    set_category_request = SetConfigCategoryRequest(
-                        category=library_data_setting.category, contents=existing_category_contents
+                    if isinstance(evaluate_result, EvaluateLibraryFitnessResultFailure):
+                        self._library_file_path_to_info[library_info.library_path] = library_info
+                        return RegisterLibraryFromFileResultFailure(result_details=evaluate_result.result_details)
+
+                    # Update library_info with evaluation results
+                    library_info.fitness = evaluate_result.fitness
+                    library_info.problems.extend(evaluate_result.problems)
+
+                    # Check if library requirements are met by the current system
+                    library_data = metadata_result.library_schema
+                    library_requirements = (
+                        library_data.metadata.resources.required
+                        if library_data.metadata.resources is not None
+                        else None
                     )
-                    set_category_result = GriptapeNodes.handle_request(set_category_request)
-                    if not isinstance(set_category_result, SetConfigCategoryResultSuccess):
-                        problems.append(UpdateConfigCategoryProblem(category_name=library_data_setting.category))
-                        details = f"Failed attempting to update config category '{library_data_setting.category}' for library '{library_data.name}'."
-                        logger.error(details)
-                        continue  # SKIP IT
-
-        # Attempt to load nodes from the library.
-        library_load_results = await asyncio.to_thread(
-            self._attempt_load_nodes_from_library,
-            library_data=library_data,
-            library=library,
-            base_dir=base_dir,
-            library_file_path=file_path,
-            library_version=library_version,
-            problems=problems,
-        )
-        self._library_file_path_to_info[file_path] = library_load_results
+                    if library_requirements is not None:
+                        requirements_check_result = self._check_library_requirements(
+                            library_requirements, library_data.name
+                        )
+                        if requirements_check_result is not None:
+                            library_info.fitness = LibraryManager.LibraryFitness.UNUSABLE
+                            library_info.problems.append(requirements_check_result)
+                            library_info.lifecycle_state = LibraryManager.LibraryLifecycleState.FAILURE
+                            self._library_file_path_to_info[library_info.library_path] = library_info
+                            details = f"Library '{library_data.name}' requirements not met: {library_requirements}"
+                            return RegisterLibraryFromFileResultFailure(result_details=details)
+
+                    library_info.lifecycle_state = LibraryManager.LibraryLifecycleState.EVALUATED
+
+                case LibraryManager.LibraryLifecycleState.EVALUATED:
+                    # EVALUATED → DEPENDENCIES_INSTALLED
+                    install_result = await self.install_library_dependencies_request(
+                        InstallLibraryDependenciesRequest(library_file_path=library_info.library_path)
+                    )
+                    if isinstance(install_result, InstallLibraryDependenciesResultFailure):
+                        self._library_file_path_to_info[library_info.library_path] = library_info
+                        return RegisterLibraryFromFileResultFailure(result_details=install_result.result_details)
 
-        match library_load_results.status:
-            case LibraryStatus.GOOD:
-                details = f"Successfully loaded Library '{library_data.name}' from JSON file at {json_path}"
-                return RegisterLibraryFromFileResultSuccess(
-                    library_name=library_data.name, result_details=ResultDetails(message=details, level=logging.INFO)
-                )
-            case LibraryStatus.FLAWED:
-                details = f"Successfully loaded Library JSON file from '{json_path}', but one or more nodes failed to load. Check the log for more details."
-                return RegisterLibraryFromFileResultSuccess(
-                    library_name=library_data.name, result_details=ResultDetails(message=details, level=logging.WARNING)
-                )
-            case LibraryStatus.UNUSABLE:
-                details = f"Attempted to load Library JSON file from '{json_path}'. Failed because no nodes were loaded. Check the log for more details."
-                return RegisterLibraryFromFileResultFailure(result_details=details)
-            case _:
-                details = f"Attempted to load Library JSON file from '{json_path}'. Failed because an unknown/unexpected status '{library_load_results.status}' was returned."
-                return RegisterLibraryFromFileResultFailure(result_details=details)
+                    # Update library_info
+                    library_info.lifecycle_state = LibraryManager.LibraryLifecycleState.DEPENDENCIES_INSTALLED
+
+                case LibraryManager.LibraryLifecycleState.DEPENDENCIES_INSTALLED:
+                    # DEPENDENCIES_INSTALLED → LOADED
+
+                    if not library_info.is_sandbox:
+                        # REGULAR LIBRARIES: Standard registration from JSON file
+                        # Load metadata and create library
+                        metadata_result = self.load_library_metadata_from_file_request(
+                            LoadLibraryMetadataFromFileRequest(file_path=library_info.library_path)
+                        )
+
+                        if isinstance(metadata_result, LoadLibraryMetadataFromFileResultFailure):
+                            self._library_file_path_to_info[library_info.library_path] = library_info
+                            return RegisterLibraryFromFileResultFailure(result_details=metadata_result.result_details)
+
+                        library_data = metadata_result.library_schema
+                        json_path = Path(file_path)
+                        base_dir = json_path.parent.absolute()
+
+                        # Add the directory to the Python path to allow for relative imports
+                        sys.path.insert(0, str(base_dir))
+
+                        # Add venv site-packages to sys.path if library has dependencies
+                        if library_data.metadata.dependencies and library_data.metadata.dependencies.pip_dependencies:
+                            venv_path = self._get_library_venv_path(library_data.name, file_path)
+                            if venv_path.exists():
+                                site_packages = str(
+                                    Path(
+                                        sysconfig.get_path(
+                                            "purelib",
+                                            vars={"base": str(venv_path), "platbase": str(venv_path)},
+                                        )
+                                    )
+                                )
+                                sys.path.insert(0, site_packages)
+                                logger.debug(
+                                    "Added library '%s' venv to sys.path: %s", library_data.name, site_packages
+                                )
+
+                        # Load the advanced library module if specified
+                        advanced_library_instance = None
+                        if library_data.advanced_library_path:
+                            try:
+                                advanced_library_instance = self._load_advanced_library_module(
+                                    library_data=library_data,
+                                    base_dir=base_dir,
+                                )
+                            except Exception as err:
+                                library_info.lifecycle_state = LibraryManager.LibraryLifecycleState.FAILURE
+                                library_info.fitness = LibraryManager.LibraryFitness.UNUSABLE
+                                library_info.problems.append(
+                                    AdvancedLibraryLoadFailureProblem(
+                                        advanced_library_path=library_data.advanced_library_path, error_message=str(err)
+                                    )
+                                )
+                                self._library_file_path_to_info[file_path] = library_info
+                                details = f"Attempted to load Library '{library_data.name}' from '{json_path}'. Failed to load Advanced Library module: {err}"
+                                return RegisterLibraryFromFileResultFailure(result_details=details)
+
+                        # Create or get the library
+                        try:
+                            library = LibraryRegistry.generate_new_library(
+                                library_data=library_data,
+                                mark_as_default_library=request.load_as_default_library,
+                                advanced_library=advanced_library_instance,
+                            )
+                        except KeyError as err:
+                            # Library already exists
+                            library_info.lifecycle_state = LibraryManager.LibraryLifecycleState.FAILURE
+                            library_info.fitness = LibraryManager.LibraryFitness.UNUSABLE
+                            library_info.problems.append(DuplicateLibraryProblem())
+                            self._library_file_path_to_info[file_path] = library_info
+                            details = f"Attempted to load Library JSON file from '{json_path}'. Failed because a Library '{library_data.name}' already exists. Error: {err}."
+                            return RegisterLibraryFromFileResultFailure(result_details=details)
+
+                        # Check the library's custom config settings
+                        if library_data.settings is not None:
+                            for library_data_setting in library_data.settings:
+                                # Does the category exist?
+                                get_category_request = GetConfigCategoryRequest(
+                                    category=library_data_setting.category,
+                                    failure_log_level=logging.DEBUG,
+                                )
+                                get_category_result = GriptapeNodes.handle_request(get_category_request)
+                                if not isinstance(get_category_result, GetConfigCategoryResultSuccess):
+                                    # Create new category
+                                    create_new_category_request = SetConfigCategoryRequest(
+                                        category=library_data_setting.category, contents=library_data_setting.contents
+                                    )
+                                    create_new_category_result = GriptapeNodes.handle_request(
+                                        create_new_category_request
+                                    )
+                                    if not isinstance(create_new_category_result, SetConfigCategoryResultSuccess):
+                                        library_info.problems.append(
+                                            CreateConfigCategoryProblem(category_name=library_data_setting.category)
+                                        )
+                                        details = f"Failed attempting to create new config category '{library_data_setting.category}' for library '{library_data.name}'."
+                                        logger.error(details)
+                                        continue
+                                else:
+                                    # Merge with existing category
+                                    existing_category_contents = merge_dicts(
+                                        library_data_setting.contents,
+                                        get_category_result.contents,
+                                        add_keys=True,
+                                        merge_lists=True,
+                                    )
+                                    set_category_request = SetConfigCategoryRequest(
+                                        category=library_data_setting.category, contents=existing_category_contents
+                                    )
+                                    set_category_result = GriptapeNodes.handle_request(set_category_request)
+                                    if not isinstance(set_category_result, SetConfigCategoryResultSuccess):
+                                        library_info.problems.append(
+                                            UpdateConfigCategoryProblem(category_name=library_data_setting.category)
+                                        )
+                                        details = f"Failed attempting to update config category '{library_data_setting.category}' for library '{library_data.name}'."
+                                        logger.error(details)
+                                        continue
+
+                        # Attempt to load nodes from the library (modifies library_info in place)
+                        await asyncio.to_thread(
+                            self._attempt_load_nodes_from_library,
+                            library_data=library_data,
+                            library=library,
+                            base_dir=base_dir,
+                            library_info=library_info,
+                        )
+                        self._library_file_path_to_info[file_path] = library_info
+                    else:
+                        # SANDBOX LIBRARIES: Full processing here (discovery + registration)
+                        # Load metadata from JSON file (already generated in DISCOVERED → METADATA_LOADED)
+                        sandbox_directory = Path(library_info.library_path).parent
+                        metadata_result = self.load_library_metadata_from_file_request(
+                            LoadLibraryMetadataFromFileRequest(file_path=library_info.library_path)
+                        )
+
+                        if isinstance(metadata_result, LoadLibraryMetadataFromFileResultFailure):
+                            self._library_file_path_to_info[library_info.library_path] = library_info
+                            return RegisterLibraryFromFileResultFailure(result_details=metadata_result.result_details)
+
+                        # Discover real class names by importing files
+                        await self._attempt_generate_sandbox_library_from_schema(
+                            library_schema=metadata_result.library_schema,
+                            sandbox_directory=str(sandbox_directory),
+                            library_info=library_info,
+                        )
+                        # Function handles registration and updates library_info with problems
+                        # lifecycle_state set to LOADED by _attempt_load_nodes_from_library
+
+                    # Exit loop after final phase
+                    break
+
+                case _:
+                    # Unexpected state
+                    msg = f"Library '{library_info.library_name}' in unexpected lifecycle state: {current_state}"
+                    raise ValueError(msg)
+
+        # Success - progressed to LOADED state
+        return None
 
     async def register_library_from_requirement_specifier_request(
         self, request: RegisterLibraryFromRequirementSpecifierRequest
@@ -1174,6 +1678,106 @@ class LibraryManager:
 
         return library_venv_python_path
 
+    def _check_library_requirements(
+        self, requirements: dict[str, Any], library_name: str
+    ) -> IncompatibleRequirementsProblem | None:
+        """Check if the current system meets the library's resource requirements.
+
+        Args:
+            requirements: Dictionary of requirements in the format used by resource_instance.Requirements
+            library_name: Name of the library being checked (for logging)
+
+        Returns:
+            IncompatibleRequirementsProblem if requirements are not met, None if they are met
+        """
+        logger.info("Checking requirements for library '%s': %s", library_name, requirements)
+
+        os_keys = {"platform", "arch", "version"}
+        compute_keys = {"compute"}
+
+        os_requirements = {k: v for k, v in requirements.items() if k in os_keys}
+        compute_requirements = {k: v for k, v in requirements.items() if k in compute_keys}
+
+        if os_requirements:
+            list_request = ListCompatibleResourceInstancesRequest(
+                resource_type_name="OSResourceType",
+                requirements=os_requirements,
+                include_locked=True,
+            )
+            result = GriptapeNodes.handle_request(list_request)
+
+            if isinstance(result, ListCompatibleResourceInstancesResultSuccess) and not result.instance_ids:
+                system_capabilities = self._get_system_capabilities()
+                logger.warning(
+                    "Library '%s' OS requirements not met. Required: %s, System: %s",
+                    library_name,
+                    os_requirements,
+                    system_capabilities,
+                )
+                return IncompatibleRequirementsProblem(
+                    requirements=requirements,
+                    system_capabilities=system_capabilities,
+                )
+
+        if compute_requirements:
+            list_request = ListCompatibleResourceInstancesRequest(
+                resource_type_name="ComputeResourceType",
+                requirements=compute_requirements,
+                include_locked=True,
+            )
+            result = GriptapeNodes.handle_request(list_request)
+
+            if isinstance(result, ListCompatibleResourceInstancesResultSuccess) and not result.instance_ids:
+                system_capabilities = self._get_system_capabilities()
+                logger.warning(
+                    "Library '%s' compute requirements not met. Required: %s, System: %s",
+                    library_name,
+                    compute_requirements,
+                    system_capabilities,
+                )
+                return IncompatibleRequirementsProblem(
+                    requirements=requirements,
+                    system_capabilities=system_capabilities,
+                )
+
+        return None
+
+    def _get_system_capabilities(self) -> dict[str, Any]:
+        """Get the current system's capabilities for error reporting.
+
+        Returns:
+            Dictionary of combined OS and compute capabilities or empty dict if unavailable
+        """
+        capabilities: dict[str, Any] = {}
+
+        os_list_request = ListCompatibleResourceInstancesRequest(
+            resource_type_name="OSResourceType",
+            requirements=None,
+            include_locked=True,
+        )
+        os_result = GriptapeNodes.handle_request(os_list_request)
+
+        if isinstance(os_result, ListCompatibleResourceInstancesResultSuccess) and os_result.instance_ids:
+            status_request = GetResourceInstanceStatusRequest(instance_id=os_result.instance_ids[0])
+            status_result = GriptapeNodes.handle_request(status_request)
+            if isinstance(status_result, GetResourceInstanceStatusResultSuccess):
+                capabilities.update(status_result.status.capabilities)
+
+        compute_list_request = ListCompatibleResourceInstancesRequest(
+            resource_type_name="ComputeResourceType",
+            requirements=None,
+            include_locked=True,
+        )
+        compute_result = GriptapeNodes.handle_request(compute_list_request)
+
+        if isinstance(compute_result, ListCompatibleResourceInstancesResultSuccess) and compute_result.instance_ids:
+            status_request = GetResourceInstanceStatusRequest(instance_id=compute_result.instance_ids[0])
+            status_result = GriptapeNodes.handle_request(status_request)
+            if isinstance(status_result, GetResourceInstanceStatusResultSuccess):
+                capabilities.update(status_result.status.capabilities)
+
+        return capabilities
+
     def _get_library_venv_path(self, library_name: str, library_file_path: str | None = None) -> Path:
         """Get the path to the virtual environment directory for a library.
 
@@ -1626,113 +2230,89 @@ class LibraryManager:
     async def load_all_libraries_from_config(self) -> None:
         self._libraries_loading_complete.clear()
 
-        try:
-            # Load metadata for all libraries to determine which ones can be safely loaded
-            metadata_request = LoadMetadataForAllLibrariesRequest()
-            metadata_result = self.load_metadata_for_all_libraries_request(metadata_request)
-
-            # Check if metadata loading succeeded
-            if not isinstance(metadata_result, LoadMetadataForAllLibrariesResultSuccess):
-                logger.error("Failed to load metadata for all libraries, skipping library registration")
-                return
-
-            # Record all failed libraries in our tracking immediately
-            for failed_library in metadata_result.failed_libraries:
-                self._library_file_path_to_info[failed_library.library_path] = LibraryManager.LibraryInfo(
-                    library_path=failed_library.library_path,
-                    library_name=failed_library.library_name,
-                    status=failed_library.status,
-                    problems=failed_library.problems,
-                )
+        # Discover all available libraries (config + sandbox)
+        discover_result = self.discover_libraries_request(DiscoverLibrariesRequest())
+        if isinstance(discover_result, DiscoverLibrariesResultFailure):
+            logger.error("Failed to discover libraries: %s", discover_result.result_details)
+            self._libraries_loading_complete.set()
+            return
+
+        # Build list of library paths to load
+        libraries_to_load = []
+        for discovered_lib in discover_result.libraries_discovered:
+            lib_path = str(discovered_lib.path)
+            lib_info = self._library_file_path_to_info.get(lib_path)
+
+            if lib_info:
+                libraries_to_load.append(lib_path)
 
-            # Calculate total libraries for progress tracking
-            total_libraries = len(metadata_result.successful_libraries)
+        if not libraries_to_load:
+            logger.info("No libraries found in configuration.")
+            self._libraries_loading_complete.set()
+            return
 
-            # Use metadata results to selectively load libraries
-            for current_library_index, library_result in enumerate(metadata_result.successful_libraries, start=1):
-                library_name = library_result.library_schema.name
+        # Calculate total libraries for progress tracking
+        total_libraries = len(libraries_to_load)
+
+        # Load each discovered library by path (RegisterLibraryFromFileRequest will handle metadata loading)
+        for current_library_index, lib_path in enumerate(libraries_to_load, start=1):
+            # Load the library through unified lifecycle using library_path
+            # RegisterLibraryFromFileRequest will handle metadata loading internally to get library_name
+            load_result = await self.register_library_from_file_request(
+                RegisterLibraryFromFileRequest(
+                    file_path=lib_path,
+                    load_as_default_library=False,
+                )
+            )
 
-                # Emit loading event
+            # Handle failure case first
+            if isinstance(load_result, RegisterLibraryFromFileResultFailure):
+                logger.warning("Failed to load library at '%s': %s", lib_path, load_result.result_details)
+                error_message = (
+                    load_result.result_details.result_details[0].message
+                    if isinstance(load_result.result_details, ResultDetails)
+                    else str(load_result.result_details)
+                )
                 GriptapeNodes.EventManager().put_event(
                     AppEvent(
                         payload=EngineInitializationProgress(
                             phase=InitializationPhase.LIBRARIES,
-                            item_name=library_name,
-                            status=InitializationStatus.LOADING,
+                            item_name=lib_path,  # Use path as fallback since we don't have library_name
+                            status=InitializationStatus.FAILED,
                             current=current_library_index,
                             total=total_libraries,
+                            error=error_message,
                         )
                     )
                 )
+                continue
 
-                # Register the library
-                if library_result.library_schema.name == LibraryManager.SANDBOX_LIBRARY_NAME:
-                    # Handle sandbox library - use the schema we already have
-                    await self._attempt_generate_sandbox_library_from_schema(
-                        library_schema=library_result.library_schema, sandbox_directory=library_result.file_path
-                    )
-                    # Emit success event for sandbox library
-                    GriptapeNodes.EventManager().put_event(
-                        AppEvent(
-                            payload=EngineInitializationProgress(
-                                phase=InitializationPhase.LIBRARIES,
-                                item_name=library_name,
-                                status=InitializationStatus.COMPLETE,
-                                current=current_library_index,
-                                total=total_libraries,
-                            )
+            # Success case - narrow type and get library_name from result
+            if isinstance(load_result, RegisterLibraryFromFileResultSuccess):
+                library_name = load_result.library_name
+
+                # Emit success event
+                GriptapeNodes.EventManager().put_event(
+                    AppEvent(
+                        payload=EngineInitializationProgress(
+                            phase=InitializationPhase.LIBRARIES,
+                            item_name=library_name,
+                            status=InitializationStatus.COMPLETE,
+                            current=current_library_index,
+                            total=total_libraries,
                         )
                     )
-                else:
-                    # Handle config-based library - register it directly using the file path
-                    register_request = RegisterLibraryFromFileRequest(
-                        file_path=library_result.file_path, load_as_default_library=False
-                    )
-                    register_result = await self.register_library_from_file_request(register_request)
-                    if isinstance(register_result, RegisterLibraryFromFileResultFailure):
-                        # Registration failed - the failure info is already recorded in _library_file_path_to_info
-                        # by register_library_from_file_request, so we just log it here for visibility
-                        logger.warning("Failed to register library from %s", library_result.file_path)
-                        # Emit failure event
-                        error_message = (
-                            register_result.result_details.result_details[0].message
-                            if isinstance(register_result.result_details, ResultDetails)
-                            else register_result.result_details
-                        )
-                        GriptapeNodes.EventManager().put_event(
-                            AppEvent(
-                                payload=EngineInitializationProgress(
-                                    phase=InitializationPhase.LIBRARIES,
-                                    item_name=library_name,
-                                    status=InitializationStatus.FAILED,
-                                    current=current_library_index,
-                                    total=total_libraries,
-                                    error=error_message,
-                                )
-                            )
-                        )
-                    else:
-                        # Emit success event
-                        GriptapeNodes.EventManager().put_event(
-                            AppEvent(
-                                payload=EngineInitializationProgress(
-                                    phase=InitializationPhase.LIBRARIES,
-                                    item_name=library_name,
-                                    status=InitializationStatus.COMPLETE,
-                                    current=current_library_index,
-                                    total=total_libraries,
-                                )
-                            )
-                        )
+                )
 
-            # Print 'em all pretty
-            self.print_library_load_status()
+        # Print 'em all pretty
+        self.print_library_load_status()
 
-            # Remove any missing libraries AFTER we've printed them for the user.
-            user_libraries_section = LIBRARIES_TO_REGISTER_KEY
-            self._remove_missing_libraries_from_config(config_category=user_libraries_section)
-        finally:
-            self._libraries_loading_complete.set()
+        # Remove any missing libraries AFTER we've printed them for the user.
+        user_libraries_section = LIBRARIES_TO_REGISTER_KEY
+        self._remove_missing_libraries_from_config(config_category=user_libraries_section)
+
+        # Mark libraries loading as complete
+        self._libraries_loading_complete.set()
 
     async def _ensure_libraries_from_config(self) -> None:
         """Ensure libraries from git URLs specified in config are downloaded.
@@ -1923,86 +2503,6 @@ class LibraryManager:
         )
         console.print(message)
 
-    async def _load_libraries_from_provenance_system(self) -> None:
-        """Load libraries using the new provenance-based system with FSM.
-
-        This method converts libraries_to_register entries into LibraryProvenanceLocalFile
-        objects and processes them through the LibraryDirectory and LibraryLifecycleFSM systems.
-        """
-        # Get config manager
-        config_mgr = GriptapeNodes.ConfigManager()
-
-        # Get the current libraries_to_register list
-        user_libraries_section = LIBRARIES_TO_REGISTER_KEY
-        libraries_to_register: list[str] = config_mgr.get_config_value(user_libraries_section)
-
-        # Filter out empty or whitespace-only entries
-        original_count = len(libraries_to_register) if libraries_to_register else 0
-        libraries_to_register = [path for path in (libraries_to_register or []) if path and path.strip()]
-        filtered_count = original_count - len(libraries_to_register)
-        if filtered_count > 0:
-            logger.warning("Filtered out %d empty library path entries from configuration", filtered_count)
-
-        if not libraries_to_register:
-            logger.info("No libraries to register from config")
-            return
-
-        # Convert string paths to LibraryProvenanceLocalFile objects
-        for library_path in libraries_to_register:
-            # Skip non-JSON files for now (requirement specifiers will need different handling)
-            if not library_path.endswith(".json"):
-                logger.debug("Skipping non-JSON library path: %s", library_path)
-                continue
-
-            # Create provenance object
-            provenance = LibraryProvenanceLocalFile(file_path=library_path)
-
-            # Add to directory as user candidate (defaults to active=True)
-            # This automatically creates FSM and runs evaluation
-            await self._library_directory.add_user_candidate(provenance)
-
-            logger.debug("Added library provenance: %s", provenance.get_display_name())
-
-        # Get all candidates for evaluation
-        all_candidates = self._library_directory.get_all_candidates()
-
-        logger.info("Evaluated %d library candidates through FSM lifecycle", len(all_candidates))
-
-        # Report on conflicts found
-        self._report_library_name_conflicts()
-
-        # Get candidates that are ready for installation
-        installable_candidates = self._library_directory.get_installable_candidates()
-
-        # Log any skipped libraries
-        active_candidates = self._library_directory.get_active_candidates()
-        for candidate in active_candidates:
-            if candidate not in installable_candidates:
-                blockers = self._library_directory.get_installation_blockers(candidate.provenance)
-                if blockers:
-                    blocker_messages = [blocker.message for blocker in blockers]
-                    combined_message = "; ".join(blocker_messages)
-                    logger.info("Skipping library '%s' - %s", candidate.provenance.get_display_name(), combined_message)
-
-        logger.info("Installing and loading %d installable library candidates", len(installable_candidates))
-
-        # Process installable candidates through installation and loading
-        for candidate in installable_candidates:
-            if await self._library_directory.install_library(candidate.provenance):
-                await self._library_directory.load_library(candidate.provenance)
-
-    def _report_library_name_conflicts(self) -> None:
-        """Report on library name conflicts found during evaluation."""
-        conflicting_names = self._library_directory.get_all_conflicting_library_names()
-        for library_name in conflicting_names:
-            conflicting_provenances = self._library_directory.get_conflicting_provenances(library_name)
-            logger.warning(
-                "Library name conflict detected for '%s' across %d libraries: %s",
-                library_name,
-                len(conflicting_provenances),
-                [p.get_display_name() for p in conflicting_provenances],
-            )
-
     def _load_advanced_library_module(
         self,
         library_data: LibrarySchema,
@@ -2069,54 +2569,42 @@ class LibraryManager:
 
         return advanced_library_instance
 
-    def _attempt_load_nodes_from_library(  # noqa: PLR0913, PLR0912, PLR0915, C901
+    def _attempt_load_nodes_from_library(  # noqa: PLR0912, PLR0915, C901
         self,
         library_data: LibrarySchema,
         library: Library,
         base_dir: Path,
-        library_file_path: str,
-        library_version: str | None,
-        problems: list[LibraryProblem],
-    ) -> LibraryManager.LibraryInfo:
-        any_nodes_loaded_successfully = False
+        library_info: LibraryInfo,
+    ) -> None:
+        """Load nodes from library and update library_info in place.
 
-        # Check for version-based compatibility issues and add to problems
-        version_issues = GriptapeNodes.VersionCompatibilityManager().check_library_version_compatibility(library_data)
-        has_disqualifying_issues = False
-        for issue in version_issues:
-            problems.append(issue.problem)
-            if issue.severity == LibraryStatus.UNUSABLE:
-                has_disqualifying_issues = True
+        Args:
+            library_data: Library schema with node definitions
+            library: Library instance to register nodes with
+            base_dir: Base directory for resolving relative paths
+            library_info: LibraryInfo to update with problems and fitness
+        """
+        any_nodes_loaded_successfully = False
 
         # Check if library is in old XDG location
         old_xdg_libraries_path = xdg_data_home() / "griptape_nodes" / "libraries"
-        library_path_obj = Path(library_file_path)
+        library_path_obj = Path(library_info.library_path)
         try:
             # Check if the library path is relative to the old XDG location
             if library_path_obj.is_relative_to(old_xdg_libraries_path):
-                problems.append(OldXdgLocationWarningProblem(old_path=str(library_path_obj)))
+                library_info.problems.append(OldXdgLocationWarningProblem(old_path=str(library_path_obj)))
                 logger.warning(
                     "Library '%s' is located in old XDG data directory: %s. "
                     "Starting with version 0.65.0, libraries are managed in your workspace directory. "
                     "To migrate: run 'gtn init' (CLI) or go to App Settings and click 'Re-run Setup Wizard' (desktop app).",
                     library_data.name,
-                    library_file_path,
+                    library_info.library_path,
                 )
         except ValueError:
             # is_relative_to() raises ValueError if paths are on different drives
             # In this case, library is definitely not in the old XDG location
             pass
 
-        # Early exit if any version issues are disqualifying
-        if has_disqualifying_issues:
-            return LibraryManager.LibraryInfo(
-                library_path=library_file_path,
-                library_name=library_data.name,
-                library_version=library_version,
-                status=LibraryStatus.UNUSABLE,
-                problems=problems,
-            )
-
         # Call the before_library_nodes_loaded callback if available
         advanced_library = library.get_advanced_library()
         if advanced_library:
@@ -2125,7 +2613,7 @@ class LibraryManager:
                 details = f"Successfully called before_library_nodes_loaded callback for library '{library_data.name}'"
                 logger.debug(details)
             except Exception as err:
-                problems.append(BeforeLibraryCallbackProblem(error_message=str(err)))
+                library_info.problems.append(BeforeLibraryCallbackProblem(error_message=str(err)))
                 details = (
                     f"Failed to call before_library_nodes_loaded callback for library '{library_data.name}': {err}"
                 )
@@ -2143,7 +2631,7 @@ class LibraryManager:
                 node_class = self._load_class_from_file(node_file_path, node_definition.class_name, library_data.name)
             except ImportError as err:
                 root_cause = self._get_root_cause_from_exception(err)
-                problems.append(
+                library_info.problems.append(
                     NodeModuleImportProblem(
                         class_name=node_definition.class_name,
                         file_path=str(node_file_path),
@@ -2155,14 +2643,14 @@ class LibraryManager:
                 logger.error(details)
                 continue  # SKIP IT
             except AttributeError:
-                problems.append(
+                library_info.problems.append(
                     NodeClassNotFoundProblem(class_name=node_definition.class_name, file_path=str(node_file_path))
                 )
                 details = f"Attempted to load node '{node_definition.class_name}' from '{node_file_path}'. Failed because class not found in module"
                 logger.error(details)
                 continue  # SKIP IT
             except TypeError:
-                problems.append(
+                library_info.problems.append(
                     NodeClassNotBaseNodeProblem(class_name=node_definition.class_name, file_path=str(node_file_path))
                 )
                 details = f"Attempted to load node '{node_definition.class_name}' from '{node_file_path}'. Failed because class doesn't inherit from BaseNode"
@@ -2172,7 +2660,7 @@ class LibraryManager:
             # Register the node type with the library
             library_problem = library.register_new_node_type(node_class, metadata=node_definition.metadata)
             if library_problem is not None:
-                problems.append(library_problem)
+                library_info.problems.append(library_problem)
 
             # If we got here, at least one node came in.
             any_nodes_loaded_successfully = True
@@ -2184,49 +2672,46 @@ class LibraryManager:
                 details = f"Successfully called after_library_nodes_loaded callback for library '{library_data.name}'"
                 logger.debug(details)
             except Exception as err:
-                problems.append(AfterLibraryCallbackProblem(error_message=str(err)))
+                library_info.problems.append(AfterLibraryCallbackProblem(error_message=str(err)))
                 details = f"Failed to call after_library_nodes_loaded callback for library '{library_data.name}': {err}"
                 logger.error(details)
 
-        # Create a LibraryInfo object based on load successes and problem count.
+        # Update library_info fitness based on load successes and problem count
         if not any_nodes_loaded_successfully:
-            status = LibraryStatus.UNUSABLE
-        elif problems:
+            library_info.fitness = LibraryManager.LibraryFitness.UNUSABLE
+        elif library_info.problems:
             # Success, but errors.
-            status = LibraryStatus.FLAWED
+            library_info.fitness = LibraryManager.LibraryFitness.FLAWED
         else:
             # Flawless victory.
-            status = LibraryStatus.GOOD
-
-        # Create a LibraryInfo object based on load successes and problem count.
-        return LibraryManager.LibraryInfo(
-            library_path=library_file_path,
-            library_name=library_data.name,
-            library_version=library_version,
-            status=status,
-            problems=problems,
-        )
+            library_info.fitness = LibraryManager.LibraryFitness.GOOD
 
-    async def _attempt_generate_sandbox_library_from_schema(
-        self, library_schema: LibrarySchema, sandbox_directory: str
+        # Update lifecycle state to LOADED
+        library_info.lifecycle_state = LibraryManager.LibraryLifecycleState.LOADED
+
+    async def _attempt_generate_sandbox_library_from_schema(  # noqa: C901
+        self,
+        library_schema: LibrarySchema,
+        sandbox_directory: str,
+        library_info: LibraryInfo,
     ) -> None:
         """Generate sandbox library using an existing schema, loading actual node classes."""
         sandbox_library_dir = Path(sandbox_directory)
-        sandbox_library_dir_as_posix = sandbox_library_dir.as_posix()
 
         problems = []
 
         # Get the file paths from the schema's node definitions to load actual classes
         actual_node_definitions = []
         for node_def in library_schema.nodes:
-            candidate_path = Path(node_def.file_path)
+            # Resolve relative path from schema against sandbox directory
+            candidate_path = sandbox_library_dir / node_def.file_path
             try:
                 module = self._load_module_from_file(candidate_path, LibraryManager.SANDBOX_LIBRARY_NAME)
             except Exception as err:
                 root_cause = self._get_root_cause_from_exception(err)
                 problems.append(
                     NodeModuleImportProblem(
-                        class_name=node_def.class_name,
+                        class_name=f"<Sandbox node in '{node_def.file_path}'>",
                         file_path=str(candidate_path),
                         error_message=str(err),
                         root_cause=str(root_cause),
@@ -2247,29 +2732,38 @@ class LibraryManager:
                     details = f"Found node '{class_name}' in sandbox library '{candidate_path}'."
                     logger.debug(details)
 
-                    # Get metadata from class attributes if they exist, otherwise use defaults
-                    node_icon = getattr(obj, "ICON", "square-dashed")
-                    node_description = getattr(
-                        obj, "DESCRIPTION", f"'{class_name}' (loaded from the {LibraryManager.SANDBOX_LIBRARY_NAME})."
-                    )
-                    node_color = getattr(obj, "COLOR", None)
-
-                    node_metadata = NodeMetadata(
-                        category="Griptape Nodes Sandbox",
-                        description=node_description,
-                        display_name=class_name,
-                        icon=node_icon,
-                        color=node_color,
-                    )
+                    # Look for existing node definition to preserve user-edited metadata
+                    existing_node = None
+                    for existing_node_def in library_schema.nodes:
+                        if (
+                            existing_node_def.file_path == str(candidate_path)
+                            and existing_node_def.class_name == class_name
+                        ):
+                            existing_node = existing_node_def
+                            break
+
+                    if existing_node:
+                        # PRESERVE existing metadata - user may have customized it
+                        node_metadata = existing_node.metadata
+                        logger.debug("Preserving existing metadata for node '%s'", class_name)
+                    else:
+                        # NEW node - create default metadata
+                        node_metadata = NodeMetadata(
+                            category=self.SANDBOX_CATEGORY_NAME,
+                            description=f"'{class_name}' (loaded from the {LibraryManager.SANDBOX_LIBRARY_NAME}).",
+                            display_name=class_name,
+                        )
+                        logger.debug("Creating new metadata for node '%s'", class_name)
+
                     node_definition = NodeDefinition(
                         class_name=class_name,
-                        file_path=str(candidate_path),
+                        file_path=node_def.file_path,  # Keep original relative path from schema
                         metadata=node_metadata,
                     )
                     actual_node_definitions.append(node_definition)
 
         if not actual_node_definitions:
-            logger.info("No nodes found in sandbox library '%s'. Skipping.", sandbox_library_dir)
+            logger.debug("No nodes found in sandbox library '%s'. Skipping.", sandbox_library_dir)
             return
 
         # Use the existing schema but replace nodes with actual discovered ones
@@ -2281,6 +2775,16 @@ class LibraryManager:
             nodes=actual_node_definitions,
         )
 
+        # Save the schema with real class names back to disk
+        json_path = sandbox_library_dir / LibraryManager.LIBRARY_CONFIG_FILENAME
+        write_succeeded = self._write_library_schema_to_json(library_data, json_path)
+        if write_succeeded:
+            logger.debug(
+                "Saved sandbox library schema with %d discovered nodes to '%s'",
+                len(actual_node_definitions),
+                json_path,
+            )
+
         # Register the library.
         # Create or get the library
         try:
@@ -2291,30 +2795,27 @@ class LibraryManager:
             )
 
         except KeyError as err:
-            # Library already exists
-            self._library_file_path_to_info[sandbox_library_dir_as_posix] = LibraryManager.LibraryInfo(
-                library_path=sandbox_library_dir_as_posix,
-                library_name=library_data.name,
-                library_version=library_data.metadata.library_version,
-                status=LibraryStatus.UNUSABLE,
-                problems=[DuplicateLibraryProblem()],
-            )
+            # Library already exists - update existing library_info
+            library_info.lifecycle_state = LibraryManager.LibraryLifecycleState.FAILURE
+            library_info.fitness = LibraryManager.LibraryFitness.UNUSABLE
+            library_info.problems.append(DuplicateLibraryProblem())
 
             details = f"Attempted to load Library JSON file from '{sandbox_library_dir}'. Failed because a Library '{library_data.name}' already exists. Error: {err}."
             logger.error(details)
             return
 
-        # Load nodes into the library
-        library_load_results = await asyncio.to_thread(
+        # Add any problems encountered during node discovery to library_info
+        library_info.problems.extend(problems)
+
+        # Load nodes into the library (modifies library_info in place)
+        # Note: library_info is passed as parameter from lifecycle handler
+        await asyncio.to_thread(
             self._attempt_load_nodes_from_library,
             library_data=library_data,
             library=library,
             base_dir=sandbox_library_dir,
-            library_file_path=sandbox_library_dir_as_posix,
-            library_version=library_data.metadata.library_version,
-            problems=problems,
+            library_info=library_info,
         )
-        self._library_file_path_to_info[sandbox_library_dir_as_posix] = library_load_results
 
     def _find_files_in_dir(self, directory: Path, extension: str) -> list[Path]:
         """Find all files with given extension in directory, excluding common non-source directories."""
@@ -2330,6 +2831,29 @@ class LibraryManager:
                     ret_val.append(file_path)
         return ret_val
 
+    def _write_library_schema_to_json(self, library_schema: LibrarySchema, json_path: Path) -> bool:
+        """Write library schema to JSON file using WriteFileRequest.
+
+        Args:
+            library_schema: The library schema to write
+            json_path: Path where the JSON file should be written
+
+        Returns:
+            True if write succeeded, False otherwise
+        """
+        write_request = WriteFileRequest(
+            file_path=str(json_path),
+            content=library_schema.model_dump_json(indent=2),
+            encoding="utf-8",
+        )
+        write_result = GriptapeNodes.handle_request(write_request)
+
+        if write_result.failed():
+            logger.error("Failed to write library schema to '%s': %s", json_path, write_result.result_details)
+            return False
+
+        return True
+
     def _remove_missing_libraries_from_config(self, config_category: str) -> None:
         # Now remove all libraries that were missing from the user's config.
         config_mgr = GriptapeNodes.ConfigManager()
@@ -2337,7 +2861,7 @@ class LibraryManager:
 
         paths_to_remove = set()
         for library_path, library_info in self._library_file_path_to_info.items():
-            if library_info.status == LibraryStatus.MISSING:
+            if library_info.fitness == LibraryManager.LibraryFitness.MISSING:
                 # Remove this file path from the config.
                 paths_to_remove.add(library_path.lower())
 
@@ -2461,24 +2985,236 @@ class LibraryManager:
         )
         return ReloadAllLibrariesResultSuccess(result_details=ResultDetails(message=details, level=logging.INFO))
 
-    async def load_libraries_request(self, request: LoadLibrariesRequest) -> ResultPayload:  # noqa: ARG002
-        # Check if there are any new libraries in config that haven't been loaded yet
-        discovered_libraries = {str(path) for path in self._discover_library_files()}
-        loaded_libraries = set(self._library_file_path_to_info.keys())
-        unloaded_libraries = discovered_libraries - loaded_libraries
-
-        if not unloaded_libraries:
-            details = "All configured libraries are already loaded, no action needed."
-            return LoadLibrariesResultSuccess(result_details=ResultDetails(message=details, level=logging.INFO))
+    def discover_libraries_request(
+        self,
+        request: DiscoverLibrariesRequest,
+    ) -> DiscoverLibrariesResultSuccess | DiscoverLibrariesResultFailure:
+        """Discover libraries from config and track them in discovered state.
 
+        This is the event handler for DiscoverLibrariesRequest.
+        Scans configured library paths and creates LibraryInfo entries in DISCOVERED state.
+        """
         try:
-            await self.load_all_libraries_from_config()
-            details = "Successfully loaded all libraries from configuration."
-            return LoadLibrariesResultSuccess(result_details=ResultDetails(message=details, level=logging.INFO))
+            config_library_paths = set(self._discover_library_files())
         except Exception as e:
-            details = f"Failed to load libraries from configuration: {e}"
-            logger.error(details)
-            return LoadLibrariesResultFailure(result_details=details)
+            logger.exception("Failed to discover library files")
+            return DiscoverLibrariesResultFailure(
+                result_details=f"Failed to discover library files: {e}",
+            )
+
+        discovered_libraries = set()
+
+        # Process sandbox library first if requested
+        if request.include_sandbox:
+            sandbox_library_dir = self._get_sandbox_directory()
+            if sandbox_library_dir:
+                # Generate/update the sandbox library JSON file
+                metadata_result = self.scan_sandbox_directory_request(
+                    ScanSandboxDirectoryRequest(directory_path=str(sandbox_library_dir))
+                )
+
+                # If generation succeeded, write JSON and add the sandbox library
+                if isinstance(metadata_result, ScanSandboxDirectoryResultSuccess):
+                    sandbox_json_path = sandbox_library_dir / LibraryManager.LIBRARY_CONFIG_FILENAME
+                    sandbox_json_path_str = str(sandbox_json_path)
+
+                    # Write the schema to JSON so it exists for lifecycle phases
+                    write_succeeded = self._write_library_schema_to_json(
+                        metadata_result.library_schema, sandbox_json_path
+                    )
+                    if write_succeeded:
+                        logger.debug(
+                            "Wrote sandbox library schema with %d nodes to '%s' during discovery",
+                            len(metadata_result.library_schema.nodes),
+                            sandbox_json_path,
+                        )
+                    # Continue anyway if write failed - lifecycle will fail gracefully
+
+                    # Add to discovered libraries with is_sandbox=True
+                    discovered_libraries.add(DiscoveredLibrary(path=sandbox_json_path, is_sandbox=True))
+
+                    # Create minimal LibraryInfo entry in discovered state if not already tracked
+                    if sandbox_json_path_str not in self._library_file_path_to_info:
+                        self._library_file_path_to_info[sandbox_json_path_str] = LibraryManager.LibraryInfo(
+                            lifecycle_state=LibraryManager.LibraryLifecycleState.DISCOVERED,
+                            fitness=LibraryManager.LibraryFitness.NOT_EVALUATED,
+                            library_path=sandbox_json_path_str,
+                            is_sandbox=True,
+                            library_name=None,
+                            library_version=None,
+                        )
+
+        # Add all regular libraries from config
+        for file_path in config_library_paths:
+            file_path_str = str(file_path)
+
+            # Add to discovered libraries with is_sandbox=False
+            discovered_libraries.add(DiscoveredLibrary(path=file_path, is_sandbox=False))
+
+            # Skip if already tracked
+            if file_path_str in self._library_file_path_to_info:
+                continue
+
+            # Create minimal LibraryInfo entry in discovered state
+            self._library_file_path_to_info[file_path_str] = LibraryManager.LibraryInfo(
+                lifecycle_state=LibraryManager.LibraryLifecycleState.DISCOVERED,
+                fitness=LibraryManager.LibraryFitness.NOT_EVALUATED,
+                library_path=file_path_str,
+                is_sandbox=False,
+                library_name=None,
+                library_version=None,
+            )
+
+        # Success path at the end
+        return DiscoverLibrariesResultSuccess(
+            result_details=f"Discovered {len(discovered_libraries)} libraries",
+            libraries_discovered=discovered_libraries,
+        )
+
+    def evaluate_library_fitness_request(
+        self, request: EvaluateLibraryFitnessRequest
+    ) -> EvaluateLibraryFitnessResultSuccess | EvaluateLibraryFitnessResultFailure:
+        """Evaluate library fitness using version compatibility checks.
+
+        Extracts version checking logic from _attempt_load_nodes_from_library.
+        Checks engine version compatibility without loading Python modules.
+        """
+        schema = request.schema
+        problems: list[LibraryProblem] = []
+
+        # Check for version-based compatibility issues
+        version_issues = GriptapeNodes.VersionCompatibilityManager().check_library_version_compatibility(schema)
+        has_disqualifying_issues = False
+
+        for issue in version_issues:
+            problems.append(issue.problem)
+            if issue.severity == LibraryManager.LibraryFitness.UNUSABLE:
+                has_disqualifying_issues = True
+
+        if has_disqualifying_issues:
+            return EvaluateLibraryFitnessResultFailure(
+                result_details=f"Library '{schema.name}' has version compatibility issues",
+                fitness=LibraryManager.LibraryFitness.UNUSABLE,
+                problems=problems,
+            )
+
+        # Determine fitness based on whether we have any non-disqualifying issues
+        fitness = LibraryManager.LibraryFitness.FLAWED if problems else LibraryManager.LibraryFitness.GOOD
+
+        return EvaluateLibraryFitnessResultSuccess(
+            result_details=f"Library '{schema.name}' is compatible",
+            fitness=fitness,
+            problems=problems,
+        )
+
+    async def load_libraries_request(self, request: LoadLibrariesRequest) -> ResultPayload:  # noqa: ARG002, C901
+        """Load all libraries from configuration (backward compatibility wrapper).
+
+        This is the legacy entry point that loads all configured libraries.
+        New code should use LoadLibraryRequest to load specific libraries instead.
+        """
+        # First, discover all available libraries
+        discover_result = self.discover_libraries_request(DiscoverLibrariesRequest())
+        if isinstance(discover_result, DiscoverLibrariesResultFailure):
+            return LoadLibrariesResultFailure(result_details=f"Discovery failed: {discover_result.result_details}")
+
+        # Build list of library paths to load, preserving is_sandbox flag
+        libraries_to_load = []
+        for discovered_lib in discover_result.libraries_discovered:
+            lib_path = str(discovered_lib.path)
+            lib_info = self._library_file_path_to_info.get(lib_path)
+
+            # Update is_sandbox if library_info exists and discovery says it's sandbox
+            if lib_info and discovered_lib.is_sandbox:
+                lib_info.is_sandbox = True
+
+            if lib_info:
+                libraries_to_load.append(lib_path)
+
+        if not libraries_to_load:
+            details = "No libraries found in configuration."
+            return LoadLibrariesResultSuccess(result_details=ResultDetails(message=details, level=logging.INFO))
+
+        # Load each discovered library by path
+        loaded_count = 0
+        failed_libraries = []
+        total_libraries = len(libraries_to_load)
+
+        for current_library_index, lib_path in enumerate(libraries_to_load, start=1):
+            load_result = await self.register_library_from_file_request(
+                RegisterLibraryFromFileRequest(
+                    file_path=lib_path,
+                    load_as_default_library=False,
+                )
+            )
+
+            # Get library_name from result for progress events (use path as fallback for failures)
+            if isinstance(load_result, RegisterLibraryFromFileResultSuccess):
+                library_name = load_result.library_name
+            else:
+                library_name = lib_path
+
+            # Emit loading event
+            GriptapeNodes.EventManager().put_event(
+                AppEvent(
+                    payload=EngineInitializationProgress(
+                        phase=InitializationPhase.LIBRARIES,
+                        item_name=library_name,
+                        status=InitializationStatus.LOADING,
+                        current=current_library_index,
+                        total=total_libraries,
+                    )
+                )
+            )
+
+            if isinstance(load_result, RegisterLibraryFromFileResultSuccess):
+                loaded_count += 1
+
+                # Emit success event
+                GriptapeNodes.EventManager().put_event(
+                    AppEvent(
+                        payload=EngineInitializationProgress(
+                            phase=InitializationPhase.LIBRARIES,
+                            item_name=library_name,
+                            status=InitializationStatus.COMPLETE,
+                            current=current_library_index,
+                            total=total_libraries,
+                        )
+                    )
+                )
+            else:
+                failed_libraries.append(library_name)
+                logger.warning("Failed to load library '%s': %s", library_name, load_result.result_details)
+
+                # Emit failure event
+                error_message = (
+                    load_result.result_details.result_details[0].message
+                    if isinstance(load_result.result_details, ResultDetails)
+                    else str(load_result.result_details)
+                )
+                GriptapeNodes.EventManager().put_event(
+                    AppEvent(
+                        payload=EngineInitializationProgress(
+                            phase=InitializationPhase.LIBRARIES,
+                            item_name=library_name,
+                            status=InitializationStatus.FAILED,
+                            current=current_library_index,
+                            total=total_libraries,
+                            error=error_message,
+                        )
+                    )
+                )
+
+        if loaded_count == 0 and len(failed_libraries) > 0:
+            return LoadLibrariesResultFailure(
+                result_details=f"Failed to load any libraries. Failed: {', '.join(failed_libraries)}"
+            )
+
+        message = f"Loaded {loaded_count} libraries"
+        if failed_libraries:
+            message += f". Failed: {', '.join(failed_libraries)}"
+
+        return LoadLibrariesResultSuccess(result_details=ResultDetails(message=message, level=logging.INFO))
 
     def _discover_library_files(self) -> list[Path]:
         """Discover library JSON files from config and workspace recursively.
@@ -2720,6 +3456,18 @@ class LibraryManager:
         # Use the found file path for reloading
         actual_library_file_path = str(actual_library_file)
 
+        # Create LibraryInfo for tracking this library reload
+        lib_info = LibraryManager.LibraryInfo(
+            lifecycle_state=LibraryManager.LibraryLifecycleState.DISCOVERED,
+            library_path=actual_library_file_path,
+            is_sandbox=False,
+            library_name=library_name,
+            fitness=LibraryManager.LibraryFitness.NOT_EVALUATED,
+            problems=[],
+        )
+        # Store lib_info in dict so register handler can find it
+        self._library_file_path_to_info[actual_library_file_path] = lib_info
+
         # Reload the library from file
         reload_result = await GriptapeNodes.ahandle_request(
             RegisterLibraryFromFileRequest(file_path=actual_library_file_path)
@@ -2954,6 +3702,18 @@ class LibraryManager:
 
         # Automatically register the downloaded library (unless disabled for startup downloads)
         if request.auto_register:
+            # Create LibraryInfo for tracking this downloaded library
+            lib_info = LibraryManager.LibraryInfo(
+                lifecycle_state=LibraryManager.LibraryLifecycleState.DISCOVERED,
+                library_path=str(library_json_path),
+                is_sandbox=False,
+                library_name=library_name,
+                fitness=LibraryManager.LibraryFitness.NOT_EVALUATED,
+                problems=[],
+            )
+            # Store lib_info in dict so register handler can find it
+            self._library_file_path_to_info[str(library_json_path)] = lib_info
+
             register_request = RegisterLibraryFromFileRequest(file_path=str(library_json_path))
             register_result = await GriptapeNodes.ahandle_request(register_request)
             if not register_result.succeeded():