agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/kernel/bootstrap.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""生产 composition root（Phase 1 Task 4 Step 4）。
+"""生产 composition root（Kernel Task 4 Step 4）。
 
 ``build_agent_kernel_runtime(config) -> AgentKernelRuntime`` 把 AgentKernel
 栈的全部运行时角色组装成一个可启动 / 可关闭的单元：
@@ -18,6 +18,7 @@ RuntimeAdapter provider、contract digest 或 durable nonce store 时
 ``build_agent_kernel_runtime`` 直接抛 ``RuntimeError``，绝不静默降级到
 内存栈或本地自签 authority。
 """
+
 from __future__ import annotations
 
 import asyncio
@@ -34,7 +35,7 @@ from ksadk.events.session_event import SessionServiceEventStore
 from ksadk.kernel.authorization import AgentControlPermitVerifier, InMemoryNonceStore
 from ksadk.kernel.contract_fingerprints import (
     AGENT_KERNEL_V1_AGGREGATE_DIGEST,
-    runtime_capability_matrix_digest,
+    runtime_capability_admission_digest,
     runtime_capability_matrix_wire_value,
 )
 from ksadk.kernel.contracts import RuntimeCapabilityMatrix
@@ -46,10 +47,13 @@ from ksadk.kernel.store import AgentKernelStore, now_utc
 from ksadk.kernel.worker import AgentKernelWorker
 from ksadk.runtime.adapter import RuntimeAdapter
 
+from ksadk.kernel.readiness import AgentKernelReadiness
+
 AuthorityMode = Literal["local", "hosted"]
 DurabilityTier = Literal["durable", "ephemeral"]
 
 logger = logging.getLogger(__name__)
+MAX_CONCURRENT_KERNEL_SESSIONS = 64
 
 
 @dataclass
@@ -179,116 +183,6 @@ class LeaseHeartbeat:
         self._last_tokens.pop(session_id, None)
 
 
-@dataclass
-class AgentKernelReadiness:
-    """truthful readiness probe：每个维度都是真实查询，不是配置回显。"""
-
-    runtime: "AgentKernelRuntime"
-
-    async def check(self) -> dict[str, Any]:
-        config = self.runtime.config
-        store_ok = False
-        try:
-            # 真实 store 查询（PG driver 即真实 SQL round-trip）。
-            await self.runtime.kernel_store.list_messages(
-                config.agent_instance_id
-            )
-            store_ok = True
-        except Exception:
-            store_ok = False
-
-        lease_healthy = True
-        activation_id: str | None = None
-        for session_id in self.runtime.heartbeat_sessions():
-            try:
-                lease = await self.runtime.kernel_store.current_lease(
-                    config.agent_instance_id, session_id
-                )
-            except Exception:
-                lease = None
-            if lease is None:
-                lease_healthy = False
-                continue
-            if not self.runtime.lease_heartbeat.owns_lease(session_id, lease):
-                # lease 存在但已被其它 activation 接管：对本 runtime 而言
-                # 等价于丢失，必须如实上报 not-ready。
-                lease_healthy = False
-                continue
-            activation_id = activation_id or lease.activation_id
-            expires = getattr(lease, "lease_expires_at", "")
-            try:
-                from datetime import datetime
-
-                expires_at = datetime.fromisoformat(
-                    str(expires).replace("Z", "+00:00")
-                )
-                if expires_at <= datetime.now(expires_at.tzinfo):
-                    lease_healthy = False
-            except ValueError:
-                lease_healthy = False
-
-        worker_running = self.runtime.worker_running
-        degraded = self.runtime.degraded
-        quarantined = self.runtime.quarantined_sessions()
-        capability = self.runtime.kernel.capabilities()
-        capability_matrix = runtime_capability_matrix_wire_value(capability)
-        computed_capability_digest = runtime_capability_matrix_digest(capability)
-        # The control plane compares all three digests before declaring an
-        # AgentInstance ready.  Reporting ready with only a contract digest
-        # would conceal a missing bundle/capability projection and make the
-        # runtime's health endpoint more optimistic than Server readiness.
-        digests_match = all(
-            (
-                config.contract_digest == AGENT_KERNEL_V1_AGGREGATE_DIGEST,
-                config.capability_digest == computed_capability_digest,
-                config.bundle_digest,
-            )
-        )
-        ready = (
-            store_ok and worker_running and lease_healthy and digests_match
-            and not degraded
-        )
-        health = {
-            "ready": ready,
-            "store_ok": store_ok,
-            "worker_running": worker_running,
-            "degraded": degraded,
-            # additive：被隔离（恢复失败）的 session 数量；隔离本身不影响
-            # ready，其余 session 照常服务。
-            "quarantined_sessions": len(quarantined),
-            "lease_healthy": lease_healthy,
-            "activation_id": activation_id,
-            # Contract support is packaged with this KsADK image; never echo
-            # an unverified control-plane environment value as evidence.
-            "contract_digest": AGENT_KERNEL_V1_AGGREGATE_DIGEST,
-            # Likewise derive capabilities from the actual Adapter matrix,
-            # rather than trusting the requested deployment digest.
-            "capability_digest": computed_capability_digest,
-            # Runtime/Operator/Server readiness chain must carry the actual
-            # typed capability facts, not merely a digest supplied at deploy
-            # time. Server admission uses these to reject unsupported control
-            # operations before they enter the durable inbox.
-            "capabilities": capability_matrix,
-            "bundle_digest": config.bundle_digest,
-            "durability_tier": config.durability_tier,
-            # Identity is derived from the KsADK source Python imported, not
-            # ``importlib.metadata`` for the base image distribution.
-            "runtime_identity": runtime_identity(),
-        }
-        # 诊断字段（additive，runtime 内部端点非 wire 冻结合同）：
-        # degraded 时必须能从 health 直接回答 "为什么降级、何时降级"，
-        # 出问题的 session 明细同样可见，运维不必再对着布尔值猜。
-        if quarantined:
-            health["quarantined_session_ids"] = sorted(quarantined)
-        if degraded:
-            health["degradation_reason"] = self.runtime._degradation_reason
-            health["degraded_at"] = self.runtime._degraded_at
-            health["degradation_last_error"] = (
-                self.runtime._degraded_last_error
-            )
-        return health
-
-
 @dataclass
 class AgentKernelRuntime:
     """生产 kernel runtime：start() 启动后台 worker/lease loop，close() 全停。"""
@@ -303,10 +197,14 @@ class AgentKernelRuntime:
     session_events: Any = field(repr=False)
     _owns_pool: bool = field(default=False, repr=False)
     _pool: Any = field(default=None, repr=False)
+    _owns_store: bool = field(default=False, repr=False)
 
     def __post_init__(self) -> None:
         self._tasks: list[asyncio.Task] = []
+        self._session_tasks: dict[str, asyncio.Task[bool]] = {}
         self._worker_running = False
+        self._last_scheduler_poll = 0.0
+        self._session_capacity_exhausted = False
         self._heartbeat_sessions: set[str] = set()
         self._last_renewed: dict[str, float] = {}
         self._degraded = False
@@ -322,17 +220,13 @@ class AgentKernelRuntime:
 
     # ------------------------------------------------------------ degradation
 
-    def _mark_degraded(
-        self, reason: str, exc: BaseException | None = None
-    ) -> None:
+    def _mark_degraded(self, reason: str, exc: BaseException | None = None) -> None:
         """统一降级入口：醒目 ERROR 日志 + 可供 health 端点回读的诊断状态。"""
 
         self._degraded = True
         if self._degradation_reason is None:
             self._degradation_reason = reason
-        last_error = (
-            f"{type(exc).__name__}: {exc}" if exc is not None else "n/a"
-        )
+        last_error = f"{type(exc).__name__}: {exc}" if exc is not None else "n/a"
         self._degraded_last_error = last_error
         try:
             self._degraded_at = self.config.clock().isoformat()
@@ -352,7 +246,13 @@ class AgentKernelRuntime:
 
     @property
     def worker_running(self) -> bool:
-        return self._worker_running
+        return (
+            self._worker_running
+            and not self._degraded
+            and not self._session_capacity_exhausted
+            and time.monotonic() - self._last_scheduler_poll
+            <= max(10.0, self.config.poll_interval * 20)
+        )
 
     @property
     def degraded(self) -> bool:
@@ -370,32 +270,35 @@ class AgentKernelRuntime:
 
     @property
     def background_tasks(self) -> list[asyncio.Task]:
-        return list(self._tasks)
+        return [*self._tasks, *self._session_tasks.values()]
 
     # ------------------------------------------------------------- lifecycle
 
     async def start(self) -> None:
         if self._tasks:
             return
+        if hasattr(self.kernel_store, "ensure_schema"):
+            await self.kernel_store.ensure_schema()  # type: ignore[attr-defined]
         self._worker_running = True
+        self._last_scheduler_poll = time.monotonic()
         self._tasks.append(asyncio.create_task(self._run_loop(), name="kernel-runtime"))
         # 心跳续约必须是独立任务：run loop 可能长时间阻塞在某个 session 的
         # adapter.start()（hosted pod 上 codex 握手可超过 lease TTL），内联
         # 续约会把其它已持有 lease 的 session 拖过期（stream guard StaleFence）。
-        self._tasks.append(
-            asyncio.create_task(self._heartbeat_loop(), name="kernel-heartbeat")
-        )
+        self._tasks.append(asyncio.create_task(self._heartbeat_loop(), name="kernel-heartbeat"))
 
     async def close(self) -> None:
-        for task in self._tasks:
+        all_tasks = self.background_tasks
+        for task in all_tasks:
             if not task.done():
                 task.cancel()
-        for task in self._tasks:
+        for task in all_tasks:
             try:
                 await task
             except (asyncio.CancelledError, Exception):
                 pass
         self._tasks.clear()
+        self._session_tasks.clear()
         self._worker_running = False
         # best-effort 释放持有的 activation（不阻塞关闭）。
         for session_id in list(self._heartbeat_sessions | self._quarantined):
@@ -403,9 +306,7 @@ class AgentKernelRuntime:
                 lease = await self.kernel_store.current_lease(
                     self.config.agent_instance_id, session_id
                 )
-                if lease is not None and self.lease_heartbeat.owns_lease(
-                    session_id, lease
-                ):
+                if lease is not None and self.lease_heartbeat.owns_lease(session_id, lease):
                     await self.kernel_store.release_activation(
                         lease.activation_id, expected_fence=lease.fencing_token
                     )
@@ -419,6 +320,11 @@ class AgentKernelRuntime:
                 await self._pool.close()
             except Exception:
                 pass
+        if self._owns_store and hasattr(self.kernel_store, "close"):
+            try:
+                await self.kernel_store.close()  # type: ignore[attr-defined]
+            except Exception:
+                pass
 
     # ------------------------------------------------------------- run loop
 
@@ -429,87 +335,128 @@ class AgentKernelRuntime:
                 if self._degraded:
                     return
                 progressed = False
+                task_failed = False
                 try:
-                    sessions = await self._pending_sessions()
-                    for session_id in sorted(sessions):
-                        if session_id in self._quarantined:
-                            # 隔离中的 session：不 claim inbox、不恢复、
-                            # 不写任何 canonical 事件（等待人工清理）。
+                    for session_id, task in list(self._session_tasks.items()):
+                        if not task.done():
                             continue
-                        lease, took_over = await self.lease_heartbeat.ensure_lease(
-                            session_id
-                        )
-                        if lease is None:
-                            continue
-                        self._heartbeat_sessions.add(session_id)
-                        self._last_renewed[session_id] = time.monotonic()
-                        if took_over:
-                            # takeover：对 open run 做确定性收口（attach /
-                            # resume / interrupted），再继续消费 inbox。
-                            # P0-1：recover 抛错不得静默吞掉——先尝试
-                            # durable 兜底收口；连收口都失败则隔离该
-                            # session 并上报，其余 session 继续服务；只有
-                            # 全局性故障（store 不可达或失败扩散到阈值）
-                            # 才进程级 degraded。
-                            failure = await self._recover_safely(
-                                lease, session_id
-                            )
-                            if failure is not None:
-                                if not await self._quarantine_session(
-                                    session_id, failure
-                                ):
-                                    return
-                                continue
-                        result = await self.worker.run_once(
-                            self.config.agent_instance_id,
-                            lease,
-                            session_id=session_id,
-                        )
-                        if result.outcome in {"claimed", "completed"}:
-                            progressed = True
-                        elif result.outcome == "terminal_failure":
-                            if isinstance(result.error, StaleFenceError):
-                                # 当前 activation 已失去 fence，不能继续触碰该
-                                # session，也不应把正常 takeover 误判为坏数据。
-                                self._heartbeat_sessions.discard(session_id)
-                                self._last_renewed.pop(session_id, None)
-                                self.lease_heartbeat.forget(session_id)
-                                continue
-                            failure = result.error or RuntimeError(
-                                "agent kernel command failed without an error detail"
-                            )
-                            if not await self._quarantine_session(
+                        del self._session_tasks[session_id]
+                        try:
+                            progressed = task.result() or progressed
+                        except asyncio.CancelledError:
+                            raise
+                        except Exception as exc:
+                            task_failed = True
+                            self._store_failures += 1
+                            logger.exception(
+                                "agent kernel session poll failed: "
+                                "agent_instance_id=%s session_id=%s "
+                                "consecutive_failures=%d",
+                                self.config.agent_instance_id,
                                 session_id,
-                                failure,
-                                context="command execution",
+                                self._store_failures,
+                                exc_info=exc,
+                            )
+                            if (
+                                self._store_failures >= self.config.store_failure_degrade_threshold
+                                and not await self._store_reachable()
                             ):
+                                self._mark_degraded("store_unreachable", exc)
                                 return
-                    self._store_failures = 0
+                    sessions = await self._pending_sessions()
+                    self._last_scheduler_poll = time.monotonic()
+                    self._session_capacity_exhausted = False
+                    for session_id in sorted(sessions):
+                        if session_id in self._quarantined or session_id in self._session_tasks:
+                            continue
+                        if len(self._session_tasks) >= MAX_CONCURRENT_KERNEL_SESSIONS:
+                            self._session_capacity_exhausted = True
+                            break
+                        self._session_tasks[session_id] = asyncio.create_task(
+                            self._run_session_once(session_id),
+                            name=f"kernel-session:{session_id}",
+                        )
+                    if not task_failed:
+                        self._store_failures = 0
                 except asyncio.CancelledError:
                     raise
-                except Exception:
+                except Exception as exc:
                     self._store_failures += 1
+                    logger.exception(
+                        "agent kernel poll failed: agent_instance_id=%s "
+                        "consecutive_failures=%d",
+                        self.config.agent_instance_id,
+                        self._store_failures,
+                    )
                     if (
-                        self._store_failures
-                        >= self.config.store_failure_degrade_threshold
+                        self._store_failures >= self.config.store_failure_degrade_threshold
                         and not await self._store_reachable()
                     ):
                         # store 持续不可达是全局性故障：宁降级不静默。
-                        self._mark_degraded("store_unreachable")
+                        self._mark_degraded("store_unreachable", exc)
                         return
                     await asyncio.sleep(self.config.poll_interval * 4)
                     continue
-                if not progressed:
-                    await asyncio.sleep(self.config.poll_interval)
+                await asyncio.sleep(0 if progressed else self.config.poll_interval)
         finally:
             self._worker_running = False
 
+    async def _run_session_once(self, session_id: str) -> bool:
+        """Process one session without stalling admission for other sessions."""
+
+        lease, took_over = await self.lease_heartbeat.ensure_lease(session_id)
+        if lease is None:
+            return False
+        self._heartbeat_sessions.add(session_id)
+        self._last_renewed[session_id] = time.monotonic()
+        if took_over:
+            failure = await self._recover_safely(lease, session_id)
+            if failure is not None:
+                await self._quarantine_session(session_id, failure)
+                return False
+        active = await self.kernel_store.find_active_run(
+            self.config.agent_instance_id, session_id
+        )
+        if active is not None and self.worker.take_stream_failure(
+            active.run_id, lease
+        ) is not None:
+            try:
+                await self.recovery.settle_interrupted(
+                    self.config.agent_instance_id, lease,
+                    session_id=session_id, reason="runtime_stream_failed",
+                )
+                return True
+            except StaleFenceError:
+                self._heartbeat_sessions.discard(session_id)
+                self._last_renewed.pop(session_id, None)
+                self.lease_heartbeat.forget(session_id)
+                return False
+            except Exception as error:
+                await self._quarantine_session(
+                    session_id, error, context="background stream settlement"
+                )
+                return False
+        result = await self.worker.run_once(
+            self.config.agent_instance_id, lease, session_id=session_id
+        )
+        if result.outcome == "terminal_failure":
+            if isinstance(result.error, StaleFenceError):
+                self._heartbeat_sessions.discard(session_id)
+                self._last_renewed.pop(session_id, None)
+                self.lease_heartbeat.forget(session_id)
+            else:
+                failure = result.error or RuntimeError(
+                    "agent kernel command failed without an error detail"
+                )
+                await self._quarantine_session(
+                    session_id, failure, context="command execution"
+                )
+        return result.outcome in {"claimed", "completed"}
+
     async def _heartbeat_loop(self) -> None:
         """独立心跳任务：按 TTL/3 节奏续约所有已持有的 lease。"""
 
-        interval = max(
-            self.config.lease_ttl_seconds / 3.0, self.config.poll_interval
-        )
+        interval = max(self.config.lease_ttl_seconds / 3.0, self.config.poll_interval)
         while True:
             await asyncio.sleep(interval / 2.0)
             await self._renew_leased_sessions()
@@ -526,9 +473,7 @@ class AgentKernelRuntime:
         activation lease 仍由本 runtime 持有，就以 TTL/3 的节奏幂等续约。
         """
 
-        interval = max(
-            self.config.lease_ttl_seconds / 3.0, self.config.poll_interval
-        )
+        interval = max(self.config.lease_ttl_seconds / 3.0, self.config.poll_interval)
         now = time.monotonic()
         for session_id in sorted(self._heartbeat_sessions):
             if session_id in self._quarantined:
@@ -537,9 +482,7 @@ class AgentKernelRuntime:
                 continue
             self._last_renewed[session_id] = now
             try:
-                lease, took_over = await self.lease_heartbeat.ensure_lease(
-                    session_id
-                )
+                lease, took_over = await self.lease_heartbeat.ensure_lease(session_id)
             except asyncio.CancelledError:
                 raise
             except Exception:
@@ -555,14 +498,10 @@ class AgentKernelRuntime:
             if failure is not None:
                 if not await self._quarantine_session(session_id, failure):
                     if not self._degraded:
-                        self._mark_degraded(
-                            "renew_recovery_failure", failure
-                        )
+                        self._mark_degraded("renew_recovery_failure", failure)
                     return
 
-    async def _recover_safely(
-        self, lease, session_id: str | None = None
-    ) -> Exception | None:
+    async def _recover_safely(self, lease, session_id: str | None = None) -> Exception | None:
         """takeover 后的安全恢复：失败必须持久化收口，否则返回失败原因。
 
         返回 None 表示恢复路径已收口（含 durable interrupted 兜底），
@@ -571,7 +510,11 @@ class AgentKernelRuntime:
         """
 
         try:
-            await self.recovery.recover(self.config.agent_instance_id, lease)
+            report = await self.recovery.recover(
+                self.config.agent_instance_id, lease, session_id=session_id
+            )
+            if getattr(report, "outcome", None) == "failed":
+                raise RuntimeError(f"runtime recovery failed: {report.reason}")
             return None
         except Exception as exc:
             first_failure = exc
@@ -589,7 +532,7 @@ class AgentKernelRuntime:
             )
         try:
             await self.recovery.settle_interrupted(
-                self.config.agent_instance_id, lease
+                self.config.agent_instance_id, lease, session_id=session_id
             )
             # 主恢复失败但 durable interrupted 兜底收口成功：半恢复状态，
             # 运维需要可见（事件流里会出现确定性的 interrupted 收口）。
@@ -644,9 +587,7 @@ class AgentKernelRuntime:
 
         if not await self._store_reachable():
             # store 本身不可达：这不是单个 session 的问题。
-            self._mark_degraded(
-                "store_unreachable_during_recovery", exc
-            )
+            self._mark_degraded("store_unreachable_during_recovery", exc)
             return False
         self._quarantined.add(session_id)
         self._recovery_failed_sessions.add(session_id)
@@ -662,28 +603,34 @@ class AgentKernelRuntime:
             type(exc).__name__,
             exc,
         )
-        if (
-            len(self._recovery_failed_sessions)
-            >= self.config.quarantine_degrade_threshold
-        ):
+        if len(self._recovery_failed_sessions) >= self.config.quarantine_degrade_threshold:
             self._mark_degraded(
-                "recovery_failures_spread_to_%d_sessions" % len(
-                    self._recovery_failed_sessions
-                ),
+                "recovery_failures_spread_to_%d_sessions" % len(self._recovery_failed_sessions),
                 exc,
             )
             return False
         return True
 
     async def _pending_sessions(self) -> set[str]:
-        messages = await self.kernel_store.list_messages(
-            self.config.agent_instance_id
-        )
+        messages = await self.kernel_store.list_messages(self.config.agent_instance_id)
         inbox_sessions = {
             message.session_id
             for message in messages
             if message.status.value in ("accepted", "claimed")
         }
+        # A process may die after the Inbox claim is completed but before the
+        # Runtime run reaches a terminal state. On restart there is then no
+        # pending Inbox row to discover the session from; scan sessions seen in
+        # the durable Inbox and retain those with an open Run for takeover.
+        known_sessions = {message.session_id for message in messages}
+        open_run_sessions = {
+            session_id
+            for session_id in known_sessions
+            if await self.kernel_store.find_active_run(
+                self.config.agent_instance_id, session_id
+            )
+            is not None
+        }
         # Inbox is completed as soon as a stream is launched.  Keep renewing
         # the owning lease after the independent live execution finishes too:
         # this runtime remains the session's activation owner while the Pod is
@@ -692,7 +639,7 @@ class AgentKernelRuntime:
         # releases the retained leases; an ungraceful stop lets their TTL
         # expire for recovery by a new activation.
         active_sessions = self.worker.active_session_ids()
-        return inbox_sessions | active_sessions
+        return inbox_sessions | open_run_sessions | active_sessions
 
 
 # ---------------------------------------------------------------------------
@@ -776,6 +723,7 @@ def build_agent_kernel_runtime(
     session_events = config.session_events
     session_service = config.session_service
     owns_pool = config.owns_pool
+    owns_store = False
     pool = config.pool
 
     if store is None or session_events is None:
@@ -788,9 +736,7 @@ def build_agent_kernel_runtime(
             from ksadk.sessions.postgres_service import PostgresSessionService
 
             if not config.dsn:
-                raise RuntimeError(
-                    "postgres agent kernel runtime requires a store DSN"
-                )
+                raise RuntimeError("postgres agent kernel runtime requires a store DSN")
             if session_service is None:
                 session_service = PostgresSessionService(
                     dsn=config.dsn,
@@ -806,11 +752,23 @@ def build_agent_kernel_runtime(
                 workspace_id=session_service.workspace_id,
             )
             kernel_store: AgentKernelStore = PostgresAgentKernelStore(
-                pool, event_log
+                pool, event_log, tenant_id=session_service.tenant_id
             )
             # typed RuntimeEvent 写路径走 fenced store：每个
             # ActivationWriteGuard append 在同一事务验证 activation 行。
             events = PostgresFencedSessionEventStore(kernel_store)  # type: ignore[arg-type]
+        elif config.driver == "sqlite":
+            from ksadk.kernel.sqlite_store import SQLiteAgentKernelStore
+            from ksadk.sessions.in_memory import InMemorySessionService
+
+            if not config.dsn:
+                raise RuntimeError("sqlite agent kernel runtime requires a database path")
+            if session_service is None:
+                session_service = InMemorySessionService()
+            base_events = SessionServiceEventStore(session_service)
+            kernel_store = SQLiteAgentKernelStore(config.dsn, base_events)
+            events = base_events
+            owns_store = True
         else:
             from ksadk.kernel.memory_store import InMemoryAgentKernelStore
             from ksadk.sessions.in_memory import InMemorySessionService
@@ -845,13 +803,14 @@ def build_agent_kernel_runtime(
             raise RuntimeError(
                 "hosted agent kernel runtime cannot determine adapter capabilities"
             ) from exc
-        computed_capability_digest = runtime_capability_matrix_digest(
-            capability_snapshot
+        computed_capability_digest = runtime_capability_admission_digest(
+            capability_snapshot, config.capability_digest
         )
         if config.capability_digest != computed_capability_digest:
             raise RuntimeError(
                 "capability_digest_mismatch: hosted adapter capabilities do not "
-                "match the control-plane deployment digest"
+                "match the control-plane deployment digest "
+                f"(expected={config.capability_digest}, actual={computed_capability_digest})"
             )
 
         def capabilities() -> RuntimeCapabilityMatrix:  # type: ignore[misc]
@@ -878,6 +837,7 @@ def build_agent_kernel_runtime(
         store,
         adapter_factory=adapter_provider,
         session_events=session_events,
+        session_service=session_service,
         start_request_defaults=config.start_request_defaults,
     )
     recovery = RecoveryCoordinator(
@@ -887,20 +847,23 @@ def build_agent_kernel_runtime(
         executor=config.runtime_executor,
         launch_context=config.launch_context,
         adapter_factory=adapter_provider,
+        session_service=session_service,
         # takeover 重建的 live execution 交还 worker（ActiveExecution 归
         # 当前 activation 持有，Interaction 回包才能打到同一 client 实例）。
         execution_sink=worker.adopt_execution,
+        recovery_stream_sink=worker.recover_stream,
     )
     heartbeat = LeaseHeartbeat(
         store,
         agent_instance_id=config.agent_instance_id,
-        activation_id=config.activation_id
-        or f"{config.agent_instance_id}:kernel-runtime",
+        activation_id=config.activation_id or f"{config.agent_instance_id}:kernel-runtime",
         runtime_type=config.runtime_type,
         bundle_digest=config.bundle_digest,
-        # Lease metadata must represent the exact matrix this owner executes,
-        # not an unverified environment projection.
-        capability_digest=runtime_capability_matrix_digest(capabilities()),
+        # The lease carries the verified admission policy; command admission
+        # continues to read the adapter's complete capability matrix.
+        capability_digest=runtime_capability_admission_digest(
+            capabilities(), config.capability_digest
+        ),
         lease_ttl_seconds=config.lease_ttl_seconds,
     )
     runtime = AgentKernelRuntime(
@@ -914,6 +877,7 @@ def build_agent_kernel_runtime(
         session_events=session_events,
         _owns_pool=owns_pool,
         _pool=pool,
+        _owns_store=owns_store,
     )
     runtime.readiness.runtime = runtime
     return runtime
@@ -930,6 +894,7 @@ async def bootstrap_agent_kernel_runtime_from_env(
     launch_context: Any | None = None,
     start_request_defaults: dict[str, Any] | None = None,
     session_service: Any | None = None,
+    before_start: Any | None = None,
 ) -> AgentKernelRuntime | None:
     """Operator env 投影 -> 生产 runtime（AGENT_KERNEL_ENABLED=1 时）。
 
@@ -958,13 +923,9 @@ async def bootstrap_agent_kernel_runtime_from_env(
     driver = os.environ.get("AGENT_KERNEL_STORE_DRIVER", "memory").strip().lower()
     dsn = os.environ.get("AGENT_KERNEL_STORE_DSN", "").strip()
     jwks_url = os.environ.get(ENV_JWKS_URL, "").strip()
-    session_namespace = (
-        os.environ.get("KSADK_SESSION_NAMESPACE", "default").strip() or "default"
-    )
+    session_namespace = os.environ.get("KSADK_SESSION_NAMESPACE", "default").strip() or "default"
     tenant_id = (
-        os.environ.get("KSADK_TENANT_ID")
-        or os.environ.get("AGENTENGINE_TENANT_ID")
-        or "default"
+        os.environ.get("KSADK_TENANT_ID") or os.environ.get("AGENTENGINE_TENANT_ID") or "default"
     ).strip()
     workspace_id = (
         os.environ.get("KSADK_WORKSPACE_ID")
@@ -972,21 +933,25 @@ async def bootstrap_agent_kernel_runtime_from_env(
         or "default"
     ).strip()
     mode: AuthorityMode = authority_mode()  # type: ignore[assignment]
-    durability_tier: DurabilityTier = os.environ.get(
-        "AGENT_KERNEL_DURABILITY_TIER", "durable"
-    ).strip().lower()  # type: ignore[assignment]
-    injected_contract_digest = os.environ.get(
-        "AGENT_KERNEL_CONTRACT_DIGEST", ""
-    ).strip()
-    if (
-        mode == "hosted"
-        and injected_contract_digest != AGENT_KERNEL_V1_AGGREGATE_DIGEST
-    ):
+    durability_tier: DurabilityTier = (
+        os.environ.get("AGENT_KERNEL_DURABILITY_TIER", "durable").strip().lower()
+    )  # type: ignore[assignment]
+    injected_contract_digest = os.environ.get("AGENT_KERNEL_CONTRACT_DIGEST", "").strip()
+    if mode == "hosted" and injected_contract_digest != AGENT_KERNEL_V1_AGGREGATE_DIGEST:
         raise RuntimeError(
             "contract_digest_mismatch: hosted agent kernel runtime image "
             "does not support the control-plane contract digest"
         )
 
+    # Lazy framework adapters learn their native checkpoint capabilities during
+    # preflight. Snapshotting before it permanently disables cold recovery even
+    # when the deployment has configured durable native sessions.
+    capabilities = None
+    if adapter_provider is not None:
+        capability_adapter = adapter_provider()
+        await capability_adapter.preflight()
+        capabilities = capability_adapter.capabilities
+
     pool = None
     owns_pool = False
     if driver == "postgres":
@@ -1015,7 +980,7 @@ async def bootstrap_agent_kernel_runtime_from_env(
             workspace_id=session_service.workspace_id,
         )
         store: AgentKernelStore = PostgresAgentKernelStore(
-            pool, event_log, owns_pool=True
+            pool, event_log, tenant_id=session_service.tenant_id, owns_pool=True
         )
         await store.ensure_schema()
         session_events: Any = PostgresFencedSessionEventStore(store)
@@ -1052,11 +1017,10 @@ async def bootstrap_agent_kernel_runtime_from_env(
         permit_issuer=os.environ.get("AGENT_CONTROL_PERMIT_ISSUER", ""),
         nonce_store=nonce_store,
         adapter_provider=adapter_provider,
+        capabilities=capabilities,
         start_request_defaults=dict(start_request_defaults or {}),
         contract_digest=(
-            AGENT_KERNEL_V1_AGGREGATE_DIGEST
-            if mode == "hosted"
-            else injected_contract_digest
+            AGENT_KERNEL_V1_AGGREGATE_DIGEST if mode == "hosted" else injected_contract_digest
         ),
         capability_digest=os.environ.get("AGENT_KERNEL_CAPABILITY_DIGEST", ""),
         bundle_digest=os.environ.get("AGENT_BUNDLE_DIGEST", ""),
@@ -1074,12 +1038,16 @@ async def bootstrap_agent_kernel_runtime_from_env(
         # 组合才是 activation owner；hosted 少了它必须拒绝启动，不能退回到
         # 所有副本共享的固定字符串。
         activation_id=f"{agent_instance_id}:{pod_uid}" if pod_uid else None,
-        lease_ttl_seconds=float(
-            os.environ.get("AGENT_KERNEL_LEASE_TTL_SECONDS", "60") or "60"
-        ),
+        lease_ttl_seconds=float(os.environ.get("AGENT_KERNEL_LEASE_TTL_SECONDS", "60") or "60"),
     )
     runtime = build_agent_kernel_runtime(config)
-    await runtime.start()
+    try:
+        if before_start is not None:
+            await before_start(runtime)
+        await runtime.start()
+    except BaseException:
+        await runtime.close()
+        raise
     set_agent_kernel(runtime.kernel)
     set_agent_kernel_runtime(runtime)
     return runtime