Docs: refresh extension host module layout

docs/.internal/extension-host-migration/openclaw-capability-catalog-and-arbitration-spec.md

@@ -35,43 +35,43 @@ What has been implemented:
 - channel catalog package metadata parsing now routes through host-owned schema helpers
 - host-owned resolved-extension records now carry the static metadata needed for install, onboarding, and lightweight operator UX
 - config doc baseline generation now uses the same host-owned resolved-extension metadata path
-- plugin SDK alias resolution now routes through `src/extension-host/loader-compat.ts`
-- loader alias-wired module loader creation now routes through `src/extension-host/loader-module-loader.ts`
-- loader cache key construction and registry cache control now route through `src/extension-host/loader-cache.ts`
-- loader lazy runtime proxy creation now routes through `src/extension-host/loader-runtime-proxy.ts`
-- loader provenance helpers now route through `src/extension-host/loader-provenance.ts`
-- loader duplicate-order and record/error policy now route through `src/extension-host/loader-policy.ts`
-- loader discovery policy outcomes now route through `src/extension-host/loader-discovery-policy.ts`
-- loader initial candidate planning and record creation now route through `src/extension-host/loader-records.ts`
-- loader entry-path opening and module import now route through `src/extension-host/loader-import.ts`
-- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/loader-runtime.ts`
-- loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts`
-- loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts`
-- loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts`
-- loader host process state now routes through `src/extension-host/loader-host-state.ts`
-- loader preflight and cache-hit setup now routes through `src/extension-host/loader-preflight.ts`
-- loader post-preflight pipeline composition now routes through `src/extension-host/loader-pipeline.ts`
-- loader execution setup composition now routes through `src/extension-host/loader-execution.ts`
-- loader discovery and manifest bootstrap now routes through `src/extension-host/loader-bootstrap.ts`
-- loader mutable activation state now routes through `src/extension-host/loader-session.ts`
-- loader session run and finalization composition now routes through `src/extension-host/loader-run.ts`
-- loader activation policy outcomes now route through `src/extension-host/loader-activation-policy.ts`
-- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values
-- loader finalization policy results now route through `src/extension-host/loader-finalization-policy.ts`
-- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/loader-finalize.ts`
+- plugin SDK alias resolution now routes through `src/extension-host/compat/loader-compat.ts`
+- loader alias-wired module loader creation now routes through `src/extension-host/activation/loader-module-loader.ts`
+- loader cache key construction and registry cache control now route through `src/extension-host/activation/loader-cache.ts`
+- loader lazy runtime proxy creation now routes through `src/extension-host/activation/loader-runtime-proxy.ts`
+- loader provenance helpers now route through `src/extension-host/policy/loader-provenance.ts`
+- loader duplicate-order and record/error policy now route through `src/extension-host/policy/loader-policy.ts`
+- loader discovery policy outcomes now route through `src/extension-host/policy/loader-discovery-policy.ts`
+- loader initial candidate planning and record creation now route through `src/extension-host/activation/loader-records.ts`
+- loader entry-path opening and module import now route through `src/extension-host/activation/loader-import.ts`
+- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/activation/loader-runtime.ts`
+- loader post-import planning and `register(...)` execution now route through `src/extension-host/activation/loader-register.ts`
+- loader per-candidate orchestration now routes through `src/extension-host/activation/loader-flow.ts`
+- loader top-level load orchestration now routes through `src/extension-host/activation/loader-orchestrator.ts`
+- loader host process state now routes through `src/extension-host/activation/loader-host-state.ts`
+- loader preflight and cache-hit setup now routes through `src/extension-host/activation/loader-preflight.ts`
+- loader post-preflight pipeline composition now routes through `src/extension-host/activation/loader-pipeline.ts`
+- loader execution setup composition now routes through `src/extension-host/activation/loader-execution.ts`
+- loader discovery and manifest bootstrap now routes through `src/extension-host/activation/loader-bootstrap.ts`
+- loader mutable activation state now routes through `src/extension-host/activation/loader-session.ts`
+- loader session run and finalization composition now routes through `src/extension-host/activation/loader-run.ts`
+- loader activation policy outcomes now route through `src/extension-host/policy/loader-activation-policy.ts`
+- loader record-state transitions now route through `src/extension-host/activation/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values
+- loader finalization policy results now route through `src/extension-host/policy/loader-finalization-policy.ts`
+- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/activation/loader-finalize.ts`
 - channel, provider, gateway-method, tool, CLI, service, command, context-engine, and hook registration normalization now has a host-owned helper boundary for future catalog migration
 - low-risk runtime compatibility writes for channel, provider, gateway-method, HTTP-route, tool, CLI, service, command, context-engine, and hook registrations now route through `src/extension-host/registry-writes.ts` ahead of broader catalog-backed registry ownership
 - context-engine registration and runtime resolution now route through `src/extension-host/context-engine-runtime.ts` ahead of broader catalog-backed ownership
-- exclusive-slot selection and default-slot resolution now route through `src/extension-host/slot-arbitration.ts` ahead of broader catalog-backed arbitration ownership
+- exclusive-slot selection and default-slot resolution now route through `src/extension-host/policy/slot-arbitration.ts` ahead of broader catalog-backed arbitration ownership
 - ACP backend registration and runtime resolution now route through `src/extension-host/acp-runtime-backend-registry.ts` ahead of broader catalog-backed backend ownership
-- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade
-- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades
+- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/policy/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade
+- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/policy/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/policy/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades
 - TTS provider metadata, provider ordering, API-key resolution, configuration checks, and telephony support now route through `src/extension-host/tts-runtime-registry.ts`, provider execution loops, output-format selection, telephony synthesis, and provider-error shaping now route through `src/extension-host/tts-runtime-execution.ts`, provider selection plus request setup now route through `src/extension-host/tts-runtime-setup.ts`, TTS config normalization, defaults, and model-override policy now route through `src/extension-host/tts-config.ts`, prefs-path resolution, auto-mode policy, and persisted TTS preference reads and writes now route through `src/extension-host/tts-preferences.ts`, auto-TTS gating, directive cleanup, truncation, summarization, and payload planning now route through `src/extension-host/tts-payload.ts`, and last-attempt state plus shared status snapshots now route through `src/extension-host/tts-status.ts` while `src/tts/tts.ts` remains the compatibility facade
-- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/hook-compat.ts` ahead of broader catalog-backed registry ownership
-- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/plugin-api.ts` ahead of broader catalog-backed registry ownership
-- compatibility plugin-registry facade ownership now routes through `src/extension-host/plugin-registry.ts` ahead of broader catalog-backed registry ownership
-- compatibility plugin-registry policy now routes through `src/extension-host/plugin-registry-compat.ts` ahead of broader catalog-backed registry ownership
-- compatibility plugin-registry registration actions now route through `src/extension-host/plugin-registry-registrations.ts` ahead of broader catalog-backed registry ownership
+- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/compat/hook-compat.ts` ahead of broader catalog-backed registry ownership
+- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/compat/plugin-api.ts` ahead of broader catalog-backed registry ownership
+- compatibility plugin-registry facade ownership now routes through `src/extension-host/compat/plugin-registry.ts` ahead of broader catalog-backed registry ownership
+- compatibility plugin-registry policy now routes through `src/extension-host/compat/plugin-registry-compat.ts` ahead of broader catalog-backed registry ownership
+- compatibility plugin-registry registration actions now route through `src/extension-host/compat/plugin-registry-registrations.ts` ahead of broader catalog-backed registry ownership
 - host-owned runtime registry accessors now route through `src/extension-host/runtime-registry.ts` ahead of broader catalog-backed registry ownership, and the channel, provider, tool, command, HTTP-route, gateway-method, CLI, and service slices now keep host-owned storage there with mirrored legacy compatibility views
 - plugin command registration, matching, execution, listing, native command-spec projection, and loader reload clearing now route through `src/extension-host/command-runtime.ts` ahead of broader catalog-backed ownership
 - service startup, stop ordering, service-context creation, and failure logging now route through `src/extension-host/service-lifecycle.ts` ahead of broader catalog-backed lifecycle ownership
@@ -103,7 +103,7 @@ How it has been implemented:
 - by extracting post-preflight execution setup and session-run composition into a host-owned loader-pipeline helper before catalog publication work
 - by extracting runtime creation, registry creation, bootstrap setup, module-loader creation, and session creation into a host-owned loader-execution helper before catalog publication work
 - by moving mutable activation state into a host-owned loader session before catalog publication work
-- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation
+- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/policy/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation
 - by turning open-allowlist discovery warnings into explicit host-owned discovery-policy results before catalog publication work
 - by moving duplicate precedence, config enablement, and early memory-slot gating into explicit host-owned activation-policy outcomes before catalog publication work
 - by turning provenance-based untracked-extension warnings and final memory-slot warnings into explicit host-owned finalization-policy results before catalog publication work
@@ -618,7 +618,7 @@ Capability selection must emit structured events for:
 - channel capabilities from `extensions/discord/src/channel.ts:74`, `extensions/slack/src/channel.ts:107`, and `extensions/telegram/src/channel.ts:120` collapse into canonical messaging action families
 - diffs becomes an agent-visible tool family plus a host-managed route surface from `extensions/diffs/index.ts:27`
 - provider integration from `extensions/google-gemini-cli-auth/index.ts:24` becomes operator-visible setup and auth capabilities
-- catalog-backed runtime-family descriptors for embeddings, media, and TTS now route through `src/extension-host/runtime-backend-catalog.ts`; embedding shared backend definitions in `src/extension-host/embedding-runtime-backends.ts`, media shared backend definitions in `src/extension-host/media-runtime-backends.ts`, TTS shared backend definitions in `src/extension-host/tts-runtime-backends.ts`, initial runtime-family arbitration in `src/extension-host/runtime-backend-arbitration.ts`, and shared default and preferred backend ordering plus fallback chaining in `src/extension-host/runtime-backend-policy.ts`; the catalog helpers for generic subsystem ordering, media auto-ordering, and TTS preferred-provider ordering now also route through that shared backend-policy layer; embedding auto-provider selection, embedding local setup guidance, memory doctor guidance for embedding auto-provider order, and explicit embedding fallback policy in `src/extension-host/embedding-runtime-policy.ts`, media provider candidate ordering plus default-model fallback selection in `src/extension-host/media-runtime-policy.ts`, and TTS request setup, status, compatibility provider-order exports, plus explicit TTS configured-fallback policy in `src/extension-host/tts-runtime-policy.ts` already consume that catalog-backed arbitration and backend-policy data, and broader consumer adoption and arbitration should continue moving those subsystem runtimes toward runtime-internal registries rather than leaving them as a universal plugin-provider API shape
+- catalog-backed runtime-family descriptors for embeddings, media, and TTS now route through `src/extension-host/runtime-backend-catalog.ts`; embedding shared backend definitions in `src/extension-host/embedding-runtime-backends.ts`, media shared backend definitions in `src/extension-host/media-runtime-backends.ts`, TTS shared backend definitions in `src/extension-host/tts-runtime-backends.ts`, initial runtime-family arbitration in `src/extension-host/policy/runtime-backend-arbitration.ts`, and shared default and preferred backend ordering plus fallback chaining in `src/extension-host/policy/runtime-backend-policy.ts`; the catalog helpers for generic subsystem ordering, media auto-ordering, and TTS preferred-provider ordering now also route through that shared backend-policy layer; embedding auto-provider selection, embedding local setup guidance, memory doctor guidance for embedding auto-provider order, and explicit embedding fallback policy in `src/extension-host/policy/embedding-runtime-policy.ts`, media provider candidate ordering plus default-model fallback selection in `src/extension-host/policy/media-runtime-policy.ts`, and TTS request setup, status, compatibility provider-order exports, plus explicit TTS configured-fallback policy in `src/extension-host/policy/tts-runtime-policy.ts` already consume that catalog-backed arbitration and backend-policy data, and broader consumer adoption and arbitration should continue moving those subsystem runtimes toward runtime-internal registries rather than leaving them as a universal plugin-provider API shape
 - extension-backed web search should become an agent-visible tool family unless it is only a runtime-internal backend feeding another host-owned surface
 - voice-call from `extensions/voice-call/index.ts:230` becomes a mix of agent-visible actions, runtime providers, and operator surfaces
 - ACP backend registration from `extensions/acpx/src/service.ts:55` becomes runtime-internal backend arbitration

docs/.internal/extension-host-migration/openclaw-extension-contribution-schema-spec.md

@@ -41,16 +41,16 @@ What has been implemented:
 - the first runtime registration normalization helpers now exist in `src/extension-host/runtime-registrations.ts` for channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook writes
 - low-risk runtime compatibility writes for channel, provider, gateway-method, HTTP-route, tool, CLI, service, command, context-engine, and hook registrations now route through `src/extension-host/registry-writes.ts`
 - context-engine registration and runtime resolution now route through `src/extension-host/context-engine-runtime.ts` while `src/context-engine/registry.ts` remains the compatibility facade
-- exclusive-slot selection and default-slot resolution now route through `src/extension-host/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade
+- exclusive-slot selection and default-slot resolution now route through `src/extension-host/policy/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade
 - ACP backend registration and runtime resolution now route through `src/extension-host/acp-runtime-backend-registry.ts` while `src/acp/runtime/registry.ts` remains the compatibility facade
-- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/embedding-runtime-policy.ts`, the public embedding runtime surface and result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade
-- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades
+- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/policy/embedding-runtime-policy.ts`, the public embedding runtime surface and result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade
+- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/policy/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/policy/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades
 - TTS provider metadata, provider ordering, API-key resolution, configuration checks, and telephony support now route through `src/extension-host/tts-runtime-registry.ts`, provider execution loops, output-format selection, telephony synthesis, and provider-error shaping now route through `src/extension-host/tts-runtime-execution.ts`, provider selection plus request setup now route through `src/extension-host/tts-runtime-setup.ts`, TTS config normalization, defaults, and model-override policy now route through `src/extension-host/tts-config.ts`, prefs-path resolution, auto-mode policy, and persisted TTS preference reads and writes now route through `src/extension-host/tts-preferences.ts`, auto-TTS gating, directive cleanup, truncation, summarization, and payload planning now route through `src/extension-host/tts-payload.ts`, and last-attempt state plus shared status snapshots now route through `src/extension-host/tts-status.ts` while `src/tts/tts.ts` remains the compatibility facade
-- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/hook-compat.ts`
-- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/plugin-api.ts`
-- compatibility plugin-registry facade ownership now routes through `src/extension-host/plugin-registry.ts`
-- compatibility plugin-registry policy now routes through `src/extension-host/plugin-registry-compat.ts`
-- compatibility plugin-registry registration actions now route through `src/extension-host/plugin-registry-registrations.ts`
+- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/compat/hook-compat.ts`
+- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/compat/plugin-api.ts`
+- compatibility plugin-registry facade ownership now routes through `src/extension-host/compat/plugin-registry.ts`
+- compatibility plugin-registry policy now routes through `src/extension-host/compat/plugin-registry-compat.ts`
+- compatibility plugin-registry registration actions now route through `src/extension-host/compat/plugin-registry-registrations.ts`
 - service startup, stop ordering, service-context creation, and failure logging now route through `src/extension-host/service-lifecycle.ts`
 - CLI duplicate detection, registrar invocation, and async failure logging now route through `src/extension-host/cli-lifecycle.ts`
 - gateway method-id aggregation, plugin diagnostic shaping, and extra-handler composition now route through `src/extension-host/gateway-methods.ts`
@@ -64,30 +64,30 @@ What has been implemented:
 - provider onboarding option building, model-picker entry building, and provider-method choice resolution now route through `src/extension-host/provider-wizard.ts`
 - loaded-provider auth application, plugin-enable gating, auth-method execution, and post-auth default-model handling now route through `src/extension-host/provider-auth-flow.ts`
 - provider post-selection hook lookup and invocation now route through `src/extension-host/provider-model-selection.ts`
-- plugin SDK alias resolution now routes through `src/extension-host/loader-compat.ts`
-- loader alias-wired module loader creation now routes through `src/extension-host/loader-module-loader.ts`
-- loader cache key construction and registry cache control now route through `src/extension-host/loader-cache.ts`
-- loader lazy runtime proxy creation now routes through `src/extension-host/loader-runtime-proxy.ts`
-- loader provenance helpers now route through `src/extension-host/loader-provenance.ts`
-- loader duplicate-order and record/error policy now route through `src/extension-host/loader-policy.ts`
-- loader discovery policy outcomes now route through `src/extension-host/loader-discovery-policy.ts`
-- loader initial candidate planning and record creation now route through `src/extension-host/loader-records.ts`
-- loader entry-path opening and module import now route through `src/extension-host/loader-import.ts`
-- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/loader-runtime.ts`
-- loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts`
-- loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts`
-- loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts`
-- loader host process state now routes through `src/extension-host/loader-host-state.ts`
-- loader preflight and cache-hit setup now routes through `src/extension-host/loader-preflight.ts`
-- loader post-preflight pipeline composition now routes through `src/extension-host/loader-pipeline.ts`
-- loader execution setup composition now routes through `src/extension-host/loader-execution.ts`
-- loader discovery and manifest bootstrap now routes through `src/extension-host/loader-bootstrap.ts`
-- loader mutable activation state now routes through `src/extension-host/loader-session.ts`
-- loader session run and finalization composition now routes through `src/extension-host/loader-run.ts`
-- loader activation policy outcomes now route through `src/extension-host/loader-activation-policy.ts`
-- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values
-- loader finalization policy results now route through `src/extension-host/loader-finalization-policy.ts`
-- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/loader-finalize.ts`
+- plugin SDK alias resolution now routes through `src/extension-host/compat/loader-compat.ts`
+- loader alias-wired module loader creation now routes through `src/extension-host/activation/loader-module-loader.ts`
+- loader cache key construction and registry cache control now route through `src/extension-host/activation/loader-cache.ts`
+- loader lazy runtime proxy creation now routes through `src/extension-host/activation/loader-runtime-proxy.ts`
+- loader provenance helpers now route through `src/extension-host/policy/loader-provenance.ts`
+- loader duplicate-order and record/error policy now route through `src/extension-host/policy/loader-policy.ts`
+- loader discovery policy outcomes now route through `src/extension-host/policy/loader-discovery-policy.ts`
+- loader initial candidate planning and record creation now route through `src/extension-host/activation/loader-records.ts`
+- loader entry-path opening and module import now route through `src/extension-host/activation/loader-import.ts`
+- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/activation/loader-runtime.ts`
+- loader post-import planning and `register(...)` execution now route through `src/extension-host/activation/loader-register.ts`
+- loader per-candidate orchestration now routes through `src/extension-host/activation/loader-flow.ts`
+- loader top-level load orchestration now routes through `src/extension-host/activation/loader-orchestrator.ts`
+- loader host process state now routes through `src/extension-host/activation/loader-host-state.ts`
+- loader preflight and cache-hit setup now routes through `src/extension-host/activation/loader-preflight.ts`
+- loader post-preflight pipeline composition now routes through `src/extension-host/activation/loader-pipeline.ts`
+- loader execution setup composition now routes through `src/extension-host/activation/loader-execution.ts`
+- loader discovery and manifest bootstrap now routes through `src/extension-host/activation/loader-bootstrap.ts`
+- loader mutable activation state now routes through `src/extension-host/activation/loader-session.ts`
+- loader session run and finalization composition now routes through `src/extension-host/activation/loader-run.ts`
+- loader activation policy outcomes now route through `src/extension-host/policy/loader-activation-policy.ts`
+- loader record-state transitions now route through `src/extension-host/activation/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values
+- loader finalization policy results now route through `src/extension-host/policy/loader-finalization-policy.ts`
+- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/activation/loader-finalize.ts`
 
 How it has been implemented:
 
@@ -108,7 +108,7 @@ How it has been implemented:
 - by extracting post-preflight execution setup and session-run composition into a host-owned loader-pipeline helper before broadening the schema-driven host lifecycle model
 - by extracting runtime creation, registry creation, bootstrap setup, module-loader creation, and session creation into a host-owned loader-execution helper before broadening the schema-driven host lifecycle model
 - by moving mutable activation state into a host-owned loader session before broadening the schema-driven host lifecycle model
-- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation
+- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/policy/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation
 - by turning open-allowlist discovery warnings into explicit host-owned discovery-policy results before broadening the schema-driven host lifecycle model
 - by moving duplicate precedence, config enablement, and early memory-slot gating into explicit host-owned activation-policy outcomes before broadening the schema-driven host lifecycle model
 - by turning provenance-based untracked-extension warnings and final memory-slot warnings into explicit host-owned finalization-policy results before broadening the schema-driven host lifecycle model

docs/.internal/extension-host-migration/openclaw-extension-host-implementation-guide.md

@@ -60,40 +60,40 @@ What has been implemented so far:
 - `src/plugins/manifest-registry.ts` now carries a normalized `resolvedExtension` alongside the legacy flat manifest record
 - `src/extension-host/resolved-registry.ts` now exposes a host-owned resolved-extension registry view
 - an initial Phase 0 inventory now exists in `src/extension-host/cutover-inventory.md`
-- plugin SDK alias resolution now routes through `src/extension-host/loader-compat.ts`
-- loader alias-wired module loader creation now routes through `src/extension-host/loader-module-loader.ts`
-- loader cache key construction and registry cache control now route through `src/extension-host/loader-cache.ts`
-- loader lazy runtime proxy creation now routes through `src/extension-host/loader-runtime-proxy.ts`
-- loader provenance helpers now route through `src/extension-host/loader-provenance.ts`
-- loader duplicate-order and record/error policy now route through `src/extension-host/loader-policy.ts`
-- loader discovery policy outcomes now route through `src/extension-host/loader-discovery-policy.ts`
-- loader initial candidate planning and record creation now route through `src/extension-host/loader-records.ts`
-- loader entry-path opening and module import now route through `src/extension-host/loader-import.ts`
-- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/loader-runtime.ts`
-- loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts`
-- loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts`
-- loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts`
-- loader host process state now routes through `src/extension-host/loader-host-state.ts`
-- loader preflight and cache-hit setup now routes through `src/extension-host/loader-preflight.ts`
-- loader post-preflight pipeline composition now routes through `src/extension-host/loader-pipeline.ts`
-- loader execution setup composition now routes through `src/extension-host/loader-execution.ts`
-- loader discovery and manifest bootstrap now routes through `src/extension-host/loader-bootstrap.ts`
-- loader mutable activation state now routes through `src/extension-host/loader-session.ts`
-- loader session run and finalization composition now routes through `src/extension-host/loader-run.ts`
-- loader activation policy outcomes now route through `src/extension-host/loader-activation-policy.ts`
-- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values
-- loader finalization policy results now route through `src/extension-host/loader-finalization-policy.ts`
-- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/loader-finalize.ts`
+- plugin SDK alias resolution now routes through `src/extension-host/compat/loader-compat.ts`
+- loader alias-wired module loader creation now routes through `src/extension-host/activation/loader-module-loader.ts`
+- loader cache key construction and registry cache control now route through `src/extension-host/activation/loader-cache.ts`
+- loader lazy runtime proxy creation now routes through `src/extension-host/activation/loader-runtime-proxy.ts`
+- loader provenance helpers now route through `src/extension-host/policy/loader-provenance.ts`
+- loader duplicate-order and record/error policy now route through `src/extension-host/policy/loader-policy.ts`
+- loader discovery policy outcomes now route through `src/extension-host/policy/loader-discovery-policy.ts`
+- loader initial candidate planning and record creation now route through `src/extension-host/activation/loader-records.ts`
+- loader entry-path opening and module import now route through `src/extension-host/activation/loader-import.ts`
+- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/activation/loader-runtime.ts`
+- loader post-import planning and `register(...)` execution now route through `src/extension-host/activation/loader-register.ts`
+- loader per-candidate orchestration now routes through `src/extension-host/activation/loader-flow.ts`
+- loader top-level load orchestration now routes through `src/extension-host/activation/loader-orchestrator.ts`
+- loader host process state now routes through `src/extension-host/activation/loader-host-state.ts`
+- loader preflight and cache-hit setup now routes through `src/extension-host/activation/loader-preflight.ts`
+- loader post-preflight pipeline composition now routes through `src/extension-host/activation/loader-pipeline.ts`
+- loader execution setup composition now routes through `src/extension-host/activation/loader-execution.ts`
+- loader discovery and manifest bootstrap now routes through `src/extension-host/activation/loader-bootstrap.ts`
+- loader mutable activation state now routes through `src/extension-host/activation/loader-session.ts`
+- loader session run and finalization composition now routes through `src/extension-host/activation/loader-run.ts`
+- loader activation policy outcomes now route through `src/extension-host/policy/loader-activation-policy.ts`
+- loader record-state transitions now route through `src/extension-host/activation/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values
+- loader finalization policy results now route through `src/extension-host/policy/loader-finalization-policy.ts`
+- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/activation/loader-finalize.ts`
 - runtime registration normalization has started in `src/extension-host/runtime-registrations.ts` for channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook registrations
 - low-risk runtime compatibility writes for channel, provider, gateway-method, HTTP-route, tool, CLI, service, command, context-engine, and hook registrations now route through `src/extension-host/registry-writes.ts`
 - context-engine registration and runtime resolution now route through `src/extension-host/context-engine-runtime.ts` while `src/context-engine/registry.ts` remains the compatibility facade
-- exclusive-slot selection and default-slot resolution now route through `src/extension-host/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade
+- exclusive-slot selection and default-slot resolution now route through `src/extension-host/policy/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade
 - ACP backend registration and resolution now route through `src/extension-host/acp-runtime-backend-registry.ts` while `src/acp/runtime/registry.ts` remains the compatibility facade
-- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/hook-compat.ts`
-- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/plugin-api.ts`
-- compatibility plugin-registry facade ownership now routes through `src/extension-host/plugin-registry.ts`
-- compatibility plugin-registry policy now routes through `src/extension-host/plugin-registry-compat.ts`
-- compatibility plugin-registry registration actions now route through `src/extension-host/plugin-registry-registrations.ts`
+- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/compat/hook-compat.ts`
+- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/compat/plugin-api.ts`
+- compatibility plugin-registry facade ownership now routes through `src/extension-host/compat/plugin-registry.ts`
+- compatibility plugin-registry policy now routes through `src/extension-host/compat/plugin-registry-compat.ts`
+- compatibility plugin-registry registration actions now route through `src/extension-host/compat/plugin-registry-registrations.ts`
 - host-owned runtime registry accessors now route through `src/extension-host/runtime-registry.ts`, and the channel, provider, tool, command, HTTP-route, gateway-method, CLI, and service slices now keep host-owned storage there with mirrored legacy compatibility views
 - service startup, stop ordering, service-context creation, and failure logging now route through `src/extension-host/service-lifecycle.ts`
 - CLI duplicate detection, registrar invocation, and async failure logging now route through `src/extension-host/cli-lifecycle.ts`
@@ -102,12 +102,13 @@ What has been implemented so far:
 - plugin provider projection from registry entries into runtime provider objects now routes through `src/extension-host/provider-runtime.ts`
 - plugin provider discovery filtering, order grouping, and result normalization now route through `src/extension-host/provider-discovery.ts`
 - provider matching, auth-method selection, config-patch merging, and default-model application now route through `src/extension-host/provider-auth.ts`
-- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade
-- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades
+- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/policy/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade
+- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/policy/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/policy/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades
 - TTS provider metadata, provider ordering, API-key resolution, configuration checks, and telephony support now route through `src/extension-host/tts-runtime-registry.ts`, provider execution loops, output-format selection, telephony synthesis, and provider-error shaping now route through `src/extension-host/tts-runtime-execution.ts`, provider selection plus request setup now route through `src/extension-host/tts-runtime-setup.ts`, TTS config normalization, defaults, and model-override policy now route through `src/extension-host/tts-config.ts`, prefs-path resolution, auto-mode policy, and persisted TTS preference reads and writes now route through `src/extension-host/tts-preferences.ts`, auto-TTS gating, directive cleanup, truncation, summarization, and payload planning now route through `src/extension-host/tts-payload.ts`, and last-attempt state plus shared status snapshots now route through `src/extension-host/tts-status.ts` while `src/tts/tts.ts` remains the compatibility facade
 - provider onboarding option building, model-picker entry building, and provider-method choice resolution now route through `src/extension-host/provider-wizard.ts`
 - loaded-provider auth application, plugin-enable gating, auth-method execution, and post-auth default-model handling now route through `src/extension-host/provider-auth-flow.ts`
 - provider post-selection hook lookup and invocation now route through `src/extension-host/provider-model-selection.ts`
+- the first filesystem-layout pass has also landed: activation helpers now live under `src/extension-host/activation/`, host-owned policy seams now live under `src/extension-host/policy/`, and compatibility facades now live under `src/extension-host/compat/`, matching the module layout already called for in the transition plan without changing the underlying ownership split
 - several static and lookup consumers now read through the host boundary or resolved-extension model:
   - channel registry and dock lookups
   - message-channel normalization
@@ -161,7 +162,7 @@ How it has been done:
 - by extracting post-preflight execution setup and session-run composition into a host-owned loader-pipeline helper before shrinking the remaining orchestrator surface
 - by extracting runtime creation, registry creation, bootstrap setup, module-loader creation, and session creation into a host-owned loader-execution helper before shrinking the remaining orchestrator surface
 - by moving mutable activation state such as seen-id tracking, memory-slot selection, and finalization inputs into a host-owned loader session instead of leaving them in top-level loader variables
-- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation
+- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/policy/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation
 - by turning open-allowlist discovery warnings into explicit host-owned discovery-policy results before the orchestrator logs them
 - by moving duplicate precedence, config enablement, and early memory-slot gating into explicit host-owned activation-policy outcomes instead of leaving them inline in the loader flow
 - by turning provenance-based untracked-extension warnings and final memory-slot warnings into explicit host-owned finalization-policy results before the finalizer applies them
@@ -297,7 +298,7 @@ Recent plan refinements:
 - it now explicitly treats interactive callback routing, namespace ownership, dedupe, and fallback behavior as first-class migration surfaces
 - it now explicitly treats inbound claim as a canonical ingress-stage concern rather than a permanent plugin-era hook shape
 - it now explicitly treats Telegram and Discord as the first validated rollout targets for interactive control surfaces while keeping the underlying contracts generic, host-owned, and kernel-agnostic
-- it now explicitly treats embeddings, media understanding, and TTS as in-progress host-owned subsystem runtimes, with embedding backend definitions now shared between `src/extension-host/embedding-runtime-backends.ts`, `src/extension-host/embedding-runtime-registry.ts`, and `src/extension-host/runtime-backend-catalog.ts`, shared default and preferred runtime-backend ordering plus fallback chaining now landing in `src/extension-host/runtime-backend-policy.ts`, the catalog helpers for generic subsystem ordering, media auto-ordering, and TTS preferred-provider ordering now also routing through that shared backend-policy layer, embedding selection, fallback routing, explicit fallback policy in `src/extension-host/embedding-runtime-policy.ts`, public runtime surface, result typing, manager-side batch and fallback policy, sync plus reindex planning, sync plus reindex orchestration, reindex sync-body execution plus unsafe reset, safe-reindex temp-db creation, file swap, reopen, and cleanup, plus runtime-backend catalog descriptors now extracted and embedding auto-provider selection, local setup guidance, and memory doctor guidance already consuming the catalog-backed embedding backend-policy order, media backend definitions now shared between `src/extension-host/media-runtime-backends.ts`, `src/extension-host/media-runtime-registry.ts`, and `src/extension-host/runtime-backend-catalog.ts`, with media registry, explicit selection policy in `src/extension-host/media-runtime-policy.ts`, execution, auto-entry selection, orchestration, planning helpers, remaining API composition, lazy entrypoint wiring, plus runtime-backend catalog descriptors now extracted and media provider candidate ordering plus default-model fallback lookup already consuming that catalog-backed backend-policy order, TTS backend definitions now shared between `src/extension-host/tts-runtime-backends.ts`, `src/extension-host/tts-runtime-registry.ts`, and `src/extension-host/runtime-backend-catalog.ts`, with TTS registry, execution, request setup, config normalization, preferences, payload planning, shared status state, API composition, plus runtime-backend catalog descriptors now extracted, initial runtime-family arbitration now landing in `src/extension-host/runtime-backend-arbitration.ts`, explicit configured-fallback policy now landing in `src/extension-host/tts-runtime-policy.ts`, and TTS request setup, status, plus compatibility provider-order exports already consuming that arbitration-backed backend-policy order, and broader consumer adoption and arbitration on top of those catalog-backed runtime-family descriptors still pending, all with capability routing, typed request envelopes, provider-id normalization, and fallback policy
+- it now explicitly treats embeddings, media understanding, and TTS as in-progress host-owned subsystem runtimes, with embedding backend definitions now shared between `src/extension-host/embedding-runtime-backends.ts`, `src/extension-host/embedding-runtime-registry.ts`, and `src/extension-host/runtime-backend-catalog.ts`, shared default and preferred runtime-backend ordering plus fallback chaining now landing in `src/extension-host/policy/runtime-backend-policy.ts`, the catalog helpers for generic subsystem ordering, media auto-ordering, and TTS preferred-provider ordering now also routing through that shared backend-policy layer, embedding selection, fallback routing, explicit fallback policy in `src/extension-host/policy/embedding-runtime-policy.ts`, public runtime surface, result typing, manager-side batch and fallback policy, sync plus reindex planning, sync plus reindex orchestration, reindex sync-body execution plus unsafe reset, safe-reindex temp-db creation, file swap, reopen, and cleanup, plus runtime-backend catalog descriptors now extracted and embedding auto-provider selection, local setup guidance, and memory doctor guidance already consuming the catalog-backed embedding backend-policy order, media backend definitions now shared between `src/extension-host/media-runtime-backends.ts`, `src/extension-host/media-runtime-registry.ts`, and `src/extension-host/runtime-backend-catalog.ts`, with media registry, explicit selection policy in `src/extension-host/policy/media-runtime-policy.ts`, execution, auto-entry selection, orchestration, planning helpers, remaining API composition, lazy entrypoint wiring, plus runtime-backend catalog descriptors now extracted and media provider candidate ordering plus default-model fallback lookup already consuming that catalog-backed backend-policy order, TTS backend definitions now shared between `src/extension-host/tts-runtime-backends.ts`, `src/extension-host/tts-runtime-registry.ts`, and `src/extension-host/runtime-backend-catalog.ts`, with TTS registry, execution, request setup, config normalization, preferences, payload planning, shared status state, API composition, plus runtime-backend catalog descriptors now extracted, initial runtime-family arbitration now landing in `src/extension-host/policy/runtime-backend-arbitration.ts`, explicit configured-fallback policy now landing in `src/extension-host/policy/tts-runtime-policy.ts`, and TTS request setup, status, plus compatibility provider-order exports already consuming that arbitration-backed backend-policy order, and broader consumer adoption and arbitration on top of those catalog-backed runtime-family descriptors still pending, all with capability routing, typed request envelopes, provider-id normalization, and fallback policy
 - it now explicitly rejects widening the legacy `registerProvider(...)` or `ProviderPlugin` surface into a universal runtime API while retaining capability routing, typed request envelopes, provider-id normalization, and fallback behavior where those are part of the target model
 - it now explicitly treats extension-backed search as either a canonical tool contribution or a host-owned runtime backend depending on whether the search surface is agent-visible
 

docs/.internal/extension-host-migration/openclaw-extension-host-lifecycle-and-security-spec.md

@@ -40,16 +40,16 @@ What has been implemented:
 - channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook registration normalization now delegates through `src/extension-host/runtime-registrations.ts`
 - low-risk runtime compatibility writes for channel, provider, gateway-method, HTTP-route, tool, CLI, service, command, context-engine, and hook registrations now delegate through `src/extension-host/registry-writes.ts`
 - context-engine registration and runtime resolution now delegate through `src/extension-host/context-engine-runtime.ts` while `src/context-engine/registry.ts` remains the compatibility facade
-- exclusive-slot selection and default-slot resolution now delegate through `src/extension-host/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade
+- exclusive-slot selection and default-slot resolution now delegate through `src/extension-host/policy/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade
 - ACP backend registration and runtime resolution now delegate through `src/extension-host/acp-runtime-backend-registry.ts` while `src/acp/runtime/registry.ts` remains the compatibility facade
-- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now delegate through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now delegates through `src/extension-host/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now delegate through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now delegate through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now delegate through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now delegate through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now delegate through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now delegate through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade
-- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now delegate through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now delegate through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now delegate through `src/extension-host/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now delegate through `src/extension-host/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now delegate through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now delegate through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now delegate through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain the compatibility facades
+- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now delegate through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now delegates through `src/extension-host/policy/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now delegate through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now delegate through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now delegate through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now delegate through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now delegate through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now delegate through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade
+- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now delegate through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now delegate through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now delegate through `src/extension-host/policy/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now delegate through `src/extension-host/policy/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now delegate through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now delegate through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now delegate through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain the compatibility facades
 - TTS provider metadata, provider ordering, API-key resolution, configuration checks, and telephony support now delegate through `src/extension-host/tts-runtime-registry.ts`, provider execution loops, output-format selection, telephony synthesis, and provider-error shaping now delegate through `src/extension-host/tts-runtime-execution.ts`, provider selection plus request setup now delegate through `src/extension-host/tts-runtime-setup.ts`, TTS config normalization, defaults, and model-override policy now delegate through `src/extension-host/tts-config.ts`, prefs-path resolution, auto-mode policy, and persisted TTS preference reads and writes now delegate through `src/extension-host/tts-preferences.ts`, auto-TTS gating, directive cleanup, truncation, summarization, and payload planning now delegate through `src/extension-host/tts-payload.ts`, and last-attempt state plus shared status snapshots now delegate through `src/extension-host/tts-status.ts` while `src/tts/tts.ts` remains the compatibility facade
-- legacy internal-hook bridging and typed prompt-injection compatibility policy now delegate through `src/extension-host/hook-compat.ts`
-- compatibility `OpenClawPluginApi` composition and logger shaping now delegate through `src/extension-host/plugin-api.ts`
-- compatibility plugin-registry facade ownership now delegates through `src/extension-host/plugin-registry.ts`
-- compatibility plugin-registry policy now delegates through `src/extension-host/plugin-registry-compat.ts`
-- compatibility plugin-registry registration actions now delegate through `src/extension-host/plugin-registry-registrations.ts`
+- legacy internal-hook bridging and typed prompt-injection compatibility policy now delegate through `src/extension-host/compat/hook-compat.ts`
+- compatibility `OpenClawPluginApi` composition and logger shaping now delegate through `src/extension-host/compat/plugin-api.ts`
+- compatibility plugin-registry facade ownership now delegates through `src/extension-host/compat/plugin-registry.ts`
+- compatibility plugin-registry policy now delegates through `src/extension-host/compat/plugin-registry-compat.ts`
+- compatibility plugin-registry registration actions now delegate through `src/extension-host/compat/plugin-registry-registrations.ts`
 - host-owned runtime registry accessors now delegate through `src/extension-host/runtime-registry.ts`, and the channel, provider, tool, command, HTTP-route, gateway-method, CLI, and service slices now keep host-owned storage there with mirrored legacy compatibility views
 - plugin command registration, matching, execution, listing, native command-spec projection, and loader reload clearing now delegate through `src/extension-host/command-runtime.ts`
 - service startup, stop ordering, service-context creation, and failure logging now delegate through `src/extension-host/service-lifecycle.ts`
@@ -62,29 +62,29 @@ What has been implemented:
 - provider onboarding option building, model-picker entry building, and provider-method choice resolution now delegate through `src/extension-host/provider-wizard.ts`
 - loaded-provider auth application, plugin-enable gating, auth-method execution, and post-auth default-model handling now delegate through `src/extension-host/provider-auth-flow.ts`
 - provider post-selection hook lookup and invocation now delegate through `src/extension-host/provider-model-selection.ts`
-- loader alias-wired module loader creation now routes through `src/extension-host/loader-module-loader.ts`
-- loader cache key construction and registry cache control now route through `src/extension-host/loader-cache.ts`
-- loader lazy runtime proxy creation now routes through `src/extension-host/loader-runtime-proxy.ts`
-- loader provenance helpers now route through `src/extension-host/loader-provenance.ts`
-- loader duplicate-order and record/error policy now route through `src/extension-host/loader-policy.ts`
-- loader discovery policy outcomes now route through `src/extension-host/loader-discovery-policy.ts`
-- loader initial candidate planning and record creation now route through `src/extension-host/loader-records.ts`
-- loader entry-path opening and module import now route through `src/extension-host/loader-import.ts`
-- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/loader-runtime.ts`
-- loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts`
-- loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts`
-- loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts`
-- loader host process state now routes through `src/extension-host/loader-host-state.ts`
-- loader preflight and cache-hit setup now routes through `src/extension-host/loader-preflight.ts`
-- loader post-preflight pipeline composition now routes through `src/extension-host/loader-pipeline.ts`
-- loader execution setup composition now routes through `src/extension-host/loader-execution.ts`
-- loader discovery and manifest bootstrap now routes through `src/extension-host/loader-bootstrap.ts`
-- loader mutable activation state now routes through `src/extension-host/loader-session.ts`
-- loader session run and finalization composition now routes through `src/extension-host/loader-run.ts`
-- loader activation policy outcomes now route through `src/extension-host/loader-activation-policy.ts`
-- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values
-- loader finalization policy results now route through `src/extension-host/loader-finalization-policy.ts`
-- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/loader-finalize.ts`
+- loader alias-wired module loader creation now routes through `src/extension-host/activation/loader-module-loader.ts`
+- loader cache key construction and registry cache control now route through `src/extension-host/activation/loader-cache.ts`
+- loader lazy runtime proxy creation now routes through `src/extension-host/activation/loader-runtime-proxy.ts`
+- loader provenance helpers now route through `src/extension-host/policy/loader-provenance.ts`
+- loader duplicate-order and record/error policy now route through `src/extension-host/policy/loader-policy.ts`
+- loader discovery policy outcomes now route through `src/extension-host/policy/loader-discovery-policy.ts`
+- loader initial candidate planning and record creation now route through `src/extension-host/activation/loader-records.ts`
+- loader entry-path opening and module import now route through `src/extension-host/activation/loader-import.ts`
+- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/activation/loader-runtime.ts`
+- loader post-import planning and `register(...)` execution now route through `src/extension-host/activation/loader-register.ts`
+- loader per-candidate orchestration now routes through `src/extension-host/activation/loader-flow.ts`
+- loader top-level load orchestration now routes through `src/extension-host/activation/loader-orchestrator.ts`
+- loader host process state now routes through `src/extension-host/activation/loader-host-state.ts`
+- loader preflight and cache-hit setup now routes through `src/extension-host/activation/loader-preflight.ts`
+- loader post-preflight pipeline composition now routes through `src/extension-host/activation/loader-pipeline.ts`
+- loader execution setup composition now routes through `src/extension-host/activation/loader-execution.ts`
+- loader discovery and manifest bootstrap now routes through `src/extension-host/activation/loader-bootstrap.ts`
+- loader mutable activation state now routes through `src/extension-host/activation/loader-session.ts`
+- loader session run and finalization composition now routes through `src/extension-host/activation/loader-run.ts`
+- loader activation policy outcomes now route through `src/extension-host/policy/loader-activation-policy.ts`
+- loader record-state transitions now route through `src/extension-host/activation/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values
+- loader finalization policy results now route through `src/extension-host/policy/loader-finalization-policy.ts`
+- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/activation/loader-finalize.ts`
 
 How it has been implemented:
 
@@ -117,7 +117,7 @@ How it has been implemented:
 - by adding explicit compatibility `lifecycleState` mapping on loader-owned plugin records before enforcing the loader lifecycle state machine
 - by promoting successfully registered plugins to `ready` during host-owned finalization while leaving broader activation-state semantics for later phases
 - by moving mutable activation state such as seen-id tracking, memory-slot selection, and finalization inputs into a host-owned loader session before broader activation-state semantics move
-- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation
+- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/policy/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation
 - by turning open-allowlist discovery warnings into explicit host-owned discovery-policy results before the orchestrator logs them
 - by moving duplicate precedence, config enablement, and early memory-slot gating into explicit host-owned activation-policy outcomes before broader policy semantics move
 - by turning provenance-based untracked-extension warnings and final memory-slot warnings into explicit host-owned finalization-policy results before the finalizer applies them

docs/.internal/extension-host-migration/openclaw-kernel-event-pipeline-spec.md

@@ -37,10 +37,10 @@ Relevant prerequisite work that has landed:
 - config doc baseline generation now uses the same host-owned resolved-extension data path
 - channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook registration normalization now has a host-owned helper boundary
 - context-engine registration and runtime resolution now have a host-owned helper boundary in `src/extension-host/context-engine-runtime.ts`
-- exclusive-slot selection and default-slot resolution now have a host-owned helper boundary in `src/extension-host/slot-arbitration.ts`
+- exclusive-slot selection and default-slot resolution now have a host-owned helper boundary in `src/extension-host/policy/slot-arbitration.ts`
 - ACP backend registration and runtime resolution now have a host-owned helper boundary in `src/extension-host/acp-runtime-backend-registry.ts`
-- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now have a host-owned helper boundary in `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now has a host-owned helper boundary in `src/extension-host/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now have host-owned boundaries in `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now have a host-owned helper boundary in `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now have a host-owned helper boundary in `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now has a host-owned helper boundary in `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now have a host-owned helper boundary in `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now have a host-owned helper boundary in `src/extension-host/embedding-safe-reindex.ts`
-- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now have a host-owned helper boundary in `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now have a host-owned helper boundary in `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now have a host-owned helper boundary in `src/extension-host/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now have a host-owned helper boundary in `src/extension-host/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now have a host-owned helper boundary in `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now have host-owned helper boundaries in `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now have host-owned helper boundaries in `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts`
+- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now have a host-owned helper boundary in `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now has a host-owned helper boundary in `src/extension-host/policy/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now have host-owned boundaries in `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now have a host-owned helper boundary in `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now have a host-owned helper boundary in `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now has a host-owned helper boundary in `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now have a host-owned helper boundary in `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now have a host-owned helper boundary in `src/extension-host/embedding-safe-reindex.ts`
+- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now have a host-owned helper boundary in `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now have a host-owned helper boundary in `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now have a host-owned helper boundary in `src/extension-host/policy/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now have a host-owned helper boundary in `src/extension-host/policy/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now have a host-owned helper boundary in `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now have host-owned helper boundaries in `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now have host-owned helper boundaries in `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts`
 - TTS provider metadata, provider ordering, API-key resolution, configuration checks, and telephony support now have a host-owned helper boundary in `src/extension-host/tts-runtime-registry.ts`, provider execution loops, output-format selection, telephony synthesis, and provider-error shaping now have a host-owned helper boundary in `src/extension-host/tts-runtime-execution.ts`, provider selection plus request setup now have a host-owned helper boundary in `src/extension-host/tts-runtime-setup.ts`, TTS config normalization, defaults, and model-override policy now have a host-owned helper boundary in `src/extension-host/tts-config.ts`, prefs-path resolution, auto-mode policy, and persisted TTS preference reads and writes now have a host-owned helper boundary in `src/extension-host/tts-preferences.ts`, auto-TTS gating, directive cleanup, truncation, summarization, and payload planning now have a host-owned helper boundary in `src/extension-host/tts-payload.ts`, and last-attempt state plus shared status snapshots now have a host-owned helper boundary in `src/extension-host/tts-status.ts`
 - loader cache key construction and registry cache control now have a host-owned helper boundary
 - loader provenance helpers now have a host-owned helper boundary
@@ -66,11 +66,11 @@ Relevant prerequisite work that has landed:
 - loader finalization policy outcomes now have a host-owned helper boundary
 - loader final cache, readiness promotion, and activation finalization now has a host-owned helper boundary
 - low-risk channel, provider, gateway-method, HTTP-route, tool, CLI, service, command, context-engine, and hook compatibility writes now have a host-owned helper boundary in `src/extension-host/registry-writes.ts`
-- legacy internal-hook bridging and typed prompt-injection compatibility policy now have a host-owned helper boundary in `src/extension-host/hook-compat.ts`
-- compatibility `OpenClawPluginApi` composition and logger shaping now have a host-owned helper boundary in `src/extension-host/plugin-api.ts`
-- compatibility plugin-registry facade ownership now has a host-owned helper boundary in `src/extension-host/plugin-registry.ts`
-- compatibility plugin-registry policy now has a host-owned helper boundary in `src/extension-host/plugin-registry-compat.ts`
-- compatibility plugin-registry registration actions now have a host-owned helper boundary in `src/extension-host/plugin-registry-registrations.ts`
+- legacy internal-hook bridging and typed prompt-injection compatibility policy now have a host-owned helper boundary in `src/extension-host/compat/hook-compat.ts`
+- compatibility `OpenClawPluginApi` composition and logger shaping now have a host-owned helper boundary in `src/extension-host/compat/plugin-api.ts`
+- compatibility plugin-registry facade ownership now has a host-owned helper boundary in `src/extension-host/compat/plugin-registry.ts`
+- compatibility plugin-registry policy now has a host-owned helper boundary in `src/extension-host/compat/plugin-registry-compat.ts`
+- compatibility plugin-registry registration actions now have a host-owned helper boundary in `src/extension-host/compat/plugin-registry-registrations.ts`
 - host-owned runtime registry accessors now have a host-owned helper boundary in `src/extension-host/runtime-registry.ts`, and the channel, provider, tool, command, HTTP-route, gateway-method, CLI, and service slices now keep host-owned storage there with mirrored legacy compatibility views
 - plugin command registration, matching, execution, listing, native command-spec projection, and loader reload clearing now have a host-owned helper boundary in `src/extension-host/command-runtime.ts`
 - service startup, stop ordering, service-context creation, and failure logging now have a host-owned helper boundary in `src/extension-host/service-lifecycle.ts`

docs/.internal/extension-host-migration/openclaw-kernel-extension-host-transition-plan.md

@@ -45,40 +45,40 @@ What has landed:
 - plugin manifest records now carry a normalized `resolvedExtension`
 - a host-owned resolved-extension registry view now exists for static consumers
 - an initial Phase 0 cutover inventory now exists in `src/extension-host/cutover-inventory.md`
-- plugin SDK alias resolution now routes through `src/extension-host/loader-compat.ts`
-- loader alias-wired module loader creation now routes through `src/extension-host/loader-module-loader.ts`
-- loader cache key construction and registry cache control now route through `src/extension-host/loader-cache.ts`
-- loader lazy runtime proxy creation now routes through `src/extension-host/loader-runtime-proxy.ts`
-- loader provenance helpers now route through `src/extension-host/loader-provenance.ts`
-- loader duplicate-order and record/error policy now route through `src/extension-host/loader-policy.ts`
-- loader discovery policy outcomes now route through `src/extension-host/loader-discovery-policy.ts`
-- loader initial candidate planning and record creation now route through `src/extension-host/loader-records.ts`
-- loader entry-path opening and module import now route through `src/extension-host/loader-import.ts`
-- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/loader-runtime.ts`
-- loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts`
-- loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts`
-- loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts`
-- loader host process state now routes through `src/extension-host/loader-host-state.ts`
-- loader preflight and cache-hit setup now routes through `src/extension-host/loader-preflight.ts`
-- loader post-preflight pipeline composition now routes through `src/extension-host/loader-pipeline.ts`
-- loader execution setup composition now routes through `src/extension-host/loader-execution.ts`
-- loader discovery and manifest bootstrap now routes through `src/extension-host/loader-bootstrap.ts`
-- loader mutable activation state now routes through `src/extension-host/loader-session.ts`
-- loader session run and finalization composition now routes through `src/extension-host/loader-run.ts`
-- loader activation policy outcomes now route through `src/extension-host/loader-activation-policy.ts`
-- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values
-- loader finalization policy results now route through `src/extension-host/loader-finalization-policy.ts`
-- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/loader-finalize.ts`
+- plugin SDK alias resolution now routes through `src/extension-host/compat/loader-compat.ts`
+- loader alias-wired module loader creation now routes through `src/extension-host/activation/loader-module-loader.ts`
+- loader cache key construction and registry cache control now route through `src/extension-host/activation/loader-cache.ts`
+- loader lazy runtime proxy creation now routes through `src/extension-host/activation/loader-runtime-proxy.ts`
+- loader provenance helpers now route through `src/extension-host/policy/loader-provenance.ts`
+- loader duplicate-order and record/error policy now route through `src/extension-host/policy/loader-policy.ts`
+- loader discovery policy outcomes now route through `src/extension-host/policy/loader-discovery-policy.ts`
+- loader initial candidate planning and record creation now route through `src/extension-host/activation/loader-records.ts`
+- loader entry-path opening and module import now route through `src/extension-host/activation/loader-import.ts`
+- loader module-export resolution, config validation, and memory-slot load decisions now route through `src/extension-host/activation/loader-runtime.ts`
+- loader post-import planning and `register(...)` execution now route through `src/extension-host/activation/loader-register.ts`
+- loader per-candidate orchestration now routes through `src/extension-host/activation/loader-flow.ts`
+- loader top-level load orchestration now routes through `src/extension-host/activation/loader-orchestrator.ts`
+- loader host process state now routes through `src/extension-host/activation/loader-host-state.ts`
+- loader preflight and cache-hit setup now routes through `src/extension-host/activation/loader-preflight.ts`
+- loader post-preflight pipeline composition now routes through `src/extension-host/activation/loader-pipeline.ts`
+- loader execution setup composition now routes through `src/extension-host/activation/loader-execution.ts`
+- loader discovery and manifest bootstrap now routes through `src/extension-host/activation/loader-bootstrap.ts`
+- loader mutable activation state now routes through `src/extension-host/activation/loader-session.ts`
+- loader session run and finalization composition now routes through `src/extension-host/activation/loader-run.ts`
+- loader activation policy outcomes now route through `src/extension-host/policy/loader-activation-policy.ts`
+- loader record-state transitions now route through `src/extension-host/activation/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values
+- loader finalization policy results now route through `src/extension-host/policy/loader-finalization-policy.ts`
+- loader final cache, readiness promotion, and activation finalization now routes through `src/extension-host/activation/loader-finalize.ts`
 - runtime registration normalization has started in `src/extension-host/runtime-registrations.ts` for channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook registrations
 - low-risk runtime compatibility writes for channel, provider, gateway-method, HTTP-route, tool, CLI, service, command, context-engine, and hook registrations now route through `src/extension-host/registry-writes.ts`
 - context-engine registration and runtime resolution now route through `src/extension-host/context-engine-runtime.ts` while `src/context-engine/registry.ts` remains the compatibility facade
-- exclusive-slot selection and default-slot resolution now route through `src/extension-host/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade
+- exclusive-slot selection and default-slot resolution now route through `src/extension-host/policy/slot-arbitration.ts` while `src/plugins/slots.ts` remains the compatibility facade
 - ACP backend registration and resolution now route through `src/extension-host/acp-runtime-backend-registry.ts` while `src/acp/runtime/registry.ts` remains the compatibility facade
-- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/hook-compat.ts`
-- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/plugin-api.ts`
-- compatibility plugin-registry facade ownership now routes through `src/extension-host/plugin-registry.ts`
-- compatibility plugin-registry policy now routes through `src/extension-host/plugin-registry-compat.ts`
-- compatibility plugin-registry registration actions now route through `src/extension-host/plugin-registry-registrations.ts`
+- legacy internal-hook bridging and typed prompt-injection compatibility policy now route through `src/extension-host/compat/hook-compat.ts`
+- compatibility `OpenClawPluginApi` composition and logger shaping now route through `src/extension-host/compat/plugin-api.ts`
+- compatibility plugin-registry facade ownership now routes through `src/extension-host/compat/plugin-registry.ts`
+- compatibility plugin-registry policy now routes through `src/extension-host/compat/plugin-registry-compat.ts`
+- compatibility plugin-registry registration actions now route through `src/extension-host/compat/plugin-registry-registrations.ts`
 - host-owned runtime registry accessors now route through `src/extension-host/runtime-registry.ts`, and the channel, provider, tool, command, HTTP-route, gateway-method, CLI, and service slices now keep host-owned storage there with mirrored legacy compatibility views
 - plugin command registration, matching, execution, listing, native command-spec projection, and loader reload clearing now route through `src/extension-host/command-runtime.ts`
 - service startup, stop ordering, service-context creation, and failure logging now route through `src/extension-host/service-lifecycle.ts`
@@ -88,8 +88,8 @@ What has landed:
 - plugin provider projection from registry entries into runtime provider objects now routes through `src/extension-host/provider-runtime.ts`
 - plugin provider discovery filtering, order grouping, and result normalization now route through `src/extension-host/provider-discovery.ts`
 - provider matching, auth-method selection, config-patch merging, and default-model application now route through `src/extension-host/provider-auth.ts`
-- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade
-- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades
+- embedding-provider auto-selection, provider creation, local-setup guidance, and primary plus fallback routing now route through `src/extension-host/embedding-runtime-registry.ts`, shared fallback-model selection now routes through `src/extension-host/policy/embedding-runtime-policy.ts`, the public embedding runtime surface plus result typing now route through `src/extension-host/embedding-runtime.ts` and `src/extension-host/embedding-runtime-types.ts`, manager-side batch policy plus fallback activation now route through `src/extension-host/embedding-manager-runtime.ts`, sync plus reindex planning now route through `src/extension-host/embedding-sync-planning.ts`, sync plus reindex orchestration now route through `src/extension-host/embedding-sync-execution.ts`, reindex sync-body execution plus unsafe reset now route through `src/extension-host/embedding-reindex-execution.ts`, and safe-reindex temp-db creation, file swap, reopen, and cleanup now route through `src/extension-host/embedding-safe-reindex.ts` while `src/memory/embeddings.ts` remains the compatibility facade
+- built-in media backend definitions, provider normalization, auto-selection seed order, selector-key shaping, and default-model metadata now route through `src/extension-host/media-runtime-backends.ts`; override merging and runtime lookup now route through `src/extension-host/media-runtime-registry.ts`; shared default and preferred runtime-backend ordering plus fallback chaining now route through `src/extension-host/policy/runtime-backend-policy.ts`; provider candidate ordering, active-model precedence, and default-model fallback selection now route through `src/extension-host/policy/media-runtime-policy.ts`; provider and CLI entry execution, output parsing, provider query normalization, provider auth/context shaping, and proxy-aware fetch handling now route through `src/extension-host/media-runtime-execution.ts`; local-binary probing, auto-entry selection, and top-level capability orchestration now route through `src/extension-host/media-runtime-auto.ts` and `src/extension-host/media-runtime-orchestration.ts`; and media prompt, timeout, scope, model-entry, concurrency, and decision helpers now route through `src/extension-host/media-runtime-config.ts` and `src/extension-host/media-runtime-decision.ts` while `src/media-understanding/providers/index.ts`, `src/media-understanding/runner.ts`, `src/media-understanding/runner.entries.ts`, and `src/media-understanding/resolve.ts` remain compatibility facades
 - TTS provider metadata, provider ordering, API-key resolution, configuration checks, and telephony support now route through `src/extension-host/tts-runtime-registry.ts`, provider execution loops, output-format selection, telephony synthesis, and provider-error shaping now route through `src/extension-host/tts-runtime-execution.ts`, provider selection plus request setup now route through `src/extension-host/tts-runtime-setup.ts`, TTS config normalization, defaults, and model-override policy now route through `src/extension-host/tts-config.ts`, prefs-path resolution, auto-mode policy, and persisted TTS preference reads and writes now route through `src/extension-host/tts-preferences.ts`, auto-TTS gating, directive cleanup, truncation, summarization, and payload planning now route through `src/extension-host/tts-payload.ts`, and last-attempt state plus shared status snapshots now route through `src/extension-host/tts-status.ts` while `src/tts/tts.ts` remains the compatibility facade
 - provider onboarding option building, model-picker entry building, and provider-method choice resolution now route through `src/extension-host/provider-wizard.ts`
 - loaded-provider auth application, plugin-enable gating, auth-method execution, and post-auth default-model handling now route through `src/extension-host/provider-auth-flow.ts`
@@ -148,7 +148,7 @@ How it was done:
 - by extracting post-preflight execution setup and session-run composition into a host-owned loader-pipeline helper before shrinking the remaining orchestrator surface
 - by extracting runtime creation, registry creation, bootstrap setup, module-loader creation, and session creation into a host-owned loader-execution helper before shrinking the remaining orchestrator surface
 - by moving mutable activation state such as seen-id tracking, memory-slot selection, and finalization inputs into a host-owned loader session instead of leaving them in top-level loader variables
-- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation
+- by extracting shared provenance path matching and install-rule evaluation into `src/extension-host/policy/loader-provenance.ts` so activation and finalization policy seams reuse one host-owned implementation
 - by turning open-allowlist discovery warnings into explicit host-owned discovery-policy results before the orchestrator logs them
 - by moving duplicate precedence, config enablement, and early memory-slot gating into explicit host-owned activation-policy outcomes instead of leaving them inline in the loader flow
 - by turning provenance-based untracked-extension warnings and final memory-slot warnings into explicit host-owned finalization-policy results before the finalizer applies them
@@ -1494,6 +1494,7 @@ Current implementation status:
 - package metadata and manifest metadata now converge into host-owned normalized records
 - discovery and install metadata parsing now go through host schema helpers
 - partial explicit compatibility now exists through host-owned loader-compat and loader-runtime helpers, but a versioned minimal SDK compatibility layer still does not exist
+- the first filesystem-layout pass has landed too: activation seams now live under `src/extension-host/activation/`, policy seams now live under `src/extension-host/policy/`, and compatibility facades now live under `src/extension-host/compat/`, matching the planned host module layout without changing the current boundary ownership model
 
 ## Phase 2: Extension Host Lifecycle And Registries
 
@@ -1532,7 +1533,7 @@ Current implementation status:
 - partially implemented in a compatibility-preserving form
 - the host now owns active registry state
 - the host now exposes resolved static registries for static consumers
-- activation, loader cache control, loader policy, loader discovery-policy outcomes, loader activation-policy outcomes, loader finalization-policy outcomes, loader runtime decisions, loader top-level load orchestration, loader session state, loader record-state helpers, and loader finalization now route through `src/extension-host/*`
+- activation, loader cache control, loader policy, loader discovery-policy outcomes, loader activation-policy outcomes, loader finalization-policy outcomes, loader runtime decisions, loader top-level load orchestration, loader session state, loader record-state helpers, and loader finalization now route through `src/extension-host/*`, with activation helpers organized under `src/extension-host/activation/`, policy helpers under `src/extension-host/policy/`, and compatibility facades under `src/extension-host/compat/`
 - broader lifecycle ownership beyond the loader state machine, registration surfaces, policy gates, and activation-state management are still pending
 
 ## Phase 3: Broader Legacy Compatibility Bridges