legionio 1.7.17 → 1.7.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fc7545d6fe4e3dc832eba2265dc27fed7546fb3d770dec04b4375b35505479f
-  data.tar.gz: 513b2ff1093560b1d88c427b176d6f27959a6c94abd3106173d462d29f8cd69c
+  metadata.gz: ba8e945b1c999e0c815583388817c35bc019134994745682a774afb6e645db1f
+  data.tar.gz: d21bf7aea3328dda51f7139ed36632b31f16e5c57bef938a9eb2f9f000c2c21e
 SHA512:
-  metadata.gz: b6de374974924d397249494b4aed6ff9e99263116a36d47226530c12653d672371565d060b65913d249fce4d0ed808fd6ffae45a669a6e4b1b67d87a056dcbe8
-  data.tar.gz: 2d64efa40365a2da40fcc97de5173e2c3bfd3458e8adf861a0efde9c35514d7b876ab200f2d5648ca68f08f5de879c29dde2c4d5c3f53d9c2240ae8f4575debe
+  metadata.gz: c5ef0de86e4ea0a8e92fc7433af4e36bb8b7088737142abcfa5edcaad3769ede8acf0205e2b8478e80cc4376052e6cb3ef3df384b2cf2c39abdc8205fd965a68
+  data.tar.gz: 389cf7d22ac2db9e44489c4118cbef323d0d92d9242b4ec0e8a4c7ed141425497249a6832b2cf1bbecdc9e6666d65251978fac36f299175195d2eefa8fb6e190

data/.rubocop.yml

@@ -3,6 +3,9 @@ AllCops:
   NewCops: enable
   SuggestExtensions: false
 
+Style/RedundantConstantBase:
+  Enabled: false
+
 Layout/LineLength:
   Max: 160
   Exclude:

data/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 ## [Unreleased]
 
+## [1.7.20] - 2026-04-06
+### Added
+- `Legion::Mode` module with `LEGACY_MAP`, ENV/Settings fallback chain, `agent?`/`worker?`/`infra?`/`lite?` predicates
+- `Legion.instance_id` — UUID computed at load time, ENV override via `LEGIONIO_INSTANCE_ID`
+- `Legion::Identity::Process` singleton — process identity with `bind!`, `bind_fallback!`, `queue_prefix` per-mode, `AtomicReference` thread safety
+- `Legion::Identity::Request` — per-request immutable identity with `from_env`, `from_auth_context`, `to_caller_hash`, `to_rbac_principal`
+- `Legion::Identity::Lease` — credential lease value object with `expired?`, `stale?` (50% TTL), `ttl_seconds`, `valid?`
+- `Legion::Identity::LeaseRenewer` — background thread per provider, 50% TTL renewal, cooperative shutdown (no `Thread#kill`)
+- `Legion::Identity::Broker` — provider management with groups cache (60s TTL, single-flight CAS), `token_for`, `credentials_for`, `shutdown`
+- `Legion::Identity::Middleware` — Rack middleware bridging `legion.auth` to `legion.principal` (`Identity::Request`)
+- `setup_identity` boot step 9 — parallel provider resolution via `Concurrent::Promises`, fallback to `ENV['USER']`
+- Extension publish suppression — defers `LexRegister.publish` until identity resolves, `flush_pending_registrations!`
+- Identity provider auto-registration during phased extension load (`identity_provider?` duck-type check)
+- `GET /api/identity/audit` route with principal and duration filtering
+- `legion doctor` checks: `ApiBindCheck` (non-loopback without auth), `ModeCheck` (no explicit process.mode)
+
+### Changed
+- `Readiness.status` upgraded to `Concurrent::Hash` for thread safety; `:identity` added to `COMPONENTS`
+- `READONLY_SECTIONS` extended with `:identity`, `:rbac`, `:api`
+- Default API bind changed from `0.0.0.0` to `127.0.0.1`
+- `ProcessRole` delegates `.current` to `Mode.current`; added `:agent` and `:infra` role entries
+- `lite_mode?` delegates to `Mode.lite?`
+- Reload path adds `Identity::Process.refresh_credentials` after transport reconnect
+- Shutdown adds cooperative `Identity::Broker.shutdown` and JWKS background refresh stop
+
+## [1.7.19] - 2026-04-06
+
+### Added
+- `ALWAYS_LOADED` constant in `Tools::Discovery` — pins apollo/knowledge and eval/evaluation runners to always-loaded regardless of extension DSL
+- `always_loaded_names` method on `Tools::Registry` returning names of all non-deferred registered tools
+
+### Changed
+- Tool name format changed from dot-separated to dash-separated (`legion-ext-runner-func`) for LLM provider compatibility
+- Reduced noisy debug logging in `Tools::Discovery` and `Tools::Registry`
+
+## [1.7.18] - 2026-04-06
+
+### Added
+- Multi-phase extension loading: identity providers (`lex-identity-*`) load in phase 0 before all other extensions in phase 1
+- `identity` category in extension registry with prefix matching for `lex-identity-*` gems at tier 0, phase 0
+- `group_by_phase` method groups discovered extensions by phase from the category registry
+- `load_phase_extensions` replaces `load_extensions` — scopes parallel loading to a subset of entries per phase
+- `hook_phase_actors` replaces `hook_all_actors` — hooks deferred actors after each phase completes
+- Per-phase logging during extension loading shows cumulative actor counts
+
+### Changed
+- `hook_extensions` now iterates phases sequentially (phase 0 then phase 1), running full load+hook cycle per phase
+- `default_category_registry` includes `phase:` key on all categories; all non-identity categories default to phase 1
+- Catalog transitions (`transition(:running)` + `flush_persisted_transitions`) happen after all phases complete
+- Reserved prefixes list now includes `identity`
+
 ### Added
 - `Legion::Tools::Base` - canonical tool base class with DSL
 - `Legion::Tools::Registry` - always/deferred tool classification

data/CLAUDE.md

@@ -9,7 +9,7 @@ The primary gem for the LegionIO framework. An extensible async job engine for s
 
 **GitHub**: https://github.com/LegionIO/LegionIO
 **Gem**: `legionio`
-**Version**: 1.6.0
+**Version**: 1.7.18
 **License**: Apache-2.0
 **Docker**: `legionio/legion`
 **Ruby**: >= 3.4
@@ -51,14 +51,14 @@ Legion.start
       ├── 10. setup_gaia         (legion-gaia, cognitive coordination layer, optional)
       ├── 11. setup_telemetry    (OpenTelemetry, optional)
       ├── 12. setup_supervision  (process supervision)
-      ├── 13. load_extensions    (two-phase parallel: require+autobuild on FixedThreadPool, then hook_all_actors)
+      ├── 13. load_extensions    (multi-phase: phase 0 (identity providers) loads and hooks actors first, then phase 1 (everything else))
       ├── 14. Legion::Crypt.cs   (distribute cluster secret)
       └── 15. setup_api          (start Sinatra/Puma on port 4567)
 ```
 
 Each phase calls `Legion::Readiness.mark_ready(:component)`. All phases are individually toggleable via `Service.new(transport: false, ...)`.
 
-Extension loading is two-phase and parallel: all extensions are `require`d and `autobuild` runs concurrently on a `Concurrent::FixedThreadPool(min(count, extensions.parallel_pool_size))`, collecting actors into a thread-safe `Concurrent::Array` of `@pending_actors`. Pool size defaults to 24, configurable via `Legion::Settings[:extensions][:parallel_pool_size]`. After all extensions are loaded, `hook_all_actors` starts AMQP subscriptions, timers, and other actor types sequentially. This prevents race conditions where early extensions start ticking while later ones haven't loaded yet. Thread safety relies on ThreadLocal AMQP channels, per-extension Settings keys, and sequential post-processing of Catalog transitions and Registry writes.
+Extension loading is multi-phase and parallel: `hook_extensions` calls `group_by_phase` to partition discovered extensions by phase number (from the category registry), then iterates phases sequentially. Phase 0 contains identity providers (`lex-identity-*` gems, category `:identity`, tier 0); phase 1 contains all other extensions. Within each phase, extensions are `require`d and `autobuild` runs concurrently on a `Concurrent::FixedThreadPool(min(count, extensions.parallel_pool_size))`, collecting actors into a thread-safe `Concurrent::Array` of `@pending_actors`. Pool size defaults to 24, configurable via `Legion::Settings[:extensions][:parallel_pool_size]`. After each phase's extensions are loaded, `hook_phase_actors` starts AMQP subscriptions, timers, and other actor types for that phase sequentially — ensuring identity providers are fully running before any other extension boots. Catalog transitions (`transition(:running)` and `flush_persisted_transitions`) happen after all phases complete. Thread safety relies on ThreadLocal AMQP channels, per-extension Settings keys, and sequential post-processing of Catalog transitions and Registry writes.
 
 ### Reload Sequence
 
@@ -85,7 +85,7 @@ Legion (lib/legion.rb)
 │                      # Ingress.run(payload:, runner_class:, function:, source:)
 │                      # Ingress.normalize returns message hash without executing
 ├── Extensions         # LEX discovery, loading, and lifecycle management
-│   ├── Core           # Mixin: data_required?, cache_required?, crypt_required?, etc.
+│   ├── Core           # Mixin: data_required?, cache_required?, crypt_required?, mcp_tools?, mcp_tools_deferred?, etc.
 │   ├── Actors/        # Actor execution modes
 │   │   ├── Base       # Base actor class
 │   │   ├── Every      # Run at interval (timer)
@@ -96,7 +96,7 @@ Legion (lib/legion.rb)
 │   │   └── Nothing    # No-op actor
 │   ├── Builders/      # Build actors and runners from LEX definitions
 │   │   ├── Actors     # Build actors from extension definitions
-│   │   ├── Runners    # Build runners from extension definitions (stores runner_module ref)
+│   │   ├── Runners    # Build runners from extension definitions; exposes `runner_modules` accessor for Discovery
 │   │   ├── Helpers    # Builder utilities
 │   │   ├── Hooks      # Webhook hook system builder
 │   │   └── Routes     # Auto-route builder: introspects runners, registers POST /api/extensions/* routes
@@ -149,7 +149,17 @@ Legion (lib/legion.rb)
 │                      # Populated by Builders::Routes during autobuild via LexDispatch
 │
 ├── MCP (legion-mcp gem)  # Extracted to standalone gem — see legion-mcp/CLAUDE.md
-│   └── (58 tools, 2 resources, TierRouter, PatternStore, ContextGuard, Observer, EmbeddingIndex)
+│   └── (tools, 2 resources, TierRouter, PatternStore, ContextGuard, Observer, EmbeddingIndex)
+│
+├── Tools              # Canonical tool layer — replaces Extensions::Capability and Catalog::Registry
+│   ├── Base           # Base class for all framework tools (Do, Status, Config are built-in statics)
+│   ├── Registry       # always/deferred classification for all tools; replaces Catalog::Registry
+│   │                  # Extensions declare tools via `mcp_tools?` / `mcp_tools_deferred?` DSL on Core
+│   ├── Discovery      # Auto-discovers tools from extension runner modules at boot
+│   │                  # `runner_modules` accessor on Builders::Runners feeds Discovery
+│   │                  # `loaded_extension_modules` on Extensions exposes the full set
+│   └── EmbeddingCache # 5-tier persistent embedding cache:
+│                      #   L0 in-memory hash → L1 Cache::Local → L2 Cache → L3 Data::Local → L4 Data
 │
 ├── DigitalWorker      # Digital worker platform (AI-as-labor governance)
 │   ├── Lifecycle      # Worker state machine (active/paused/retired/terminated)
@@ -248,6 +258,16 @@ Legion (lib/legion.rb)
 
 `Legion::Extensions.find_extensions` discovers lex-* gems via `Bundler.load.specs` (when running under Bundler) or falls back to `Gem::Specification.all_names`. It also processes `Legion::Settings[:extensions]` for explicitly configured extensions, attempting `Gem.install` for missing ones if `auto_install` is enabled.
 
+**Category registry**: Extensions are classified by `categorize_and_order` using `default_category_registry`. Each category has a `type` (`:list` or `:prefix`), `tier` (load order within a phase), and `phase`:
+
+| Category | Type | Tier | Phase | Matches |
+|----------|------|------|-------|---------|
+| `identity` | prefix | 0 | 0 | `lex-identity-*` gems |
+| `core` | list | 1 | 1 | explicitly listed core extensions |
+| `ai` | list | 2 | 1 | explicitly listed AI provider extensions |
+| `gaia` | list | 3 | 1 | explicitly listed GAIA extensions |
+| `agentic` | prefix | 4 | 1 | `lex-agentic-*` gems |
+
 **Role-based filtering**: After discovery, `apply_role_filter` prunes extensions based on `Legion::Settings[:role][:profile]`:
 
 | Profile | What loads |
@@ -479,7 +499,7 @@ legion
 
 ### MCP Design
 
-Extracted to the `legion-mcp` gem (v0.5.9). See `legion-mcp/CLAUDE.md` for full architecture.
+Extracted to the `legion-mcp` gem (v0.7.3). See `legion-mcp/CLAUDE.md` for full architecture.
 
 - `Legion::MCP.server` is memoized singleton — call `Legion::MCP.reset!` in tests
 - Tool naming: `legion.snake_case_name` (dot namespace, not slash)
@@ -571,7 +591,7 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `lib/legion/readiness.rb` | Component readiness tracking (COMPONENTS constant, `ready?`, `to_h`) |
 | `lib/legion/events.rb` | In-process pub/sub: `on`, `emit`, `once`, `off`, wildcard `*` |
 | `lib/legion/ingress.rb` | Universal runner invocation: `normalize`, `run` |
-| `lib/legion/extensions.rb` | LEX discovery, loading, actor hooking, shutdown |
+| `lib/legion/extensions.rb` | LEX discovery, loading, actor hooking, shutdown; exposes `loaded_extension_modules` for Tools::Discovery |
 | `lib/legion/extensions/core.rb` | Extension mixin (requirement flags, autobuild) |
 | `lib/legion/extensions/actors/` | Actor types: base, every, loop, once, poll, subscription, nothing, defaults |
 | `lib/legion/extensions/builders/` | Build actors, runners, helpers, hooks, routes from definitions |
@@ -586,7 +606,12 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `lib/legion/isolation.rb` | Process isolation for untrusted extension execution |
 | `lib/legion/sandbox.rb` | Sandboxed execution environment for extensions |
 | `lib/legion/context.rb` | Thread-local execution context (request tracing, tenant) |
-| `lib/legion/catalog.rb` | Extension catalog: registry of available extensions with metadata |
+| `lib/legion/catalog.rb` | Extension catalog: registry of available extensions with metadata (Catalog::Registry removed — replaced by Tools::Registry) |
+| `lib/legion/tools.rb` | Tools module entry point |
+| `lib/legion/tools/base.rb` | Tools::Base — canonical base class for all tools |
+| `lib/legion/tools/registry.rb` | Tools::Registry — always/deferred classification, replaces Catalog::Registry |
+| `lib/legion/tools/discovery.rb` | Tools::Discovery — auto-discovers tools from extension runner_modules at boot |
+| `lib/legion/tools/embedding_cache.rb` | Tools::EmbeddingCache — 5-tier persistent embedding cache (L0–L4) |
 | `lib/legion/registry.rb` | Extension registry with security scanning |
 | `lib/legion/registry/security_scanner.rb` | Gem security scanner (CVE checks, signature verification) |
 | `lib/legion/webhooks.rb` | Webhook delivery system: HTTP POST with retry, HMAC signing |

data/lib/legion/api/default_settings.rb

@@ -9,7 +9,7 @@ module Legion
         {
           enabled:         true,
           port:            4567,
-          bind:            '0.0.0.0',
+          bind:            '127.0.0.1',
           puma:            puma_defaults,
           bind_retries:    3,
           bind_retry_wait: 2,

data/lib/legion/api/identity_audit.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  class API < Sinatra::Base
+    module Routes
+      module IdentityAudit
+        def self.registered(app)
+          app.helpers IdentityAuditHelpers
+
+          app.get '/api/identity/audit' do
+            halt 503, json_error('unavailable', 'audit records not available') unless defined?(Legion::Data::Model::AuditRecord)
+
+            dataset = Legion::Data::Model::AuditRecord.where(entity_type: 'identity')
+
+            principal = params[:principal]
+            dataset = dataset.where(Sequel.lit("metadata->>'principal' = ?", principal)) if principal
+
+            since = params[:since]
+            if since
+              duration = parse_since_duration(since)
+              dataset = dataset.where { created_at >= Time.now - duration } if duration
+            end
+
+            records = dataset.order(Sequel.desc(:created_at)).limit(100).all
+            json_collection(records.map do |r|
+              { id: r.id, action: r.action, entity_type: r.entity_type, metadata: r.parsed_metadata, created_at: r.created_at }
+            end)
+          end
+        end
+
+        module IdentityAuditHelpers
+          def parse_since_duration(value)
+            return nil unless value.is_a?(String)
+
+            case value
+            when /\A(\d+)h\z/ then Regexp.last_match(1).to_i * 3600
+            when /\A(\d+)m\z/ then Regexp.last_match(1).to_i * 60
+            when /\A(\d+)s\z/ then Regexp.last_match(1).to_i
+            when /\A(\d+)d\z/ then Regexp.last_match(1).to_i * 86_400
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/settings.rb

@@ -5,7 +5,7 @@ module Legion
     module Routes
       module Settings
         SENSITIVE_KEYS = %i[password secret token key cert private_key api_key].freeze
-        READONLY_SECTIONS = %i[crypt transport].freeze
+        READONLY_SECTIONS = %i[crypt transport identity rbac api].freeze
 
         def self.registered(app)
           app.get '/api/settings' do

data/lib/legion/api.rb

@@ -60,6 +60,7 @@ require_relative 'api/tbi_patterns'
 require_relative 'api/webhooks'
 require_relative 'api/tenants'
 require_relative 'api/inbound_webhooks'
+require_relative 'api/identity_audit'
 require_relative 'api/graphql' if defined?(GraphQL)
 
 module Legion
@@ -216,6 +217,7 @@ module Legion
     register Routes::Webhooks
     register Routes::Tenants
     register Routes::InboundWebhooks
+    register Routes::IdentityAudit
     register Routes::GraphQL if defined?(Routes::GraphQL)
 
     use Legion::API::Middleware::RequestLogger

data/lib/legion/cli/do_command.rb

@@ -158,7 +158,7 @@ module Legion
           end
           return nil unless matched
 
-          matched.tool_name.split('.').last
+          matched.tool_name.split(/[-.]/).last
         end
 
         def build_runner_class(extension, runner)

data/lib/legion/cli/doctor/api_bind_check.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Legion
+  module CLI
+    class Doctor
+      class ApiBindCheck
+        LOOPBACK_BINDS = %w[127.0.0.1 ::1 localhost].freeze
+
+        def name
+          'API bind address'
+        end
+
+        def run
+          return skip_result unless defined?(Legion::Settings)
+
+          api_settings = Legion::Settings[:api]
+          return skip_result unless api_settings.is_a?(Hash)
+
+          bind = api_settings[:bind]
+          return skip_result if bind.nil?
+
+          if LOOPBACK_BINDS.include?(bind)
+            Result.new(
+              name:    name,
+              status:  :pass,
+              message: "API bound to loopback (#{bind})"
+            )
+          elsif api_settings.dig(:auth, :enabled) == true
+            Result.new(
+              name:    name,
+              status:  :pass,
+              message: "API bound to #{bind} with auth enabled"
+            )
+          else
+            Result.new(
+              name:         name,
+              status:       :warn,
+              message:      "API bound to non-loopback address (#{bind}) without explicit auth configuration",
+              prescription: "Set api.auth.enabled: true or change api.bind to '127.0.0.1'"
+            )
+          end
+        end
+
+        private
+
+        def skip_result
+          Result.new(
+            name:    name,
+            status:  :pass,
+            message: 'API settings not loaded'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/legion/cli/doctor/mode_check.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Legion
+  module CLI
+    class Doctor
+      class ModeCheck
+        def name
+          'Process mode'
+        end
+
+        def run
+          unless defined?(Legion::Settings)
+            return Result.new(
+              name:    name,
+              status:  :pass,
+              message: 'Settings not loaded'
+            )
+          end
+
+          explicit_mode = Legion::Settings.dig(:process, :mode) || Legion::Settings[:mode]
+
+          if explicit_mode
+            Result.new(
+              name:    name,
+              status:  :pass,
+              message: "Explicit process mode configured: #{explicit_mode}"
+            )
+          else
+            Result.new(
+              name:         name,
+              status:       :warn,
+              message:      'No explicit process.mode configured (defaulting to agent)',
+              prescription: 'Set {"process": {"mode": "agent"}} in settings to prepare for Phase 9 default change to worker'
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/cli/doctor_command.rb

@@ -17,6 +17,8 @@ module Legion
       autoload :PidCheck,         'legion/cli/doctor/pid_check'
       autoload :PermissionsCheck, 'legion/cli/doctor/permissions_check'
       autoload :TlsCheck,         'legion/cli/doctor/tls_check'
+      autoload :ApiBindCheck,     'legion/cli/doctor/api_bind_check'
+      autoload :ModeCheck,        'legion/cli/doctor/mode_check'
 
       def self.exit_on_failure?
         true
@@ -37,6 +39,8 @@ module Legion
         PidCheck
         PermissionsCheck
         TlsCheck
+        ApiBindCheck
+        ModeCheck
       ].freeze
 
       # Weights: security > connectivity > convenience

data/lib/legion/extensions.rb

@@ -21,12 +21,22 @@ module Legion
         @local_tasks = []
         @actors = []
         @running_instances = Concurrent::Array.new
-        @pending_actors = Concurrent::Array.new
+        @loaded_extensions = []
+        @pending_registrations = Concurrent::Array.new
 
         find_extensions
-        load_extensions
+
+        phases = group_by_phase
+        phases.each do |phase_num, entries|
+          @pending_actors = Concurrent::Array.new
+          load_phase_extensions(phase_num, entries)
+          hook_phase_actors(phase_num)
+        end
+
+        @loaded_extensions&.each { |name| Catalog.transition(name, :running) }
+        Catalog.flush_persisted_transitions
+
         load_yaml_agents
-        hook_all_actors
       end
 
       attr_reader :local_tasks
@@ -97,6 +107,21 @@ module Legion
         Legion::Logging.info "Successfully shut down all actors (#{(Time.now - shutdown_start).round(1)}s)"
       end
 
+      def flush_pending_registrations!
+        return if @pending_registrations.nil? || @pending_registrations.empty?
+
+        registrations = @pending_registrations
+        count = registrations.size
+        @pending_registrations = nil
+
+        registrations.each do |registration|
+          registration.publish
+        rescue StandardError => e
+          Legion::Logging.warn "[Extensions] flush registration failed: #{e.message}" if defined?(Legion::Logging)
+        end
+        Legion::Logging.info "[Extensions] flushed #{count} pending registrations" if defined?(Legion::Logging)
+      end
+
       def pause_actors
         @running_instances&.each do |inst|
           timer = inst.instance_variable_get(:@timer)
@@ -107,11 +132,8 @@ module Legion
         Legion::Logging.warn 'All actors paused' if defined?(Legion::Logging)
       end
 
-      def load_extensions
-        @extensions ||= []
-        @loaded_extensions ||= []
-
-        eligible = @extensions.filter_map do |entry|
+      def load_phase_extensions(phase_num, entries)
+        eligible = entries.filter_map do |entry|
           gem_name = entry[:gem_name]
           ext_name = entry[:require_path].split('/').last
 
@@ -130,15 +152,35 @@ module Legion
         load_extensions_parallel(eligible)
 
         Legion::Logging.info(
-          "#{@extensions.count} extensions loaded with " \
-          "subscription:#{@subscription_tasks.count}," \
+          "Phase #{phase_num}: #{eligible.count} extensions loaded " \
+          "(subscription:#{@subscription_tasks.count}," \
           "every:#{@timer_tasks.count}," \
           "poll:#{@poll_tasks.count}," \
           "once:#{@once_tasks.count}," \
-          "loop:#{@loop_tasks.count}"
+          "loop:#{@loop_tasks.count})"
         )
       end
 
+      def hook_phase_actors(phase_num)
+        return if @pending_actors.nil? || @pending_actors.empty?
+
+        Legion::Logging.info "Phase #{phase_num}: hooking #{@pending_actors.size} deferred actors"
+
+        groups = group_pending_actors
+
+        %i[once poll every loop].each do |type|
+          next if groups[type].empty?
+
+          groups[type].each { |actor| hook_actor(**actor) }
+        end
+
+        hook_subscription_actors_pooled(groups[:subscription]) unless groups[:subscription].empty?
+
+        dispatch_local_actors(@local_tasks) unless @local_tasks.empty?
+
+        @pending_actors.clear
+      end
+
       def load_extensions_parallel(eligible)
         return if eligible.empty?
 
@@ -227,8 +269,15 @@ module Legion
         has_logger = extension.respond_to?(:log)
         extension.autobuild
 
+        register_identity_provider(extension, entry) if identity_provider?(extension)
+
         require 'legion/transport/messages/lex_register'
-        Legion::Transport::Messages::LexRegister.new(function: 'save', opts: extension.runners).publish
+        registration = Legion::Transport::Messages::LexRegister.new(function: 'save', opts: extension.runners)
+        if @pending_registrations
+          @pending_registrations << registration
+        else
+          registration.publish
+        end
 
         register_capabilities(entry[:gem_name], extension.runners) if extension.respond_to?(:runners)
         write_lex_cli_manifest(entry, extension)
@@ -273,38 +322,6 @@ module Legion
         false
       end
 
-      def hook_all_actors
-        return if @pending_actors.nil? || @pending_actors.empty?
-
-        Legion::Logging.info "Hooking #{@pending_actors.size} deferred actors"
-
-        groups = group_pending_actors
-
-        %i[once poll every loop].each do |type|
-          next if groups[type].empty?
-
-          Legion::Logging.info "Starting #{type} actors (#{groups[type].size})"
-          groups[type].each { |actor| hook_actor(**actor) }
-        end
-        unless groups[:subscription].empty?
-          Legion::Logging.info "Starting subscription actors (#{groups[:subscription].size})"
-          hook_subscription_actors_pooled(groups[:subscription])
-        end
-        dispatch_local_actors(@local_tasks) unless @local_tasks.empty?
-
-        @pending_actors.clear
-        Legion::Logging.info(
-          "Actors hooked: subscription:#{@subscription_tasks.count}," \
-          "every:#{@timer_tasks.count}," \
-          "poll:#{@poll_tasks.count}," \
-          "once:#{@once_tasks.count}," \
-          "loop:#{@loop_tasks.count}," \
-          "local:#{@local_tasks.count}"
-        )
-        @loaded_extensions&.each { |name| Catalog.transition(name, :running) }
-        Catalog.flush_persisted_transitions
-      end
-
       ACTOR_TYPE_MAP = {
         Once:         :once,
         Poll:         :poll,
@@ -313,6 +330,17 @@ module Legion
         Subscription: :subscription
       }.freeze
 
+      def group_by_phase
+        settings_cats = ::Legion::Settings.dig(:extensions, :categories) || {}
+        categories = default_category_registry.merge(settings_cats)
+        default_phase = 1
+
+        @extensions.group_by do |entry|
+          cat = entry[:category]
+          categories.dig(cat, :phase) || default_phase
+        end.sort_by(&:first)
+      end
+
       def group_pending_actors
         groups = { once: [], poll: [], every: [], loop: [], subscription: [] }
         @pending_actors.each do |actor|
@@ -400,6 +428,39 @@ module Legion
 
       private
 
+      def identity_provider?(extension)
+        extension.respond_to?(:provider_name) &&
+          extension.respond_to?(:provider_type) &&
+          extension.respond_to?(:facing)
+      end
+
+      def register_identity_provider(extension, entry)
+        return unless defined?(Legion::Data) && Legion::Data.connected?
+        return unless defined?(Legion::Data::Model::IdentityProvider)
+
+        name = extension.provider_name.to_s
+        attrs = {
+          provider_type: extension.provider_type.to_s,
+          facing:        extension.facing.to_s,
+          priority:      extension.respond_to?(:priority) ? extension.priority : 100,
+          trust_weight:  extension.respond_to?(:trust_weight) ? extension.trust_weight : 50,
+          capabilities:  extension.respond_to?(:capabilities) ? Array(extension.capabilities).map(&:to_s) : [],
+          source:        'gem',
+          enabled:       true
+        }
+
+        existing = Legion::Data::Model::IdentityProvider.where(name: name).first
+        if existing
+          diverged = attrs.any? { |k, v| existing.send(k).to_s != v.to_s }
+          Legion::Logging.info "[identity][provider] name=#{name} source=db/gem diverged=#{diverged}" if defined?(Legion::Logging)
+        else
+          Legion::Data::Model::IdentityProvider.insert_conflict(target: :name, update: attrs).insert(attrs.merge(name: name))
+          Legion::Logging.info "[identity][provider] name=#{name} registered" if defined?(Legion::Logging)
+        end
+      rescue StandardError => e
+        Legion::Logging.warn "[identity][provider] registration failed for #{entry[:gem_name]}: #{e.message}" if defined?(Legion::Logging)
+      end
+
       def write_lex_cli_manifest(entry, extension)
         require 'legion/cli/lex_cli_manifest'
 
@@ -661,9 +722,10 @@ module Legion
         ext_settings = ::Legion::Settings[:extensions] || {}
         categories   = ext_settings[:categories] || default_category_registry
         lists        = {
-          core: Array(ext_settings[:core]),
-          ai:   Array(ext_settings[:ai]),
-          gaia: Array(ext_settings[:gaia])
+          identity: Array(ext_settings[:identity]),
+          core:     Array(ext_settings[:core]),
+          ai:       Array(ext_settings[:ai]),
+          gaia:     Array(ext_settings[:gaia])
         }
         ctx = {
           blocked:     Array(ext_settings[:blocked]),
@@ -696,7 +758,7 @@ module Legion
           Legion::Logging.debug "Extensions#check_reserved_words failed to read reserved_prefixes: #{e.message}" if defined?(Legion::Logging)
           []
         end
-        reserved_prefixes = configured_prefixes.empty? ? %w[core ai agentic gaia] : configured_prefixes
+        reserved_prefixes = configured_prefixes.empty? ? %w[core ai agentic gaia identity] : configured_prefixes
 
         configured_words = begin
           Array(::Legion::Settings.dig(:extensions, :reserved_words))
@@ -881,10 +943,11 @@ module Legion
 
       def default_category_registry
         {
-          core:    { type: :list, tier: 1 },
-          ai:      { type: :list, tier: 2 },
-          gaia:    { type: :list, tier: 3 },
-          agentic: { type: :prefix, tier: 4 }
+          identity: { type: :prefix, tier: 0, phase: 0 },
+          core:     { type: :list,   tier: 1, phase: 1 },
+          ai:       { type: :list,   tier: 2, phase: 1 },
+          gaia:     { type: :list,   tier: 3, phase: 1 },
+          agentic:  { type: :prefix, tier: 4, phase: 1 }
         }
       end