@steerable/runtime-darwin-arm64 0.0.0-stage → 0.9.1

package/python-runtime/python/lib/python3.12/site-packages/steerable_sidecar/sidecar.py

@@ -0,0 +1,3785 @@
+"""Sidecar core: wires the runtime adapters into a JSON-RPC server.
+
+Methods (see spec/sidecar/README.md for the full catalog):
+
+  system.ping              -> SidecarHealth
+  system.shutdown          -> null
+  system.shutdown_now      -> null
+  agent.session.create     -> AgentSession
+  agent.session.resume     -> AgentSession
+  agent.session.list       -> AgentSession[]
+  agent.session.fork       -> BranchPoint  (fork a record, no turn run)
+  agent.session.branches   -> { lineage, children } (branch-family view)
+  agent.session.tree       -> { recordId, tree, nodeCount, truncated }
+                                 (full branch family from the root)
+  agent.chat.stream        -> { streamId } (chunks pushed via `stream.chunk`,
+                                            terminator via `stream.done`)
+  agent.chat.cancel        -> null         (best-effort cancel of an in-flight stream)
+  tool.list                -> ToolDescriptor[]
+  tool.invoke              -> ToolResult
+  workspace.apply_edits    -> { content, diff, applied, matches }  (pure edit
+                                algorithm on supplied content; the host owns
+                                all file I/O — W6-1 single source of truth)
+  skills.list              -> { skills }  (parse + select SKILL.md from host
+                                roots; single parse source so the desktop no
+                                longer re-parses — eager/catalog both returned)
+  trace.fetch              -> { trace, spans, events }
+  trace.export             -> { status, traceId, privacyMode }  (OTLP/HTTP push, W6-6)
+  config.get / config.set
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import json
+import logging
+import math
+import os
+import platform
+import sys
+import threading
+import time
+import uuid
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from functools import lru_cache
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from steerable_agent_runtime.llm import ProviderPreset
+
+from steerable_agent_harness import DEFAULT_CACHED_TOKEN_WEIGHT, BudgetLimit
+from steerable_agent_protocol.generated import (
+    AgentSession,
+    SidecarHealth,
+    ToolCall,
+)
+from steerable_agent_runtime import (
+    DEFAULT_SHELL_TOOLS,
+    AntiHallucinationConfig,
+    AntiHallucinationHooks,
+    ApprovalExecutor,
+    AutoApprover,
+    BudgetExhaustedError,
+    ChainHooks,
+    CoreLoop,
+    FamilyTreeNode,
+    FilesystemSkillProvider,
+    HistorySeed,
+    JsonApprovalStore,
+    LoopConfig,
+    LoopHooks,
+    McpClient,
+    McpError,
+    OrchestrationConfig,
+    OrchestrationExecutor,
+    PluginLoadError,
+    PluginStateError,
+    PolicyDeniedError,
+    RequiredDelegationGate,
+    RouterToolExecutor,
+    SandboxedToolExecutor,
+    SessionApprovalCache,
+    SkillDefinition,
+    SkillExecutor,
+    SkillHooks,
+    StaticWorldStateSection,
+    StorageError,
+    SubagentConfig,
+    SubagentExecutor,
+    SubagentRegistry,
+    ToolDispatchError,
+    ToolRouter,
+    TodoCompletionGate,
+    create_mcp_client,
+    TodoPlanningNudge,
+    TraceRecorder,
+    WorldStateHooks,
+    branch_label,
+    close_dangling_tool_calls,
+    entry_from_dict,
+    estimate_cost_usd,
+    export_metrics,
+    export_trace,
+    resolve_compaction_policy,
+    is_large_window,
+    family_tree,
+    fork_record,
+    lineage,
+    load_history_transcript,
+    orchestration_tool_descriptors,
+    resolve_fork_seq,
+    select_catalog,
+    select_pinned_loadable,
+    select_skills,
+    skill_to_dict,
+    skill_tool_descriptor,
+    subagent_tool_descriptor,
+    mcp_invoker,
+    register_mcp_catalog,
+)
+from steerable_agent_runtime.llm import (
+    ContentPart,
+    ImagePart,
+    LLMMessage,
+    LLMProvider,
+    TextPart,
+)
+from steerable_agent_runtime.resume import project_transcript
+from steerable_agent_runtime.storage import InMemoryStorage, StorageAdapter
+from steerable_agent_runtime.transport.stdio_jsonrpc import (
+    JsonRpcError,
+    JsonRpcServer,
+    StdioJsonRpcTransport,
+    encode_frame,
+)
+
+from ._version import __version__ as SIDECAR_VERSION
+from .file_edit import EditError, EditOp, apply_edits
+from .host_tools import HostApprover, HostAskUserHandler, HostToolExecutor
+from .loop_limits import UNLIMITED_LOOP_LIMIT, resolve_loop_limits
+from .sandbox import select_exec_backend
+from .stream_chunks import RawChunkBridgeHooks
+
+logger = logging.getLogger("steerable_sidecar")
+
+_AUTO_APPROVED_HOST_CONTROL_TOOLS = (
+    "get_goal",
+    "create_goal",
+    "update_goal",
+    "loop_create",
+    "loop_list",
+    "loop_stop",
+)
+
+PROTOCOL_VERSION = "0.1.0"
+
+# asyncio's default 64 KiB StreamReader limit kills the read loop with
+# LimitOverrunError the moment a single JSON-RPC frame exceeds it — a large
+# reverse-channel tool result (e.g. a file read) or a long conversation's
+# chat.stream request crosses it easily, and the turn then dies silently
+# (host sees a hang, no trace). 16 MiB stays bounded while covering
+# realistic frames.
+STDIO_STREAM_LIMIT = 16 * 1024 * 1024
+READY_PREFIX = "__SIDECAR_READY__:"
+
+#: Bound on per-chat session approval caches held by one sidecar. Eviction
+#: only re-asks a cached *_for_session decision once; decisions are cheap.
+_APPROVAL_SESSION_CACHE_CAP = 64
+
+#: Grace window between a cooperative cancel (loop.cancel()) and the
+#: hard-cancel backstop. The loop normally winds down within one await
+#: point; 5s covers a slow final history flush without masking a wedge.
+_CANCEL_GRACE_S = 5.0
+
+
+class _TurnExecControl:
+    """Live command-sandbox switch for one running turn.
+
+    The composer can change workspace / full access after the stream has
+    started. Steer applies that choice here so the next shell call follows
+    it. The sandbox wrapper and the workspace auto-approver are optional:
+    a turn that never installed a wrapper cannot grow one mid-flight.
+    """
+
+    def __init__(self) -> None:
+        self.sandbox: Any = None
+        self.approver: Any = None
+
+    def apply(self, policy: str) -> None:
+        active = policy != "full"
+        sandbox = self.sandbox
+        if sandbox is not None:
+            sandbox.set_active(active)
+        approver = self.approver
+        if approver is not None:
+            approver.set_sandbox_enforced(active)
+
+
+@dataclass
+class SidecarConfig:
+    """Sidecar runtime configuration."""
+
+    log_level: str = "INFO"
+    quiet_stderr: bool = False
+    grace_period_seconds: float = 5.0
+    install_signal_handlers: bool = True
+    initial_tools: list[Any] = field(default_factory=list)
+    #: W2.6.1: when set, sessions/traces/history persist to a zero-dependency
+    #: SqliteStorage database at this path instead of vanishing with the
+    #: process (the InMemoryStorage default).
+    storage_path: str | None = None
+
+
+class Sidecar:
+    """In-process sidecar harness.
+
+    The main entrypoint composes a `JsonRpcServer`, a default `ToolRouter`, an
+    `InMemoryStorage`, and a `StdioJsonRpcTransport`. Embedders can swap any of
+    these by setting the corresponding attribute before calling ``serve()``.
+    """
+
+    def __init__(
+        self,
+        *,
+        config: SidecarConfig | None = None,
+        storage: StorageAdapter | None = None,
+        tools: ToolRouter | None = None,
+        llm_provider_factory: Any | None = None,
+        loop_hooks_factory: Any | None = None,
+    ) -> None:
+        self.config = config or SidecarConfig()
+        if storage is not None:
+            self.storage: StorageAdapter = storage
+        elif self.config.storage_path:
+            from steerable_agent_runtime.storage import SqliteStorage
+
+            self.storage = SqliteStorage(self.config.storage_path)
+        else:
+            self.storage = InMemoryStorage()
+        self.tools: ToolRouter = tools or ToolRouter()
+        self.server = JsonRpcServer()
+        self._llm_provider_factory = (
+            llm_provider_factory or default_llm_provider_factory
+        )
+        # Optional embedder hook for the CoreLoop chat path — receives the
+        # request params, returns a LoopHooks (e.g. ChainHooks of retry +
+        # compaction + spill). Defaults to RetryHooks alone.
+        self._loop_hooks_factory = loop_hooks_factory
+        self._streams: dict[str, asyncio.Task[Any]] = {}
+        #: Active CoreLoop instances by stream id — the steer RPC targets
+        #: these to inject user messages into a running turn.
+        self._coreloops: dict[str, CoreLoop] = {}
+        #: Per-stream command sandbox, toggled by agent.chat.steer execPolicy.
+        self._exec_controls: dict[str, _TurnExecControl] = {}
+        #: Hard-cancel watchdogs armed by agent.chat.cancel on CoreLoop
+        #: streams; tracked so the tasks are not garbage-collected early.
+        self._cancel_watchdogs: set[asyncio.Task[None]] = set()
+        #: Session-scope approval caches per chat (Wave 3 approval algebra).
+        #: LRU-bounded so a long-lived sidecar hosting many chats doesn't
+        #: grow without limit; eviction only means a cached *_for_session
+        #: decision is re-asked once.
+        self._approval_sessions: OrderedDict[str, SessionApprovalCache] = OrderedDict()
+        self._transport: StdioJsonRpcTransport | None = None
+        self._started_ms = int(time.monotonic() * 1000)
+        self._wall_started_ms = int(time.time() * 1000)
+        self._shutdown_requested = asyncio.Event()
+        self._serving = False
+        #: Injected by the entrypoint after plugin loading so the plugin.*
+        #: RPCs can drive the lifecycle. None means the plugin subsystem is
+        #: not wired (unit tests constructing a bare Sidecar).
+        self.plugin_registry: Any = None
+
+        self._register_default_methods()
+        for tool in self.config.initial_tools:
+            self.tools.register(tool)
+
+    def _approval_session(self, chat_id: Any) -> SessionApprovalCache:
+        """Session-scope approval cache for one chat (LRU-bounded)."""
+        key = str(chat_id) if chat_id else ""
+        cache = self._approval_sessions.get(key)
+        if cache is None:
+            cache = SessionApprovalCache()
+            self._approval_sessions[key] = cache
+            while len(self._approval_sessions) > _APPROVAL_SESSION_CACHE_CAP:
+                self._approval_sessions.popitem(last=False)
+        else:
+            self._approval_sessions.move_to_end(key)
+        return cache
+
+    # ------------------------------------------------------------------
+    # Method registration
+    # ------------------------------------------------------------------
+
+    def _register_default_methods(self) -> None:
+        register = self.server.register
+        register("system.ping", self._handle_ping)
+        register("system.shutdown", self._handle_shutdown)
+        register("system.shutdown_now", self._handle_shutdown_now)
+        register("agent.session.create", self._handle_session_create)
+        register("agent.session.resume", self._handle_session_resume)
+        register("agent.session.list", self._handle_session_list)
+        register("tool.list", self._handle_tool_list)
+        register("tool.invoke", self._handle_tool_invoke)
+        register("workspace.apply_edits", self._handle_workspace_apply_edits)
+        register("skills.list", self._handle_skills_list)
+        register("trace.fetch", self._handle_trace_fetch)
+        register("trace.export", self._handle_trace_export)
+        register("metrics.export", self._handle_metrics_export)
+        register("config.get", self._handle_config_get)
+        register("config.set", self._handle_config_set)
+        register("compat.describe", self._handle_compat_describe)
+        register("sandbox.describe", self._handle_sandbox_describe)
+        register("plugin.list", self._handle_plugin_list)
+        register("plugin.enable", self._handle_plugin_enable)
+        register("plugin.disable", self._handle_plugin_disable)
+        register("plugin.reload", self._handle_plugin_reload)
+        register("plugin.tools.describe", self._handle_plugin_tools_describe)
+        register("presets.describe", self._handle_presets_describe)
+        register("presets.resolve", self._handle_presets_resolve)
+        register("catalog.describe", self._handle_catalog_describe)
+        register("models.list", self._handle_models_list)
+        register("harness.describe", self._handle_harness_describe)
+        register("agent.chat.stream", self._handle_chat_stream)
+        register("agent.chat.cancel", self._handle_chat_cancel)
+        register("agent.chat.steer", self._handle_chat_steer)
+        register("agent.chat.compact", self._handle_chat_compact)
+        register("agent.chat.fork", self._handle_chat_fork)
+        register("agent.session.fork", self._handle_session_fork)
+        register("agent.session.branches", self._handle_session_branches)
+        register("agent.session.tree", self._handle_session_tree)
+        register("agent.session.messages", self._handle_session_messages)
+
+    # ------------------------------------------------------------------
+    # Entrypoint
+    # ------------------------------------------------------------------
+
+    async def serve(self) -> None:
+        """Run the sidecar until shutdown is requested."""
+
+        self._configure_logging()
+        if self.config.install_signal_handlers:
+            self._install_signal_handlers()
+
+        ready = await self.snapshot_health()
+        self._emit_ready_marker(ready)
+
+        reader, writer = await self._connect_stdio()
+        transport = StdioJsonRpcTransport(writer)
+        self._transport = transport
+        self.server.attach_writer(writer)
+        await transport.emit_notification(
+            "lifecycle.ready",
+            {
+                "version": SIDECAR_VERSION,
+                "protocolVersion": PROTOCOL_VERSION,
+                "pid": os.getpid(),
+                "listenInfo": {"transport": "stdio"},
+            },
+        )
+
+        self._serving = True
+        in_flight: set[asyncio.Task[None]] = set()
+        try:
+            while not self._shutdown_requested.is_set():
+                line_task = asyncio.ensure_future(reader.readline())
+                shutdown_task = asyncio.ensure_future(self._shutdown_requested.wait())
+                done, pending = await asyncio.wait(
+                    {line_task, shutdown_task},
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+                for task in pending:
+                    task.cancel()
+                if shutdown_task in done:
+                    break
+                line = line_task.result()
+                if not line:
+                    break
+                # Dispatch each frame on its own task so the read loop keeps
+                # serving while a handler awaits a reverse (sidecar -> host)
+                # call — otherwise the two peers deadlock.
+                task = asyncio.ensure_future(self._process_line(line, writer))
+                in_flight.add(task)
+                task.add_done_callback(in_flight.discard)
+        finally:
+            if in_flight:
+                await asyncio.gather(*in_flight, return_exceptions=True)
+            await transport.emit_notification(
+                "lifecycle.shutdown",
+                {"reason": "normal" if self._shutdown_requested.is_set() else "eof"},
+            )
+            await transport.aclose()
+            close = getattr(writer, "close", None)
+            if close is not None:
+                close()
+            self._serving = False
+            close_storage = getattr(self.storage, "close", None)
+            if close_storage is not None:
+                close_storage()
+
+    async def _process_line(self, line: bytes, writer: Any) -> None:
+        response = await self.server.handle_frame(line.decode("utf-8"))
+        if response is None:
+            return
+        writer.write(encode_frame(response))
+        await self._maybe_drain(writer)
+
+    async def request_shutdown(self) -> None:
+        self._shutdown_requested.set()
+
+    async def snapshot_health(self) -> SidecarHealth:
+        uptime = int(time.monotonic() * 1000) - self._started_ms
+        return SidecarHealth(
+            status="ok" if self._serving or self._started_ms else "starting",
+            version=SIDECAR_VERSION,
+            protocolVersion=PROTOCOL_VERSION,
+            uptimeMs=max(0, uptime),
+            pid=os.getpid(),
+            pythonVersion=platform.python_version(),
+            platform=f"{sys.platform}-{platform.machine()}",
+            loadedTools=len(self.tools.list_tools()),
+            activeTraces=0,
+        )
+
+    # ------------------------------------------------------------------
+    # Method handlers
+    # ------------------------------------------------------------------
+
+    async def _handle_ping(self, _params: dict[str, Any] | None) -> dict[str, Any]:
+        health = await self.snapshot_health()
+        return health.model_dump(exclude_none=True)
+
+    async def _handle_shutdown(self, _params: dict[str, Any] | None) -> None:
+        _flush_shared_calibration()
+        # Schedule the actual stop so the response can be drained first.
+        loop = asyncio.get_running_loop()
+        loop.call_later(0.1, lambda: self._shutdown_requested.set())
+
+    async def _handle_shutdown_now(self, _params: dict[str, Any] | None) -> None:
+        _flush_shared_calibration()
+        self._shutdown_requested.set()
+
+    async def _handle_session_create(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        params = _require_params(params)
+        session = AgentSession(
+            sessionId=params.get("sessionId") or _new_session_id(),
+            userId=params.get("userId") or "local",
+            chatId=params["chatId"],
+            currentStage=params.get("currentStage", "plan"),
+            isActive=True,
+            createdAt=_iso_now(),
+            updatedAt=_iso_now(),
+            scenario=params.get("scenario", "agent-entry"),
+            stageData=params.get("stageData"),
+            projectId=params.get("projectId"),
+        )
+        try:
+            stored = await self.storage.upsert_session(session)
+        except StorageError as exc:
+            raise JsonRpcError(str(exc), code=-32011, kind="internal") from exc
+        return stored.model_dump(exclude_none=True)
+
+    async def _handle_session_resume(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        params = _require_params(params)
+        session_id = params.get("sessionId")
+        if not session_id:
+            raise JsonRpcError("sessionId required", code=-32602, kind="invalid_params")
+        session = await self.storage.get_session(session_id)
+        if session is None:
+            raise JsonRpcError(
+                f"session not found: {session_id}", code=-32004, kind="invalid_request"
+            )
+        return session.model_dump(exclude_none=True)
+
+    async def _seed_host_read_state(self, record_id: str) -> None:
+        """Push the record's read-before-write evidence to the host.
+
+        Best-effort: a failed scan or push leaves the host's readFileState
+        empty, which only means fewer automatic CAS checks (or, with the
+        hard gate armed, a required re-read) — never a wrong write.
+        """
+        from steerable_agent_runtime.history import (
+            HistoryItem,
+            HistorySeed,
+            entry_from_dict,
+        )
+
+        from .workspace_tools import read_file_state_from_messages
+
+        try:
+            raw_entries = await self.storage.list_history(record_id)
+        except Exception as exc:  # noqa: BLE001 — seeding is best-effort
+            logger.warning("read_state seed scan failed for %s: %s", record_id, exc)
+            return
+        messages: list[LLMMessage] = []
+        for raw in raw_entries:
+            try:
+                entry = entry_from_dict(raw)
+            except Exception as exc:  # noqa: BLE001 — skip entries this build cannot read
+                logger.debug("skipping unreadable history entry: %s", exc)
+                continue
+            if isinstance(entry, HistoryItem):
+                messages.append(entry.message)
+            elif isinstance(entry, HistorySeed):
+                messages.extend(entry.messages)
+        state = read_file_state_from_messages(messages)
+        if not state:
+            return
+        try:
+            await self.server.call("read_state.seed", {"state": state}, timeout=10)
+        except Exception as exc:  # noqa: BLE001 — best-effort; see docstring
+            logger.warning("read_state.seed push failed for %s: %s", record_id, exc)
+
+    async def _handle_session_list(
+        self, params: dict[str, Any] | None
+    ) -> list[dict[str, Any]]:
+        params = params or {}
+        sessions = await self.storage.list_sessions(
+            user_id=params.get("userId"),
+            chat_id=params.get("chatId"),
+            active_only=bool(params.get("activeOnly", False)),
+        )
+        return [s.model_dump(exclude_none=True) for s in sessions]
+
+    async def _handle_tool_list(
+        self, _params: dict[str, Any] | None
+    ) -> list[dict[str, Any]]:
+        return self.tools.describe()
+
+    async def _handle_tool_invoke(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        params = _require_params(params)
+        try:
+            call = ToolCall(
+                id=params.get("id") or _new_call_id(),
+                name=params["name"],
+                arguments=params.get("arguments") or {},
+            )
+        except KeyError as exc:
+            raise JsonRpcError(
+                f"missing argument: {exc.args[0]}", code=-32602, kind="invalid_params"
+            ) from exc
+        try:
+            result = await self.tools.dispatch(
+                call,
+                consent_granted=bool(params.get("consentGranted", False)),
+                context=params.get("context"),
+            )
+        except PolicyDeniedError as exc:
+            raise JsonRpcError(
+                exc.message, code=-32020, kind="policy_denied", data=exc.data
+            ) from exc
+        except BudgetExhaustedError as exc:
+            raise JsonRpcError(
+                exc.message, code=-32021, kind="budget_exhausted", data=exc.data
+            ) from exc
+        except ToolDispatchError as exc:
+            raise JsonRpcError(
+                exc.message, code=-32030, kind="tool_failed", data=exc.data
+            ) from exc
+        return result.model_dump(exclude_none=True)
+
+    async def _handle_workspace_apply_edits(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Pure structured-edit algorithm on caller-supplied content.
+
+        The host (desktop) owns file read / version check / atomic write; this
+        is only the locate-and-replace surgery so the algorithm has a single
+        Python source of truth shared with the headless / ACP workspace tools.
+        """
+        params = _require_params(params)
+        content = params.get("content")
+        if not isinstance(content, str):
+            raise JsonRpcError(
+                "workspace.apply_edits: `content` (string) is required",
+                code=-32602,
+                kind="invalid_params",
+            )
+        raw_edits = params.get("edits")
+        if not isinstance(raw_edits, list):
+            raise JsonRpcError(
+                "workspace.apply_edits: `edits` (array) is required",
+                code=-32602,
+                kind="invalid_params",
+            )
+        ops = [
+            EditOp(
+                old_text=str(e.get("oldText", "")), new_text=str(e.get("newText", ""))
+            )
+            for e in raw_edits
+            if isinstance(e, dict)
+        ]
+        file_path = str(params.get("filePath") or "file")
+        try:
+            result = apply_edits(content, ops, file_path=file_path)
+        except EditError as exc:
+            raise JsonRpcError(
+                str(exc), code=-32030, kind="edit_failed", data={"code": exc.code}
+            ) from exc
+        return {
+            "content": result.content,
+            "diff": result.diff,
+            "applied": len(result.matches),
+            "matches": [
+                {
+                    "level": m.level,
+                    "startLine": m.start_line,
+                    "oldLineCount": m.old_line_count,
+                }
+                for m in result.matches
+            ],
+        }
+
+    async def _handle_skills_list(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Parse + select skills from host-supplied roots (single source of
+        truth for SKILL.md parsing, so the desktop no longer re-parses).
+
+        Roots are host-local paths — the sidecar shares the filesystem with
+        the desktop host. Returns both layers (eager + catalog) with bodies;
+        the host applies its own layer filter / budget / name lookup."""
+        params = _require_params(params)
+        roots_raw = params.get("roots")
+        if not isinstance(roots_raw, list):
+            raise JsonRpcError(
+                "skills.list: `roots` (array of paths) is required",
+                code=-32602,
+                kind="invalid_params",
+            )
+        roots = [str(r) for r in roots_raw]
+        conditions = set(params.get("conditions") or [])
+        exclude = list(params.get("exclude") or [])
+        ignore_conditions = bool(params.get("ignoreConditions"))
+        provider = FilesystemSkillProvider(roots)
+        definitions = [d for d in provider.list() if isinstance(d, SkillDefinition)]
+        selected = select_skills(definitions, conditions, exclude, ignore_conditions)
+        return {"skills": [skill_to_dict(d) for d in selected]}
+
+    async def _handle_trace_fetch(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        params = _require_params(params)
+        trace_id = params.get("traceId")
+        if not trace_id:
+            raise JsonRpcError("traceId required", code=-32602, kind="invalid_params")
+        trace = await self.storage.get_trace(trace_id)
+        if trace is None:
+            raise JsonRpcError(
+                f"trace not found: {trace_id}", code=-32004, kind="invalid_request"
+            )
+        spans = await self.storage.list_spans(trace_id)
+        events = await self.storage.list_events(trace_id)
+        # Bound the payload. A long agentic turn logs events at roughly
+        # 200-800/round; the 259-round incident produced 161k events ≈ 39 MB of
+        # JSON, which the host's single-RPC fetch (5 s) could never pull — the
+        # trace was silently dropped, and the biggest runs are exactly the ones
+        # worth inspecting. Head + tail keeps the setup and (more importantly)
+        # *how the run ended*; the dropped middle is the thrash. The markers
+        # below tell the host — and the trace viewer — that the slice is
+        # partial, so a truncated trace is never mistaken for a whole one.
+        total_events = len(events)
+        max_events = _trace_fetch_max_events(params)
+        truncated = max_events is not None and total_events > max_events
+        if truncated and max_events is not None:
+            head = max(0, max_events // 4)
+            events = [*events[:head], *events[-(max_events - head) :]]
+        payload: dict[str, Any] = {
+            "trace": trace.model_dump(exclude_none=True),
+            "spans": [s.model_dump(exclude_none=True) for s in spans],
+            "events": [e.model_dump(exclude_none=True) for e in events],
+        }
+        if truncated:
+            payload["eventsTotal"] = total_events
+            payload["eventsTruncated"] = True
+        return payload
+
+    async def _handle_trace_export(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Export a stored trace to an OTLP/HTTP collector (W6-6).
+
+        Params: ``traceId`` (required), ``endpoint`` (required, the collector's
+        ``/v1/traces`` URL), ``privacyMode`` (``"full"`` | ``"metadata"``,
+        default ``"metadata"``), ``serviceName`` (optional). The payload is
+        secret-redacted regardless of mode; ``metadata`` additionally strips
+        event payload bodies and free-form span attributes.
+        """
+        params = _require_params(params)
+        trace_id = params.get("traceId")
+        endpoint = params.get("endpoint")
+        if not trace_id:
+            raise JsonRpcError("traceId required", code=-32602, kind="invalid_params")
+        if not endpoint:
+            raise JsonRpcError("endpoint required", code=-32602, kind="invalid_params")
+        privacy_mode = params.get("privacyMode", "metadata")
+        if privacy_mode not in ("full", "metadata"):
+            raise JsonRpcError(
+                f"invalid privacyMode: {privacy_mode}",
+                code=-32602,
+                kind="invalid_params",
+            )
+        trace = await self.storage.get_trace(trace_id)
+        if trace is None:
+            raise JsonRpcError(
+                f"trace not found: {trace_id}", code=-32004, kind="invalid_request"
+            )
+        spans = await self.storage.list_spans(trace_id)
+        events = await self.storage.list_events(trace_id)
+        try:
+            status = export_trace(
+                trace,
+                spans,
+                events,
+                str(endpoint),
+                privacy_mode=privacy_mode,
+                service_name=str(params.get("serviceName") or "steerable-agent"),
+            )
+        except Exception as exc:  # collector unreachable / non-2xx
+            raise JsonRpcError(
+                f"trace export failed: {exc}", code=-32603, kind="internal"
+            ) from exc
+        return {"status": status, "traceId": trace_id, "privacyMode": privacy_mode}
+
+    async def _handle_metrics_export(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """POST turn-outcome counters to a collector's ``/v1/metrics`` (R4).
+
+        Params: ``samples`` (required) — one dict per finished turn with
+        ``outcome`` / ``failureKind`` / ``attempts`` / ``usedDirect`` —,
+        ``endpoint`` (required, the collector's ``/v1/metrics`` URL),
+        ``serviceName`` (optional).
+
+        Separate from ``trace.export`` because a collector may accept traces
+        and not metrics, or the reverse; the host calls this only when it has
+        turn outcomes to report. The payload carries no conversation content,
+        so there is nothing for the privacy mode to filter.
+        """
+        params = _require_params(params)
+        samples = params.get("samples")
+        endpoint = params.get("endpoint")
+        if not isinstance(samples, list) or not samples:
+            raise JsonRpcError("samples required", code=-32602, kind="invalid_params")
+        if not endpoint:
+            raise JsonRpcError("endpoint required", code=-32602, kind="invalid_params")
+        cleaned: list[dict[str, Any]] = []
+        for sample in samples:
+            if not isinstance(sample, dict):
+                raise JsonRpcError(
+                    "each sample must be an object", code=-32602, kind="invalid_params"
+                )
+            cleaned.append(sample)
+        try:
+            status = export_metrics(
+                cleaned,
+                str(endpoint),
+                service_name=str(params.get("serviceName") or "steerable-agent"),
+            )
+        except Exception as exc:  # collector unreachable / non-2xx
+            raise JsonRpcError(
+                f"metrics export failed: {exc}", code=-32603, kind="internal"
+            ) from exc
+        return {"status": status, "metrics": len(cleaned)}
+
+    async def _handle_config_get(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        base = {
+            "logLevel": self.config.log_level,
+            "gracePeriodSeconds": self.config.grace_period_seconds,
+            "version": SIDECAR_VERSION,
+            "protocolVersion": PROTOCOL_VERSION,
+        }
+        # ``{"merged": true}`` previews the layered user config (default →
+        # ~/.steerable/config.json → STEERABLE_* env), reporting each key's
+        # value and where it came from — the ``--dump-config`` counterpart.
+        # A malformed user file fails loud instead of serving stale defaults.
+        if isinstance(params, dict) and params.get("merged"):
+            from steerable_agent_runtime import resolve_config
+
+            resolved = resolve_config(
+                {
+                    "log_level": self.config.log_level,
+                    "grace_period_seconds": self.config.grace_period_seconds,
+                    "storage_path": self.config.storage_path,
+                }
+            )
+            base["merged"] = resolved.describe()
+        return base
+
+    async def _handle_config_set(self, params: dict[str, Any] | None) -> None:
+        params = _require_params(params)
+        log_level = params.get("logLevel")
+        if log_level is not None:
+            self.config.log_level = str(log_level)
+            logging.getLogger().setLevel(self.config.log_level)
+
+    async def _handle_compat_describe(
+        self, _params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Serve the compat-flag wire vocabulary to host settings UIs.
+
+        The framework owns the flag definitions (`describe_compat_flags`);
+        hosts render their compat section from this payload so a new flag
+        needs no host-side constant to stay in sync (ALIGN 2.3.3).
+        """
+        from steerable_agent_runtime.llm import describe_compat_flags
+
+        return {"flags": describe_compat_flags()}
+
+    async def _handle_sandbox_describe(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Report the per-exec enforcement this host can actually reach.
+
+        ``execSandbox.requireFull`` refuses every command whose backend
+        reports short of ``full``, and with egress open only Seatbelt can
+        reach ``full`` (it pins per host); bwrap and Landlock have no
+        per-host pinning.
+        anchor: packages/sidecar/py/src/steerable_sidecar/sandbox.py :: Windows\w*(ExecBackend|Rewriter)
+        Windows has no rewriter backend at all. A host
+        that decides ``requireFull`` from its own platform guess therefore
+        denies every shell call on the platforms it guessed wrong about.
+        Probing with the ``network`` / ``allowedHosts`` the turn will send
+        returns the enforcement that turn would get, so the host can pick a
+        posture it can satisfy and disclose the real one.
+
+        ``writableRoots`` is deliberately not consulted: every backend
+        derives ``enforcement`` from egress alone, so the answer is exact
+        rather than an approximation, and probing cannot fail on a root that
+        does not exist yet.
+        """
+        params = params or {}
+        backend = select_exec_backend(
+            network=bool(params.get("network")),
+            allowed_hosts=params.get("allowedHosts") or None,
+            shell=str(params.get("shell") or "/bin/sh"),
+        )
+        if backend is None:
+            return {"backend": "none", "enforcement": "none"}
+        return {"backend": backend.name, "enforcement": backend.enforcement}
+
+    def _require_plugin_registry(self) -> Any:
+        """The plugin registry, or an RPC error when the subsystem is unwired."""
+        if self.plugin_registry is None:
+            raise JsonRpcError(
+                "plugin subsystem is not wired on this sidecar",
+                code=-32602,
+                kind="invalid_params",
+            )
+        return self.plugin_registry
+
+    @staticmethod
+    def _plugin_record_dict(record: Any) -> dict[str, Any]:
+        return {
+            "name": record.name,
+            "origin": record.origin,
+            "tools": list(record.tools),
+            "enabled": record.enabled,
+            "reloadable": record.reloadable,
+        }
+
+    async def _handle_plugin_list(
+        self, _params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        registry = self._require_plugin_registry()
+        return {
+            "plugins": [
+                self._plugin_record_dict(record) for record in registry.plugins()
+            ]
+        }
+
+    async def _handle_plugin_enable(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        registry = self._require_plugin_registry()
+        name = str(_require_params(params).get("name") or "")
+        try:
+            registry.enable(name)
+        except PluginStateError as exc:
+            raise JsonRpcError(str(exc), code=-32602, kind="invalid_params") from exc
+        return {"plugin": self._plugin_record_dict(registry.get(name))}
+
+    async def _handle_plugin_disable(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        registry = self._require_plugin_registry()
+        name = str(_require_params(params).get("name") or "")
+        try:
+            registry.disable(name)
+        except PluginStateError as exc:
+            raise JsonRpcError(str(exc), code=-32602, kind="invalid_params") from exc
+        return {"plugin": self._plugin_record_dict(registry.get(name))}
+
+    async def _handle_plugin_reload(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        registry = self._require_plugin_registry()
+        name = str(_require_params(params).get("name") or "")
+        try:
+            registry.reload(name)
+        except (PluginStateError, PluginLoadError) as exc:
+            raise JsonRpcError(str(exc), code=-32602, kind="invalid_params") from exc
+        return {"plugin": self._plugin_record_dict(registry.get(name))}
+
+    async def _handle_plugin_tools_describe(
+        self, _params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Descriptors for every tool an enabled plugin has on the router.
+
+        Hosts that own the model-visible tool list (``toolsViaHost``) use
+        this to advertise plugin tools and forward calls back over
+        ``tool.invoke``; ``tool.list`` carries no mode or plugin owner.
+        Disabled plugins have no tools on the router, so they contribute none.
+        """
+        registry = self._require_plugin_registry()
+        tools: list[dict[str, Any]] = []
+        for record in registry.plugins():
+            if not record.enabled:
+                continue
+            for name in record.tools:
+                tool = self.tools.get(name)
+                if tool is None:
+                    continue
+                tools.append(
+                    {
+                        "name": tool.name,
+                        "description": tool.description,
+                        "schema": tool.schema,
+                        "mode": tool.mode,
+                        "exposure": tool.exposure,
+                        "requireConsent": tool.require_consent,
+                        "concurrencySafe": tool.concurrency_safe,
+                        "plugin": record.name,
+                    }
+                )
+        return {"tools": tools}
+
+    async def _handle_presets_describe(
+        self, _params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Serve the provider-preset table to host settings UIs.
+
+        Same service pattern as ``compat.describe``: the framework owns the
+        preset data (`describe_provider_presets`), hosts render their preset
+        picker from this payload so a new table entry needs no host change.
+        """
+        from steerable_agent_runtime.llm import describe_provider_presets
+
+        return {"presets": describe_provider_presets()}
+
+    async def _handle_presets_resolve(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Resolve the preset a given (baseUrl, model) pair would auto-match.
+
+        Powers the settings UI's "what applies" preview without the host
+        reimplementing the matching rules. ``preset`` is the camelCase wire
+        form, or ``None`` when no entry matches (or the layer is disabled
+        via ``STEERABLE_PROVIDER_PRESETS=0``).
+        """
+        from steerable_agent_runtime.llm import preset_for
+
+        params = params or {}
+        preset = preset_for(params.get("baseUrl"), params.get("model"))
+        return {"preset": preset.to_dict() if preset is not None else None}
+
+    async def _handle_catalog_describe(
+        self, _params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Serve the bundled serving-provider catalog to host settings UIs.
+
+        Same service pattern as ``compat.describe`` / ``presets.describe``:
+        the framework owns default URLs, wire kinds, and chat-capable model
+        ids. Hosts render the vendor picker from this payload so a catalog
+        refresh needs no host-side constant.
+        """
+        from steerable_agent_runtime.model_resolve import describe_catalog_providers
+
+        return {"providers": describe_catalog_providers()}
+
+    async def _handle_models_list(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Serve the gateway's live model catalog to host model pickers.
+
+        The gateway's own ``GET /models`` names the ids the endpoint
+        actually accepts — discovery, not a routing whitelist (a host may
+        still send an unlisted id). Each id is joined with catalog
+        capabilities via the same leaf join the request path uses, so the
+        picker and ``clamp_reasoning_effort`` never disagree about a model's
+        knob. A successful fetch is installed into the runtime's resolution
+        path (``register_gateway_models``) so window budgeting sees the
+        gateway-advertised windows.
+
+        ``catalogStatus``: ``live`` (just fetched), ``stale`` (refresh
+        failed, previous listing served), ``offline`` (no listing at all —
+        the picker falls back to free-form entry). Offline is a 200, not an
+        RPC error: an unreachable gateway must not break the host's
+        settings screen.
+        """
+        from steerable_agent_runtime import (
+            REASONING_EFFORT_ORDER,
+            register_gateway_models,
+        )
+        from steerable_agent_runtime.gateway_catalog import (
+            GatewayCatalogError,
+            fetch_gateway_models,
+            merge_with_catalog,
+        )
+
+        params = params or {}
+        base_url = params.get("baseUrl") or os.environ.get("STEERABLE_BASE_URL", "")
+        api_key = params.get("apiKey") or os.environ.get("STEERABLE_API_KEY", "")
+        provider = params.get("provider")
+        if not base_url:
+            raise JsonRpcError(
+                "models.list requires baseUrl (or STEERABLE_BASE_URL)",
+                code=-32602,
+                kind="invalid_params",
+            )
+        try:
+            refresh = bool(params.get("refresh"))
+            listing = await fetch_gateway_models(
+                str(base_url),
+                str(api_key) or None,
+                provider=str(provider) if provider else None,
+                **({"ttl_sec": 0} if refresh else {}),
+            )
+        except GatewayCatalogError as exc:
+            return {"models": [], "catalogStatus": "offline", "error": str(exc)}
+        rows = merge_with_catalog(listing.entries, base_url=str(base_url))
+        register_gateway_models(row.info for row in rows)
+        return {
+            "models": [
+                {
+                    "id": row.id,
+                    "name": row.name,
+                    "window": row.info.context_window,
+                    "modalities": sorted(row.info.modalities),
+                    "reasoningLevels": [
+                        level
+                        for level in REASONING_EFFORT_ORDER
+                        if level in row.info.reasoning_levels
+                    ],
+                    "pricing": (
+                        {
+                            "promptPerMtok": row.prompt_price_per_mtok,
+                            "completionPerMtok": row.completion_price_per_mtok,
+                        }
+                        if row.prompt_price_per_mtok is not None
+                        or row.completion_price_per_mtok is not None
+                        else None
+                    ),
+                    "joinedFrom": row.joined_from,
+                    "capabilities": (
+                        "known" if row.joined_from is not None else "unknown"
+                    ),
+                }
+                for row in rows
+            ],
+            "catalogStatus": "stale" if listing.stale else "live",
+            "fetchedAt": listing.fetched_at,
+            "current": {
+                "model": os.environ.get("STEERABLE_MODEL") or None,
+                "reasoningEffort": os.environ.get("STEERABLE_REASONING_EFFORT")
+                or None,
+            },
+        }
+
+    async def _handle_harness_describe(
+        self, _params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Serve the harness vocabulary + the active default selection.
+
+        Same precedent as ``compat.describe`` (W1.2.2): the framework owns
+        the dimension/implementation catalog; hosts render harness pickers
+        from this payload so a new strategy needs no host-side constant.
+        """
+        from steerable_agent_runtime.harness_spec import (
+            describe_harness_registry,
+            load_harness_spec,
+        )
+
+        default_spec = load_harness_spec(_DEFAULT_HARNESS_SPEC_PATH)
+        return {
+            "default": default_spec.describe(),
+            "available": describe_harness_registry(),
+        }
+
+    async def _handle_chat_stream(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Start a streaming chat-completion run.
+
+        Params shape (all optional unless noted)::
+
+            {
+              "provider": "openai_compat" | "anthropic"             # required
+                        | "openai-responses" | "google" | <custom>,
+              "model": "gpt-4o-mini",                                # required
+              "messages": [{"role": "...", "content": "..."}],       # required
+              "baseUrl": "https://api.example.com/v1",
+              "apiKey":  "sk-...",
+              "temperature": 0.2,
+              "maxTokens": 1024,
+              "reasoningEffort": "high",  # per-request picker value; wins over
+                                        # STEERABLE_REASONING_EFFORT and the
+                                        # preset default. Strict: an effort the
+                                        # model cannot honor is an RPC error.
+              "tools":   [...],         # OpenAI tool descriptors
+              "streamId": "str_xyz",    # auto-generated if omitted
+              "providerOptions": {...}, # passthrough
+              "resume":  True,          # W7-1: continue the record's
+                                        # interrupted turn; messages must be
+                                        # empty, recordId (or chatId) required
+            }
+
+        Returns ``{"streamId": "..."}`` immediately. Chunks arrive as
+        ``stream.chunk`` notifications with ``{"streamId", "delta"}``;
+        completion is signalled by ``stream.done`` with ``{"streamId",
+        "finishReason", "usage"}``. Errors mid-stream are emitted as
+        ``stream.error``.
+        """
+
+        params = _require_params(params)
+        if self._transport is None:
+            raise JsonRpcError("transport not ready", code=-32099, kind="internal")
+        try:
+            provider = self._llm_provider_factory(params)
+        except Exception as exc:  # surface as RPC error before scheduling task
+            raise JsonRpcError(
+                f"failed to construct LLM provider: {exc}",
+                code=-32602,
+                kind="invalid_params",
+            ) from exc
+
+        stream_id = params.get("streamId") or _new_stream_id()
+        messages = _coerce_messages(params.get("messages") or [])
+        # W7-1: resume=true continues the durable record's interrupted turn
+        # instead of opening a new one. The record's projected transcript
+        # becomes the loop seed verbatim — the host neither re-sends the last
+        # user message nor fabricates a synthetic continuation prompt, and
+        # the loop's seed reconciliation sees an exact extension of the
+        # record, so no compaction.boundary is declared and the record
+        # continues linearly. `messages` must be empty: the record is
+        # authoritative and merging a second history would silently fork.
+        if params.get("resume"):
+            if not _use_coreloop(params):
+                raise JsonRpcError(
+                    "resume requires useCoreLoop",
+                    code=-32602,
+                    kind="invalid_params",
+                )
+            if messages:
+                raise JsonRpcError(
+                    "resume replays the durable record; messages must be empty",
+                    code=-32602,
+                    kind="invalid_params",
+                )
+            record_id = params.get("recordId") or params.get("chatId")
+            if not record_id:
+                raise JsonRpcError(
+                    "resume requires recordId (or chatId)",
+                    code=-32602,
+                    kind="invalid_params",
+                )
+            resumed = await load_history_transcript(self.storage, str(record_id))
+            if not resumed:
+                raise JsonRpcError(
+                    f"record {record_id} has no history to resume",
+                    code=-32602,
+                    kind="invalid_params",
+                )
+            # Defensive close: the loop's flush discipline keeps its own
+            # records free of dangling tool_calls, but the record is a
+            # durable artifact other writers/versions may have produced.
+            messages = close_dangling_tool_calls(resumed)
+            # seed_read_state (CC parity): under toolsViaHost the desktop's
+            # file tools own the write gate, but their readFileState is
+            # process-resident and empty after an app restart. Re-seed it
+            # from the record so the resumed session keeps its
+            # read-before-write evidence.
+            if params.get("toolsViaHost"):
+                await self._seed_host_read_state(str(record_id))
+            # The host re-sends its freshly assembled systemPrompt on every
+            # turn; the record's leading system message (written by the
+            # interrupted turn) must yield to it or the mutual-exclusion
+            # check below fires. Splicing it out keeps the seed an exact
+            # extension of the record when the prompt is unchanged.
+            if (
+                params.get("systemPrompt") is not None
+                and messages
+                and messages[0].role == "system"
+            ):
+                messages = messages[1:]
+        # W2.8.2: the host's assembled system prompt arrives as a typed
+        # fragment (token cap enforced at this boundary), not an opaque seed
+        # message. Supplying both seeds is a host bug — fail loud.
+        #
+        # Only the *leading* message counts as a competing seed. Later system
+        # messages are ordinary transcript content this sidecar itself injected
+        # — the skills catalog, `<world-state>`, reminders — and a resumed
+        # record replays them verbatim. Rejecting those would make resume
+        # impossible for every turn that carried a skill or world-state
+        # fragment.
+        system_prompt = params.get("systemPrompt")
+        if system_prompt is not None:
+            if messages and messages[0].role == "system":
+                raise JsonRpcError(
+                    "systemPrompt param and a system message in messages are "
+                    "mutually exclusive",
+                    code=-32602,
+                    kind="invalid_params",
+                )
+            from steerable_agent_runtime import (
+                SystemPromptFragment,
+                render_fragment_capped,
+            )
+
+            messages.insert(
+                0, render_fragment_capped(SystemPromptFragment(str(system_prompt)))
+            )
+
+        transport = self._transport
+        use_coreloop = _use_coreloop(params)
+        content_mode = params.get("contentMode", "all")
+        if content_mode not in ("all", "final"):
+            raise JsonRpcError(
+                "contentMode must be 'all' or 'final'",
+                code=-32602,
+                kind="invalid_params",
+            )
+        if content_mode == "final" and not use_coreloop:
+            raise JsonRpcError(
+                "contentMode 'final' requires useCoreLoop",
+                code=-32602,
+                kind="invalid_params",
+            )
+        # Validate the mcp param up front (foreground, so a malformed entry
+        # fails the request with a clean invalid_params rather than surfacing
+        # as an unretrieved exception inside the background stream task).
+        # Spawning/registration happens in _run_chat_stream_coreloop.
+        mcp_param = params.get("mcp")
+        if (
+            isinstance(mcp_param, list)
+            and not params.get("toolsViaHost")
+            and self._loop_hooks_factory is None
+        ):
+            for index, server in enumerate(mcp_param):
+                if not isinstance(server, dict):
+                    raise JsonRpcError(
+                        f"mcp[{index}] must be an object",
+                        code=-32602,
+                        kind="invalid_params",
+                    )
+                try:
+                    create_mcp_client(server)
+                except McpError as exc:
+                    raise JsonRpcError(
+                        f"mcp[{index}]: {exc}",
+                        code=-32602,
+                        kind="invalid_params",
+                    ) from exc
+        if use_coreloop:
+            task = asyncio.create_task(
+                self._run_chat_stream_coreloop_guarded(
+                    provider, messages, params, stream_id, transport
+                )
+            )
+        else:
+            kwargs = _build_provider_kwargs(params)
+            task = asyncio.create_task(
+                self._run_chat_stream(provider, messages, kwargs, stream_id, transport)
+            )
+        self._streams[stream_id] = task
+        return {"streamId": stream_id}
+
+    async def _handle_chat_cancel(self, params: dict[str, Any] | None) -> None:
+        params = _require_params(params)
+        stream_id = params.get("streamId")
+        if not stream_id:
+            raise JsonRpcError("streamId required", code=-32602, kind="invalid_params")
+        # CoreLoop streams cancel cooperatively: the loop winds down at the
+        # next safe point, records the partial turn (no dangling tool_calls),
+        # and its terminal completion surfaces as stream.done with
+        # status="cancelled". A watchdog hard-cancels the task if the wind-
+        # down wedges (e.g. a provider stream that never yields).
+        loop = self._coreloops.get(stream_id)
+        if loop is not None:
+            loop.cancel()
+            task = self._streams.get(stream_id)
+            if task is not None and not task.done():
+                watchdog = asyncio.ensure_future(
+                    self._hard_cancel_after(task, stream_id)
+                )
+                self._cancel_watchdogs.add(watchdog)
+                watchdog.add_done_callback(self._cancel_watchdogs.discard)
+            return
+        task = self._streams.pop(stream_id, None)
+        if task is not None and not task.done():
+            task.cancel()
+
+    async def _hard_cancel_after(
+        self, task: asyncio.Task[None], stream_id: str
+    ) -> None:
+        """Backstop for cooperative cancel: if the loop has not finished
+        within the grace window, cancel the task outright."""
+        await asyncio.sleep(_CANCEL_GRACE_S)
+        if not task.done():
+            logger.warning(
+                "stream %s did not wind down within %.0fs of cancel; hard-cancelling",
+                stream_id,
+                _CANCEL_GRACE_S,
+            )
+            task.cancel()
+
+    async def _handle_chat_fork(self, params: dict[str, Any] | None) -> dict[str, Any]:
+        """Start a new CoreLoop stream seeded from a recorded trace — the
+        variant/regenerate primitive for trace-sourced sessions.
+
+        Params: everything ``agent.chat.stream`` takes (provider/model are
+        required), plus ONE fork source::
+
+            {
+              "recordId": "chat_...",       # Wave 1: fork the durable record
+              "untilSeq": 41,               # optional inclusive record-seq bound
+                                            # (see resume.load_history_transcript)
+              # — or, legacy trace source —
+              "traceId": "tr_...",          # the trace to fork from
+              "untilSequence": 41,          # optional inclusive event-sequence
+                                            # bound (see resume.project_transcript)
+              "messages": [...],            # optional messages appended after
+                                            # the projected seed (e.g. the
+                                            # re-asked user turn)
+            }
+
+        A record fork runs under a fresh ``<recordId>:fork:<streamId>``
+        record seeded by one provenance-carrying ``history.seed`` entry, so
+        the variant never pollutes the source chat's log.
+
+        Returns ``{"streamId", "seedMessages"}``. The fork always runs the
+        CoreLoop path (projection is a CoreLoop concept) and records its own
+        trace, so each variant is independently auditable. Hosts that keep
+        their own message store (the desktop) don't need this RPC — they
+        truncate their store and call ``agent.chat.stream`` with the rebuilt
+        history.
+        """
+        params = _require_params(params)
+        if self._transport is None:
+            raise JsonRpcError("transport not ready", code=-32099, kind="internal")
+        stream_id = params.get("streamId") or _new_stream_id()
+        source_record = params.get("recordId")
+        if source_record is not None:
+            # Wave 1 record fork (Wave 5: via branch.fork_record): seed from
+            # the durable record (optionally truncated at a record seq) into
+            # a FRESH record id, so the variant never pollutes the source
+            # chat's log. The seed entry is persisted up front with
+            # provenance and per-message kinds (the loop's host-view
+            # reconciliation needs them to keep forked records continuous);
+            # the run's own continuous-log seeding then recognises the
+            # prefix and only appends genuinely new items.
+            until_seq = params.get("untilSeq")
+            try:
+                fork = await fork_record(
+                    self.storage,
+                    str(source_record),
+                    until_seq=int(until_seq) if until_seq is not None else None,
+                    new_record_id=f"{source_record}:fork:{stream_id}",
+                )
+            except KeyError:
+                raise JsonRpcError(
+                    f"record not found: {source_record}",
+                    code=-32004,
+                    kind="invalid_request",
+                ) from None
+            seed = list(fork.messages)
+            params = {**params, "recordId": fork.point.record_id}
+        else:
+            trace_id = params.get("traceId")
+            if not trace_id:
+                raise JsonRpcError(
+                    "traceId or recordId required", code=-32602, kind="invalid_params"
+                )
+            events = await self.storage.list_events(str(trace_id))
+            if not events:
+                raise JsonRpcError(
+                    f"trace not found: {trace_id}", code=-32004, kind="invalid_request"
+                )
+            events.sort(key=lambda e: getattr(e, "sequence", 0))
+            until = params.get("untilSequence")
+            seed = project_transcript(
+                events, until_sequence=int(until) if until is not None else None
+            )
+        seed.extend(_coerce_messages(params.get("messages") or []))
+
+        try:
+            provider = self._llm_provider_factory(params)
+        except Exception as exc:
+            raise JsonRpcError(
+                f"failed to construct LLM provider: {exc}",
+                code=-32602,
+                kind="invalid_params",
+            ) from exc
+
+        transport = self._transport
+        task = asyncio.create_task(
+            self._run_chat_stream_coreloop_guarded(
+                provider, seed, params, stream_id, transport
+            )
+        )
+        self._streams[stream_id] = task
+        return {"streamId": stream_id, "seedMessages": len(seed)}
+
+    async def _handle_session_fork(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Fork a durable record WITHOUT running a turn (Wave 5).
+
+        Params::
+
+            {
+              "recordId": "chat_...",        # the source record (required)
+              "untilSeq": 41,                # exact inclusive fork point, or
+              "beforeLastUser": true,        # regen addressing: fork at the
+                                             # newest user item (the prompting
+                                             # turn stays, the reply is dropped)
+              "beforeUserIndex": 2,          # regen addressing by user-message
+                                             # ordinal (mid-history regen)
+              "newRecordId": "chat_...:r2",  # optional explicit branch id
+              "label": "...",                # optional host-supplied summary
+            }
+
+        Returns the BranchPoint (``recordId``, ``sourceRecordId``,
+        ``sourceUntilSeq``, ``label``) plus ``seedMessages`` (count). The
+        host then runs turns on the branch by passing the returned
+        ``recordId`` to ``agent.chat.stream``. The source record is never
+        mutated — this is the non-destructive regenerate primitive: the old
+        tail stays intact and discoverable via ``agent.session.branches``.
+        """
+        params = _require_params(params)
+        source_record = params.get("recordId")
+        if not source_record:
+            raise JsonRpcError("recordId required", code=-32602, kind="invalid_params")
+        until_seq = params.get("untilSeq")
+        user_index = params.get("beforeUserIndex")
+        if until_seq is None and user_index is not None:
+            until_seq = await resolve_fork_seq(
+                self.storage, str(source_record), user_index=int(user_index)
+            )
+            if until_seq is None:
+                raise JsonRpcError(
+                    f"user message index {user_index} not addressable in "
+                    f"record: {source_record}",
+                    code=-32004,
+                    kind="invalid_request",
+                )
+        if until_seq is None and params.get("beforeLastUser"):
+            until_seq = await resolve_fork_seq(
+                self.storage, str(source_record), before_last_user=True
+            )
+            if until_seq is None:
+                raise JsonRpcError(
+                    f"no user message to fork before: {source_record}",
+                    code=-32004,
+                    kind="invalid_request",
+                )
+        try:
+            fork = await fork_record(
+                self.storage,
+                str(source_record),
+                until_seq=int(until_seq) if until_seq is not None else None,
+                new_record_id=(
+                    str(params["newRecordId"]) if params.get("newRecordId") else None
+                ),
+                label=str(params["label"]) if params.get("label") else None,
+            )
+        except KeyError:
+            raise JsonRpcError(
+                f"record not found: {source_record}",
+                code=-32004,
+                kind="invalid_request",
+            ) from None
+        point = fork.point
+        return {
+            "recordId": point.record_id,
+            "sourceRecordId": point.source_record_id,
+            "sourceUntilSeq": point.source_until_seq,
+            "label": point.label,
+            "seedMessages": len(fork.messages),
+        }
+
+    async def _handle_session_branches(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Branch-family view of a record (Wave 5).
+
+        Returns ``{"lineage": [...root-first BranchPoints...], "children":
+        [...]}``. Lineage walks seed provenance upwards and always works;
+        children discovery needs record enumeration — stores implementing
+        Children discovery enumerates the record space
+        (``list_history_records``, first-class since W3.1.2) and keeps
+        records whose seed names this one as source.
+        """
+        params = _require_params(params)
+        record_id = params.get("recordId")
+        if not record_id:
+            raise JsonRpcError("recordId required", code=-32602, kind="invalid_params")
+        chain = await lineage(self.storage, str(record_id))
+        children: list[dict[str, Any]] = []
+        for candidate in await self.storage.list_history_records():
+            if candidate == record_id:
+                continue
+            first = await self.storage.list_history(candidate, limit=1)
+            if not first:
+                continue
+            entry = entry_from_dict(first[0])
+            if (
+                isinstance(entry, HistorySeed)
+                and entry.source_record_id == record_id
+            ):
+                children.append(
+                    {
+                        "recordId": candidate,
+                        "sourceRecordId": record_id,
+                        "sourceUntilSeq": entry.source_until_seq,
+                        "label": branch_label(list(entry.messages)),
+                    }
+                )
+        return {
+            "lineage": [
+                {
+                    "recordId": point.record_id,
+                    "sourceRecordId": point.source_record_id,
+                    "sourceUntilSeq": point.source_until_seq,
+                    "label": point.label,
+                    "depth": point.depth,
+                }
+                for point in chain
+            ],
+            "children": children,
+        }
+
+    async def _handle_session_tree(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Full branch family containing a record (session-tree view).
+
+        Params: ``{"recordId": "chat_..."}``. Returns ``{"recordId",
+        "tree", "nodeCount", "truncated"}`` where ``tree`` is the family
+        root as a recursive node::
+
+            {
+              "recordId", "sourceRecordId", "sourceUntilSeq",
+              "label", "depth",          # depth 0 on the root
+              "children": [...]          # same shape, recursively
+            }
+
+        This is the single-call tree a host needs to render a pi-style
+        full-tree branch view and to validate switching to ANY family
+        member (cousins included) — ``agent.session.branches`` only sees
+        the lineage plus direct children. Expansion is bounded (depth ≤
+        32, nodes ≤ 500 — see ``branch.family_tree``); a cut family comes
+        back with ``truncated: true``. Unknown record → invalid_request;
+        lineage corruption (cycle) → invalid_request, both fail loud.
+        """
+        params = _require_params(params)
+        record_id = params.get("recordId")
+        if not record_id:
+            raise JsonRpcError("recordId required", code=-32602, kind="invalid_params")
+        try:
+            family = await family_tree(self.storage, str(record_id))
+        except KeyError:
+            raise JsonRpcError(
+                f"record not found: {record_id}",
+                code=-32004,
+                kind="invalid_request",
+            ) from None
+        except ValueError as exc:
+            raise JsonRpcError(
+                str(exc), code=-32004, kind="invalid_request"
+            ) from None
+
+        def node_to_dict(node: FamilyTreeNode) -> dict[str, Any]:
+            return {
+                "recordId": node.record_id,
+                "sourceRecordId": node.source_record_id,
+                "sourceUntilSeq": node.source_until_seq,
+                "label": node.label,
+                "depth": node.depth,
+                "children": [node_to_dict(child) for child in node.children],
+            }
+
+        return {
+            "recordId": str(record_id),
+            "tree": node_to_dict(family.root),
+            "nodeCount": family.node_count,
+            "truncated": family.truncated,
+        }
+
+    async def _handle_session_messages(
+        self, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        """Projected transcript of a history record (W1.2.1).
+
+        ``{"recordId", "messages": [{seq, role, content}...]}`` — the
+        post-boundary visible span, i.e. what the model would see on resume.
+        This is the read path a host needs to render/switch branches: the
+        branch's messages live in the framework record, not the host's UI
+        store. Unknown record → invalid_request (fail loud, not an empty
+        list that looks like an empty branch).
+        """
+        from steerable_agent_runtime.resume import load_history_items
+
+        params = _require_params(params)
+        record_id = params.get("recordId")
+        if not record_id:
+            raise JsonRpcError("recordId required", code=-32602, kind="invalid_params")
+        items = await load_history_items(self.storage, str(record_id))
+        if items is None:
+            raise JsonRpcError(
+                f"record not found: {record_id}", code=-32004, kind="invalid_request"
+            )
+        messages = []
+        for item in items:
+            content = "".join(
+                getattr(part, "text", "")
+                for part in item.message.content
+                if getattr(part, "type", None) == "text"
+            ) if isinstance(item.message.content, list) else str(item.message.content)
+            messages.append(
+                {"seq": item.seq, "role": item.message.role, "content": content}
+            )
+        return {"recordId": str(record_id), "messages": messages}
+
+    async def _handle_chat_steer(self, params: dict[str, Any] | None) -> dict[str, Any]:
+        """Inject a user message into a running CoreLoop turn.
+
+        Soft-fail with ``{"ok": False}`` when the stream is unknown or not
+        CoreLoop-backed — between the user hitting send and this RPC landing,
+        the turn may legitimately have completed.
+        """
+        params = _require_params(params)
+        stream_id = params.get("streamId")
+        content = params.get("content")
+        if not stream_id or not isinstance(content, str) or not content.strip():
+            raise JsonRpcError(
+                "streamId and non-empty content required",
+                code=-32602,
+                kind="invalid_params",
+            )
+        loop = self._coreloops.get(stream_id)
+        if loop is None:
+            return {"ok": False, "reason": "stream_not_active"}
+        # Composer sandbox (workspace / full) rides with the interjection so
+        # the next shell call in this turn matches the picker. Unknown values
+        # leave the turn's original sandbox alone.
+        policy = params.get("execPolicy")
+        if policy in ("full", "workspace"):
+            control = self._exec_controls.get(stream_id)
+            if control is not None:
+                control.apply(str(policy))
+        loop.steer(content)
+        return {"ok": True}
+
+    async def _handle_chat_compact(self, params: dict[str, Any] | None) -> dict[str, Any]:
+        """Manually compact a running CoreLoop turn's transcript — the
+        host-command path (CC ``/compact`` parity).
+
+        The loop consumes the request at its next pre_step boundary: the
+        hook chain's ``compact_now`` folds old tool results and summarizes
+        the middle regardless of pressure, landing as a declared rewrite
+        plus a ``hook_action`` event. Soft-fails like steer — between the
+        host command and this RPC landing, the turn may legitimately have
+        completed.
+        """
+        params = _require_params(params)
+        stream_id = params.get("streamId")
+        if not stream_id:
+            raise JsonRpcError("streamId required", code=-32602, kind="invalid_params")
+        loop = self._coreloops.get(stream_id)
+        if loop is None:
+            return {"ok": False, "reason": "stream_not_active"}
+        loop.request_compact()
+        return {"ok": True}
+
+    async def _run_chat_stream(
+        self,
+        provider: LLMProvider,
+        messages: list[LLMMessage],
+        kwargs: dict[str, Any],
+        stream_id: str,
+        transport: StdioJsonRpcTransport,
+    ) -> None:
+        try:
+            iterator = provider.stream(messages, **kwargs)
+            async for chunk in iterator:
+                payload: dict[str, Any] = {"streamId": stream_id}
+                if chunk.content_delta is not None:
+                    payload["delta"] = chunk.content_delta
+                if chunk.reasoning_delta is not None:
+                    payload["reasoningDelta"] = chunk.reasoning_delta
+                if chunk.tool_call_delta is not None:
+                    payload["toolCall"] = chunk.tool_call_delta.model_dump(
+                        exclude_none=True
+                    )
+                if chunk.finish_reason is not None:
+                    payload["finishReason"] = chunk.finish_reason
+                if chunk.usage is not None:
+                    payload["usage"] = {
+                        "promptTokens": chunk.usage.prompt_tokens,
+                        "completionTokens": chunk.usage.completion_tokens,
+                        "totalTokens": chunk.usage.total_tokens,
+                    }
+                await transport.emit_notification("stream.chunk", payload)
+            await transport.emit_notification(
+                "stream.done", {"streamId": stream_id, "ok": True}
+            )
+        except asyncio.CancelledError:
+            await transport.emit_notification(
+                "stream.done", {"streamId": stream_id, "ok": False, "cancelled": True}
+            )
+        except Exception as exc:
+            logger.exception("chat stream %s failed", stream_id)
+            await transport.emit_notification(
+                "stream.error",
+                {
+                    "streamId": stream_id,
+                    "kind": exc.__class__.__name__,
+                    "message": str(exc),
+                },
+            )
+        finally:
+            self._streams.pop(stream_id, None)
+
+    async def _run_chat_stream_coreloop_guarded(
+        self,
+        provider: LLMProvider,
+        messages: list[LLMMessage],
+        params: dict[str, Any],
+        stream_id: str,
+        transport: StdioJsonRpcTransport,
+    ) -> None:
+        """Catch setup-phase failures the inner catch-all cannot reach.
+
+        ``_run_chat_stream_coreloop`` only starts converting exceptions into
+        ``stream.error`` once its ``try`` begins — a failure in the setup
+        region before it (tool registration, MCP client spawn, executor
+        wiring) would otherwise escape as an unretrieved task exception and
+        strand the host waiting for a terminal event that never comes.
+        """
+        try:
+            await self._run_chat_stream_coreloop(
+                provider, messages, params, stream_id, transport
+            )
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:  # last line before a stranded host
+            logger.exception("coreloop chat stream %s failed during setup", stream_id)
+            try:
+                await transport.emit_notification(
+                    "stream.error",
+                    {
+                        "streamId": stream_id,
+                        "kind": exc.__class__.__name__,
+                        "message": str(exc),
+                    },
+                )
+            except Exception:  # noqa: BLE001 — transport already broken
+                logger.warning("stream.error emit failed for %s", stream_id)
+
+    async def _run_chat_stream_coreloop(
+        self,
+        provider: LLMProvider,
+        messages: list[LLMMessage],
+        params: dict[str, Any],
+        stream_id: str,
+        transport: StdioJsonRpcTransport,
+    ) -> None:
+        """CoreLoop-backed chat stream (flag-gated — see ``_use_coreloop``).
+
+        Maps LoopEvents onto the existing wire surface so hosts don't need a
+        new protocol to opt in: content/reasoning deltas and tool progress
+        arrive as ``stream.chunk``; the terminal completion arrives as
+        ``stream.done`` with the loop's status/reason attached.
+
+        ``contentMode: "final"`` buffers each provider call's display text
+        until its outcome is known. A new request replaces a rejected retry
+        draft, and a tool call discards that request's narration. Only the
+        terminal tool-free response reaches the host; the durable record and
+        trace still retain every intermediate assistant turn.
+
+        ``mcp`` mounts per-turn MCP servers on the sidecar-local path.
+        Stdio entries use ``command`` and Streamable HTTP entries use
+        ``url``; each client registers its catalog under the
+        ``mcp__<name>__<tool>`` prefix on this turn's router, and closes the
+        clients when the stream ends (completion, error, or cancel). It is
+        the sidecar-local counterpart of the ACP adapter's ``mcpServers``
+        wiring (``acp_adapter``); over ``toolsViaHost`` the host owns tool
+        execution, so MCP mounting is a desktop concern instead.
+        """
+
+        # mcp: per-turn MCP servers on the sidecar-local path. Each entry
+        # creates one transport client; its catalog is registered on this
+        # turn's router under the ``mcp__<name>__<tool>`` prefix. Clients close
+        # in this method's ``finally`` so a completion, error, or cancel never
+        # leaks a transport. Skipped under toolsViaHost (the host owns
+        # execution there) and when an embedder replaces the whole harness
+        # (the hooks factory owns the tool surface).
+        mcp_clients: list[McpClient] = []
+        mcp_param = params.get("mcp")
+        if (
+            isinstance(mcp_param, list)
+            and mcp_param
+            and not params.get("toolsViaHost")
+            and self._loop_hooks_factory is None
+        ):
+            # Entries were shape-validated in _handle_chat_stream.
+            for index, server in enumerate(mcp_param):
+                name = str(server.get("name") or f"mcp{index}")
+                client = create_mcp_client(server)
+                await client.start()
+                mcp_clients.append(client)
+                catalog = await client.list_tools()
+                register_mcp_catalog(
+                    self.tools,
+                    server=name,
+                    tools=catalog,
+                    invoker=mcp_invoker(client),
+                )
+
+        if self._loop_hooks_factory is not None:
+            # An embedder-supplied hooks factory replaces the whole default
+            # assembly, tools dimension included — no selection is applied.
+            hooks: LoopHooks = self._loop_hooks_factory(params)
+            tool_selection: Any = None
+        else:
+            default_harness = _assemble_default_harness(
+                params, summarizer=_summarizer_for(provider)
+            )
+            hooks = default_harness.hooks
+            tool_selection = default_harness.tool_selection
+        # todo completion gate: a turn that ends `completed` while the
+        # chat's todo list still has unfinished items is retried with a
+        # reminder instead of stalling for user input (long-task stall fix).
+        # The gate keys the store by the run's LoopContext.chat_id — the same
+        # id todo_write dispatches with — so it reads the list the model wrote.
+        from .todo_tools import todo_store
+
+        hooks = ChainHooks(hooks, TodoCompletionGate(todo_store()))
+        # Planning nudge: one reminder per turn when a long run never wrote
+        # a task list. Per-run instance — it counts this turn's tool calls.
+        if self.tools.get("todo_write") is not None:
+            hooks = ChainHooks(hooks, TodoPlanningNudge(todo_store()))
+        # The bundled spec's tools dimension governs the host-supplied tool
+        # surface; the sidecar's own additions below (subagent / skills /
+        # orchestration) are orthogonal dimensions advertised past
+        # selection, mirroring the headless assembly. The bundled `full`
+        # strategy is a pass-through. A router-backed strategy
+        # (progressive) cannot run on this path — host tools dispatch over
+        # the reverse channel, so there is no in-process ToolRouter to bind
+        # — and must fail loud rather than offer a dead descriptor.
+        tools = params.get("tools")
+        from steerable_agent_runtime.approval import declared_resolver as _declared_resolver
+
+        approval_resolve = _declared_resolver(tools if isinstance(tools, list) else None)
+        if isinstance(tools, list):
+            tools = [_model_tool(tool) for tool in tools]
+        if tools is not None and tool_selection is not None:
+            try:
+                tools = tool_selection.select(list(tools))
+            except ValueError as exc:
+                logger.error("chat stream %s rejected: %s", stream_id, exc)
+                await transport.emit_notification(
+                    "stream.error",
+                    {
+                        "streamId": stream_id,
+                        "kind": exc.__class__.__name__,
+                        "message": str(exc),
+                    },
+                )
+                self._streams.pop(stream_id, None)
+                return
+        # antiHallucination: sink the desktop loop's four guards (data-need
+        # routing, deferred/claimed retry, grounding judge, narration) into
+        # the CoreLoop via hooks. Off unless the host opts in.
+        ah = params.get("antiHallucination")
+        if ah:
+            ah_opts = ah if isinstance(ah, dict) else {}
+            tool_context = params.get("toolContext") or {}
+            hooks = ChainHooks(
+                AntiHallucinationHooks(
+                    provider,
+                    AntiHallucinationConfig(
+                        mode=tool_context.get("mode"),
+                        user_question=_last_message_content(messages, "user"),
+                        last_assistant_tail=_last_message_content(
+                            messages, "assistant", tail=400
+                        ),
+                        max_retries=int(ah_opts.get("maxRetries") or 2),
+                        tools_available=bool(params.get("tools")),
+                    ),
+                ),
+                hooks,
+            )
+        # toolsViaHost: every tool call is forwarded to the host over the
+        # reverse channel (desktop deployment — tools live in Electron).
+        # Otherwise the sidecar-local registry executes them.
+        executor = (
+            HostToolExecutor(
+                self.server, tool_context=params.get("toolContext") or None
+            )
+            if params.get("toolsViaHost")
+            else RouterToolExecutor(self.tools)
+        )
+        # execSandbox: opt-in per-exec confinement for shell/subprocess
+        # calls (Wave 3). The command is rewritten to run under the
+        # platform's backend (Seatbelt on macOS, bwrap on Linux) and then
+        # delegated — over toolsViaHost the confined command is spawned by
+        # the host's shell, giving the desktop per-exec confinement without
+        # the host learning sandbox mechanics. Wrapped inside the approval
+        # layer so the approver reviews the ORIGINAL command, not the
+        # sandboxed invocation. Absent → commands run unconfined (legacy
+        # behavior); enabled with no available backend → enforcement "none"
+        # (requireFull refuses anything short of full; requireBackend
+        # refuses only enforcement "none" — the desktop uses the latter so
+        # honest-partial Seatbelt/bwrap still runs).
+        # Kept on the turn so a later steer can switch workspace / full
+        # access without rebuilding the executor chain.
+        exec_control = _TurnExecControl()
+        exec_sandbox = params.get("execSandbox")
+        if isinstance(exec_sandbox, dict) and exec_sandbox.get("enabled"):
+            backend = select_exec_backend(
+                writable_roots=[
+                    str(r) for r in exec_sandbox.get("writableRoots") or []
+                ],
+                network=bool(exec_sandbox.get("network")),
+                allowed_hosts=exec_sandbox.get("allowedHosts") or None,
+                shell=str(exec_sandbox.get("shell") or "/bin/sh"),
+            )
+            if backend is None and exec_sandbox.get("hostSpawn"):
+                # W2.2.1: no local rewriter backend (Windows) — delegate
+                # confined spawn to the host over the reverse channel
+                # instead of rewriting the command. The host owns the real
+                # confinement (restricted token + JobObject) and reports the
+                # enforcement it applied; absent capability fails closed.
+                from .host_spawn import HostSpawnExecutor
+
+                executor = HostSpawnExecutor(
+                    executor,
+                    self.server,
+                    policy={
+                        "writableRoots": [
+                            str(r) for r in exec_sandbox.get("writableRoots") or []
+                        ],
+                        "network": bool(exec_sandbox.get("network")),
+                        "allowedHosts": exec_sandbox.get("allowedHosts") or [],
+                    },
+                    shell_tools=(
+                        exec_sandbox["tools"]
+                        if exec_sandbox.get("tools") is not None
+                        else DEFAULT_SHELL_TOOLS
+                    ),
+                    command_arg=str(exec_sandbox.get("commandArg") or "command"),
+                )
+                exec_control.sandbox = executor
+            else:
+                executor = SandboxedToolExecutor(
+                    executor,
+                    backend,
+                    shell_tools=(
+                        exec_sandbox["tools"]
+                        if exec_sandbox.get("tools") is not None
+                        else DEFAULT_SHELL_TOOLS
+                    ),
+                    command_arg=str(exec_sandbox.get("commandArg") or "command"),
+                    require_full=bool(exec_sandbox.get("requireFull")),
+                    require_backend=bool(exec_sandbox.get("requireBackend")),
+                )
+                exec_control.sandbox = executor
+        # approval: opt-in approval algebra (Wave 3). ``{"mode": "auto"}`` is
+        # the headless policy (safe modes auto-approve, the rest auto-deny —
+        # a run never hangs on a prompt nobody answers); ``{"mode": "host"}``
+        # asks the host UI over the reverse channel. Absent → no approval
+        # layer, the router's require_consent gate alone (legacy behavior).
+        # Wrapped innermost so a subagent's child-loop calls are gated too.
+        approval = params.get("approval")
+        if isinstance(approval, dict) and approval.get("mode") in ("auto", "host"):
+            timeout_ms = approval.get("timeoutMs")
+            store_path = approval.get("storePath")
+            # W2.4: pattern rules (codex execpolicy's counterpart). Loaded
+            # from ``policyPath`` and consulted after the lattice's own
+            # caches, before the interactive/headless approver; host replies
+            # may amend it (``amendment`` payload → durable rule). The sink
+            # updates the live in-memory policy too, so an amendment takes
+            # effect within the same run, not just on the next one.
+            approver: Any
+            approval_chat_id = _approval_prompt_chat_id(params)
+            policy_path = approval.get("policyPath")
+            # In-project file targets do not ask. Roots come from the host's
+            # project fence (still sent when 「完整权限」 turns the OS sandbox
+            # off). The exec sandbox list is the fallback for callers that
+            # only set that. Shell calls skip the prompt only while that
+            # sandbox is actually on and the cwd stays in the roots; with
+            # the sandbox off, or a cwd outside the roots, the prompt stays.
+            # allow_once is not cached, so the next call is judged on its
+            # own paths. Sits under policy rules so an explicit deny still wins.
+            raw_roots = approval.get("writableRoots")
+            if (
+                not raw_roots
+                and isinstance(exec_sandbox, dict)
+                and exec_sandbox.get("enabled")
+            ):
+                raw_roots = exec_sandbox.get("writableRoots")
+            writable_roots = (
+                [str(root) for root in (raw_roots or []) if root]
+                if approval["mode"] == "host"
+                else []
+            )
+            raw_base = approval.get("pathBase")
+            path_base = str(raw_base) if isinstance(raw_base, str) and raw_base.strip() else None
+
+            def _sandbox_enforced() -> bool:
+                # The wrapper is installed before the first approve call, and
+                # steer updates this flag for the next shell call.
+                approver = exec_control.approver
+                return bool(getattr(approver, "_sandbox_enforced", False))
+
+            def _host_approver(amendment_sink: Any | None = None) -> Any:
+                host = HostApprover(
+                    self.server,
+                    amendment_sink=amendment_sink,
+                    chat_id=approval_chat_id,
+                    sandbox_enforced=_sandbox_enforced,
+                )
+                from steerable_agent_runtime.approval import WorkspaceAutoApprover
+
+                approver = WorkspaceAutoApprover(
+                    host,
+                    writable_roots,
+                    sandbox_enforced=bool(
+                        isinstance(exec_sandbox, dict) and exec_sandbox.get("enabled")
+                    ),
+                    auto_allow_tools=_AUTO_APPROVED_HOST_CONTROL_TOOLS,
+                    path_base=path_base,
+                )
+                exec_control.approver = approver
+                return approver
+
+            if policy_path:
+                from steerable_agent_runtime import (
+                    JsonApprovalPolicyStore,
+                    PolicyApprover,
+                )
+
+                policy_store = JsonApprovalPolicyStore(str(policy_path))
+                live_policy = policy_store.load()
+
+                def _amendment_sink(rule: Any) -> None:
+                    live_policy.add(rule)
+                    policy_store.add_rule(rule)
+
+                base = (
+                    AutoApprover()
+                    if approval["mode"] == "auto"
+                    else _host_approver(_amendment_sink)
+                )
+                approver = PolicyApprover(base, live_policy)
+            elif approval["mode"] == "auto":
+                approver = AutoApprover()
+            else:
+                approver = _host_approver()
+            executor = ApprovalExecutor(
+                executor,
+                approver,
+                session=self._approval_session(approval_chat_id or params.get("chatId")),
+                store=JsonApprovalStore(store_path) if store_path else None,
+                timeout_s=(float(timeout_ms) / 1000.0) if timeout_ms else None,
+                resolve=approval_resolve,
+            )
+        # Child-safe sidecar-local tools must be visible and dispatchable
+        # before SubagentExecutor snapshots its tool domain. User interaction
+        # is deliberately absent: children report questions through
+        # request_parent_input and the parent owns ask_user.
+        child_local_names: list[str] = []
+        if self.tools.get("todo_write") is not None:
+            from steerable_agent_runtime import todo_write_tool_descriptor
+            from .run_code import RunCodeBoundExecutor
+
+            child_local_names.append("todo_write")
+            tools = [*(tools or []), todo_write_tool_descriptor()]
+            executor = RunCodeBoundExecutor(
+                executor,
+                router=self.tools,
+                local_names=child_local_names,
+            )
+        # subagent: the delegation seam is ON BY DEFAULT (delegate-on-pool
+        # unification) — delegate_subagent is the model's single multi-agent
+        # surface; the six-tool orchestration family below is the opt-in
+        # advanced mode. ``params.subagent: false`` turns delegation off;
+        # a dict configures it. ``{"toolFilter": ["read_a", "read_b"]}``
+        # narrows the child's tool domain (W4-5): filtered-out calls fail
+        # closed with tool_not_delegated, so a read-only research sub-agent
+        # cannot reach the parent's write/shell tools by construction.
+        # Children run as pooled AgentPool runs: lifecycle lands on the
+        # agent.child notification stream, and a concurrent profile's
+        # same-round delegations execute in parallel under the pool budget.
+        loop_config = _build_loop_config(params)
+        subagent_param = params.get("subagent", True)
+        subagent_executor: SubagentExecutor | None = None
+        if subagent_param:
+            subagent_opts = subagent_param if isinstance(subagent_param, dict) else {}
+            tool_filter = (
+                frozenset(str(t) for t in subagent_opts.get("toolFilter"))
+                if isinstance(subagent_opts.get("toolFilter"), list)
+                else None
+            )
+            # Named profiles (CC ``subagent_type`` parity): the host passes
+            # ``{"profiles": {"researcher": {"toolFilter": [...], "model":
+            # "...", "maxRounds": N, "concurrent": bool}}}`` and the tool
+            # schema advertises the names as a ``subagent_type`` enum. An
+            # unknown name fails closed listing the registered ones.
+            # Round / tool-error walls inherit the parent loop unless a
+            # profile pins its own. The parent default is no cap, so an
+            # unpinned child is not stopped at SubagentConfig's 8 / 3.
+            registry = None
+            profiles = subagent_opts.get("profiles")
+            if isinstance(profiles, dict) and profiles:
+                registry = SubagentRegistry()
+                for name, profile_opts in profiles.items():
+                    p = profile_opts if isinstance(profile_opts, dict) else {}
+                    p_filter = (
+                        frozenset(str(t) for t in p.get("toolFilter"))
+                        if isinstance(p.get("toolFilter"), list)
+                        else None
+                    )
+                    registry.register(
+                        str(name),
+                        SubagentConfig(
+                            max_rounds=int(
+                                p.get("maxRounds", loop_config.max_rounds)
+                            ),
+                            max_tool_errors=int(
+                                p.get(
+                                    "maxToolErrors", loop_config.max_tool_errors
+                                )
+                            ),
+                            tool_filter=p_filter,
+                            model=(
+                                str(p["model"]) if p.get("model") is not None else None
+                            ),
+                            concurrent=bool(p.get("concurrent", False)),
+                            system_prompt=(
+                                str(p["systemPrompt"])
+                                if p.get("systemPrompt") is not None
+                                else None
+                            ),
+                            description=(
+                                str(p["description"])
+                                if p.get("description") is not None
+                                else SubagentConfig().description
+                            ),
+                        ),
+                    )
+
+            # Per-profile models resolve through a provider factory that
+            # re-enters the host's own factory with the model overridden —
+            # a profile naming a model the host cannot serve fails closed
+            # rather than silently running the parent's model.
+            def _subagent_provider_factory(model: str) -> LLMProvider:
+                overridden = {**params, "model": model}
+                return self._llm_provider_factory(overridden)
+
+            subagent_executor = SubagentExecutor(
+                executor,
+                provider,
+                SubagentConfig(
+                    tool_filter=tool_filter,
+                    max_parallel=int(subagent_opts.get("maxParallel", 4)),
+                    max_rounds=int(
+                        subagent_opts.get("maxRounds", loop_config.max_rounds)
+                    ),
+                    max_tool_errors=int(
+                        subagent_opts.get(
+                            "maxToolErrors", loop_config.max_tool_errors
+                        )
+                    ),
+                ),
+                registry=registry,
+                provider_factory=_subagent_provider_factory,
+                # Each child writes its own durable record
+                # (``<parent>:child:<lineage id>``) so the host can render
+                # the delegation's process; the id rides child_spawned.
+                history_store=self.storage,
+                record_id_prefix=(
+                    params.get("recordId") or params.get("chatId") or None
+                ),
+                # Children advertise the host tool surface (minus the
+                # delegation tool itself), narrowed per profile; the
+                # descriptor appended below is deliberately not in the
+                # snapshot — a child never re-delegates (depth-1).
+                tools=list(tools or []),
+                event_sink=lambda kind, data: self._emit_child_event(
+                    transport, stream_id, kind, data
+                ),
+            )
+            executor = subagent_executor
+            tools = [
+                *(tools or []),
+                subagent_tool_descriptor(registry=registry),
+            ]
+            # requiredProfiles: the host named these sub-agents for the turn
+            # (desktop ``@`` mentions), so finishing without delegating to
+            # one is a skipped instruction, not a choice. The prompt alone
+            # cannot enforce that — a turn that ran other tools and narrated
+            # the hand-off passes every other discipline guard.
+            required_profiles = [
+                str(name) for name in subagent_opts.get("requiredProfiles") or []
+            ]
+            if required_profiles:
+                hooks = ChainHooks(
+                    RequiredDelegationGate(
+                        required_profiles,
+                        tool_name=SubagentConfig().tool_name,
+                    ),
+                    hooks,
+                )
+        # worldState: slow-changing host context (time, workspace, git
+        # branch, …) as plain per-section data. The loop injects it once as
+        # a <world-state> fragment; later turns diff against the snapshot
+        # embedded in the last fragment — unchanged state costs zero tokens,
+        # a change costs one small RFC 7386 tail patch. Hosts adopting this
+        # stop rebuilding the system prompt per turn, keeping the cached
+        # prefix byte-stable.
+        world_state = params.get("worldState")
+        if isinstance(world_state, dict) and world_state:
+            hooks = ChainHooks(
+                WorldStateHooks(
+                    [
+                        StaticWorldStateSection(str(key), value)
+                        for key, value in world_state.items()
+                    ]
+                ),
+                hooks,
+            )
+        # skills: layered disclosure. The host injects the eager layer into
+        # the system prompt itself; the sidecar lists the catalog layer
+        # (first-round pre_step injection, recorded as a hook_action event)
+        # and answers `skill` tool calls with the full body. ``mode:
+        # "eager"`` keeps everything host-side (compat for hosts that have
+        # not adopted layered disclosure). Roots are host-local paths — the
+        # sidecar shares the filesystem with the desktop host.
+        skills_param = params.get("skills")
+        if (
+            isinstance(skills_param, dict)
+            and skills_param.get("mode", "layered") != "eager"
+        ):
+            roots = [str(r) for r in skills_param.get("roots") or []]
+            conditions = set(skills_param.get("conditions") or [])
+            exclude = list(skills_param.get("exclude") or [])
+            pinned = list(skills_param.get("pinned") or [])
+            ignore_conditions = bool(skills_param.get("ignoreConditions"))
+            if roots:
+                skill_provider = FilesystemSkillProvider(roots)
+                # `pinned` only suppresses the catalog entry: the host has
+                # already injected these bodies eagerly, but the model may
+                # still call `skill` (and must get the full body if eager
+                # injection was truncated). The readiness probe therefore
+                # also counts pinned skills that survive hard exclusion, so
+                # even a turn whose only visible skill is pinned still
+                # advertises the skill tool.
+                visible_catalog = select_catalog(
+                    skill_provider.list(), conditions, exclude, ignore_conditions
+                )
+                pinned_loadable = select_pinned_loadable(
+                    skill_provider.list(), pinned, exclude
+                )
+                catalog = select_catalog(
+                    skill_provider.list(),
+                    conditions,
+                    exclude,
+                    ignore_conditions,
+                    pinned,
+                )
+                if visible_catalog or pinned_loadable:
+                    if catalog:
+                        hooks = ChainHooks(
+                            SkillHooks(
+                                skill_provider,
+                                conditions=conditions,
+                                exclude=exclude,
+                                ignore_conditions=ignore_conditions,
+                                pinned=pinned,
+                            ),
+                            hooks,
+                        )
+                    executor = SkillExecutor(
+                        executor,
+                        skill_provider,
+                        conditions=conditions,
+                        exclude=exclude,
+                        ignore_conditions=ignore_conditions,
+                        pinned=pinned,
+                    )
+                    tools = [*(tools or []), skill_tool_descriptor()]
+        # orchestration: opt-in advanced multi-agent seam (P3.1) — the
+        # parent model drives parallel child CoreLoops through
+        # agent_spawn/send/wait/close/list/interrupt. OFF BY DEFAULT since
+        # the delegate-on-pool unification: delegate_subagent (above) is the
+        # single model-facing surface; the six tools ship only when the host
+        # passes ``orchestration: {"enabled": true, ...}``. Wrapped outermost
+        # so children inherit every gate below (approval, skills, subagent).
+        # Budgets fail closed (maxDepth/maxParallel); depth is structural —
+        # a child only has orchestration tools when its own pool is nested
+        # inside. When both surfaces are on the delegation seam ADOPTS this
+        # pool (attach_pool): one max_parallel budget, one lineage space,
+        # and delegate children appear in agent_list.
+        orchestration_param = params.get("orchestration")
+        orchestration: OrchestrationExecutor | None = None
+        if (
+            isinstance(orchestration_param, dict)
+            and orchestration_param
+            and not orchestration_param.get("enabled")
+        ):
+            # Pre-unification hosts passed a bare config dict (e.g.
+            # {"maxDepth": 1}) to enable the six tools. That no longer
+            # enables them — say so loudly instead of silently dropping.
+            logger.warning(
+                "orchestration config passed without enabled:true; the six "
+                "orchestration tools stay off (delegate_subagent is the "
+                "default multi-agent surface). Set orchestration.enabled=true "
+                "to opt into agent_spawn/send/wait/close/list/interrupt."
+            )
+        if isinstance(orchestration_param, dict) and orchestration_param.get("enabled"):
+            # Child round / tool-error walls inherit the parent loop unless the
+            # host pins them, matching the delegation profiles above.
+            orch_config = OrchestrationConfig(
+                max_depth=int(orchestration_param.get("maxDepth", 1)),
+                max_parallel=int(orchestration_param.get("maxParallel", 4)),
+                child_max_rounds=int(
+                    orchestration_param.get("childMaxRounds", loop_config.max_rounds)
+                ),
+                child_max_tool_errors=int(
+                    orchestration_param.get(
+                        "childMaxToolErrors", loop_config.max_tool_errors
+                    )
+                ),
+            )
+            orchestration = OrchestrationExecutor(
+                executor,
+                provider,
+                orch_config,
+                tools=list(tools or []),
+                event_sink=lambda kind, data: self._emit_child_event(
+                    transport, stream_id, kind, data
+                ),
+            )
+            if subagent_executor is not None:
+                subagent_executor.attach_pool(orchestration.pool)
+            executor = orchestration
+            tools = [
+                *(tools or []),
+                *orchestration_tool_descriptors(orch_config),
+            ]
+        # Router-answered tools (run_code, ask_user): registered on the
+        # sidecar's router but unknown to the host — under toolsViaHost the
+        # inner executor forwards every call to the host, so they must be
+        # intercepted here and dispatched locally regardless of which subset
+        # is enabled.
+        local_names: list[str] = []
+        if self.tools.get("run_code") is not None:
+            from .run_code import run_code_tool_descriptor
+
+            local_names.append("run_code")
+            # Advertise the tool to the model: registration on the router only
+            # enables dispatch; the descriptor must also reach the tools array
+            # (mirrors subagent/skills above) or the model never sees run_code.
+            tools = [*(tools or []), run_code_tool_descriptor()]
+        # todo_write: session task list (CC TodoWrite parity). Registered
+        # unconditionally at boot and advertised above before the subagent
+        # snapshots its domain. Keep it in this outer dispatcher too so
+        # parent run_code calls capture the complete executor chain.
+        if self.tools.get("todo_write") is not None:
+            local_names.append("todo_write")
+        # run_js/wait_js: conversational JS PTC (the codex CodeModeHost
+        # counterpart). Same router-answered local dispatch as run_code; the
+        # session binds to this run's chatId inside the tool.
+        if self.tools.get("run_js") is not None:
+            from .ptc_js import run_js_tool_descriptor, wait_js_tool_descriptor
+
+            local_names.extend(["run_js", "wait_js"])
+            tools = [
+                *(tools or []),
+                run_js_tool_descriptor(),
+                wait_js_tool_descriptor(),
+            ]
+        # askUser: opt-in structured user questions (W8). The host renders the
+        # question card and answers over the reverse channel
+        # (``ask_user.request``); the tool blocks until the reply. Registered
+        # on the router so dispatch works on both the host path (toolsViaHost)
+        # and the sidecar-local path — the handler is host-routed either way.
+        if params.get("askUser"):
+            from steerable_agent_runtime import make_ask_user_tool
+
+            ask_fn = make_ask_user_tool(HostAskUserHandler(self.server))
+            meta = ask_fn.__steerable_tool_meta__
+            # Registration is process-global while this block runs per
+            # request: the router rejects duplicates, so only the first
+            # askUser turn registers (the handler binds self.server, which
+            # is request-independent — re-registering would be identical).
+            if self.tools.get(meta["name"]) is None:
+                self.tools.register(
+                    ask_fn,
+                    name=meta["name"],
+                    mode=meta["mode"],
+                    description=meta["description"],
+                    schema=meta["schema"],
+                    require_consent=meta["require_consent"],
+                    concurrency_safe=meta["concurrency_safe"],
+                    exposure=meta["exposure"],
+                )
+            local_names.append(meta["name"])
+            tools = [
+                *(tools or []),
+                {
+                    "type": "function",
+                    "function": {
+                        "name": meta["name"],
+                        "description": meta["description"],
+                        "parameters": meta["schema"],
+                    },
+                },
+            ]
+        if local_names:
+            from .run_code import RunCodeBoundExecutor
+
+            executor = RunCodeBoundExecutor(
+                executor, router=self.tools, local_names=local_names
+            )
+        # streamRawChunks: opt-in pre-digestion chunk forwarding. The loop's
+        # on_stream_chunk hook sees every raw LLMStreamChunk before UI-tag
+        # stripping and surrogate splitting turn it into display text — hosts
+        # running incremental renderers (streaming UI-tag parsers) need that
+        # stream; it rides stream.chunk under `rawChunk`, distinct from the
+        # digested delta/reasoningDelta. Default off: it costs one
+        # notification per chunk. (OpenAI-compat buffers tool arguments, so
+        # toolCallDelta arrives whole — no incremental argument fragments.)
+        if params.get("streamRawChunks"):
+            hooks = ChainHooks(hooks, RawChunkBridgeHooks(transport, stream_id))
+        loop = CoreLoop(
+            provider,
+            executor,
+            loop_config,
+            hooks=hooks,
+            # Wave 1 durable record: the continuous per-chat log. An
+            # explicit recordId (the fork path's fresh log) wins over the
+            # default chat_id-derived one.
+            history_store=self.storage,
+            record_id=params.get("recordId") or params.get("chatId"),
+        )
+        # Persist the run as it streams so the host can inspect it afterwards
+        # via trace.fetch (and so a future resume projection has the events).
+        recorder = TraceRecorder(self.storage, chat_id=params.get("chatId"))
+        self._coreloops[stream_id] = loop
+        self._exec_controls[stream_id] = exec_control
+        final_content_only = params.get("contentMode") == "final"
+        pending_content: list[str] = []
+        from .egress_ask import bind_turn_chat_id, reset_turn_chat_id
+
+        raw_chat_id = params.get("chatId")
+        chat_token = bind_turn_chat_id(raw_chat_id if isinstance(raw_chat_id, str) else None)
+        try:
+            async for event in recorder.tee(
+                loop.run(
+                    messages,
+                    tools=tools,
+                    chat_id=params.get("chatId"),
+                )
+            ):
+                if final_content_only:
+                    if event.kind == "llm_request":
+                        pending_content.clear()
+                    elif event.kind == "content_delta":
+                        pending_content.append(str(event.data.get("delta") or ""))
+                        continue
+                    elif event.kind == "tool_call_start":
+                        pending_content.clear()
+                    elif event.kind == "error":
+                        pending_content.clear()
+                    elif event.kind == "completion":
+                        if event.data.get("status") == "executing":
+                            pending_content.clear()
+                        elif pending_content:
+                            await transport.emit_notification(
+                                "stream.chunk",
+                                {
+                                    "streamId": stream_id,
+                                    "delta": "".join(pending_content),
+                                },
+                            )
+                            pending_content.clear()
+                await self._emit_loop_event(
+                    transport,
+                    stream_id,
+                    event,
+                    recorder.trace_id,
+                    model=params.get("model"),
+                    hooks=hooks,
+                )
+        except asyncio.CancelledError:
+            await transport.emit_notification(
+                "stream.done",
+                {
+                    "streamId": stream_id,
+                    "ok": False,
+                    "cancelled": True,
+                    "traceId": recorder.trace_id,
+                },
+            )
+        except Exception as exc:
+            logger.exception("coreloop chat stream %s failed", stream_id)
+            await transport.emit_notification(
+                "stream.error",
+                {
+                    "streamId": stream_id,
+                    "kind": exc.__class__.__name__,
+                    "message": str(exc),
+                    # Failed turns are exactly the traces worth keeping — let
+                    # the host persist them via trace.fetch.
+                    "traceId": recorder.trace_id,
+                },
+            )
+        finally:
+            reset_turn_chat_id(chat_token)
+            self._coreloops.pop(stream_id, None)
+            self._exec_controls.pop(stream_id, None)
+            for client in mcp_clients:
+                # Close every per-turn MCP client (completion, error, or
+                # cancel) so no transport outlives its stream.
+                await client.aclose()
+            if orchestration is not None:
+                # Wind down any children still running when the parent ends
+                # (completion, error, or cancel) — cooperative first. The
+                # delegation seam shares this pool when both are on, so this
+                # covers delegate children too.
+                await orchestration.shutdown()
+            elif subagent_executor is not None:
+                # Delegation-only turn: wind down the delegate pool.
+                await subagent_executor.shutdown()
+            await recorder.finalize()
+            self._streams.pop(stream_id, None)
+
+    def _emit_child_event(
+        self,
+        transport: StdioJsonRpcTransport,
+        stream_id: str,
+        kind: str,
+        data: dict[str, Any],
+    ) -> None:
+        """Forward a child-lifecycle event from the agent pool.
+
+        Fired by orchestration children and by delegate_subagent
+        delegations (both run on the pool). The pool's sink is synchronous
+        (it fires inside tool execution), so the notification is scheduled
+        fire-and-forget; ordering against the surrounding stream events is
+        not guaranteed, lineage ids are.
+        """
+        task = asyncio.ensure_future(
+            transport.emit_notification(
+                "agent.child", {"streamId": stream_id, "kind": kind, **data}
+            )
+        )
+        task.add_done_callback(
+            lambda t: (
+                t.exception()
+                and logger.warning("child event emit failed: %s", t.exception())
+            )
+        )
+
+    @staticmethod
+    async def _emit_loop_event(
+        transport: StdioJsonRpcTransport,
+        stream_id: str,
+        event: Any,
+        trace_id: str | None = None,
+        model: str | None = None,
+        hooks: Any | None = None,
+    ) -> None:
+        kind = event.kind
+        data = event.data
+        if kind == "content_delta":
+            await transport.emit_notification(
+                "stream.chunk", {"streamId": stream_id, "delta": data["delta"]}
+            )
+        elif kind == "reasoning_delta":
+            await transport.emit_notification(
+                "stream.chunk", {"streamId": stream_id, "reasoningDelta": data["delta"]}
+            )
+        elif kind == "stream_restart":
+            # The engine is re-issuing the request it was streaming, so what
+            # the host already appended belongs to a discarded attempt. The
+            # host drops it instead of appending the retry's text after it.
+            await transport.emit_notification(
+                "stream.chunk",
+                {
+                    "streamId": stream_id,
+                    "restart": {
+                        "reason": data.get("reason") or "retry",
+                        "round": data.get("round"),
+                        "attempt": data.get("attempt"),
+                    },
+                },
+            )
+        elif kind == "tool_call_start":
+            await transport.emit_notification(
+                "stream.chunk",
+                {
+                    "streamId": stream_id,
+                    "toolCall": {
+                        "id": data["id"],
+                        "name": data["name"],
+                        "arguments": data.get("arguments") or {},
+                    },
+                },
+            )
+        elif kind in ("tool_call_result", "tool_error"):
+            payload: dict[str, Any] = {
+                "id": data["id"],
+                "name": data["name"],
+                "success": data.get("success", False),
+            }
+            if "durationMs" in data:
+                payload["durationMs"] = data["durationMs"]
+            if "error" in data:
+                payload["error"] = data["error"]
+            if "resultPreview" in data:
+                payload["resultPreview"] = data["resultPreview"]
+            if "sandbox" in data:
+                # W4-2: per-exec sandbox marker for the host's tool card.
+                payload["sandbox"] = data["sandbox"]
+            if "approval" in data:
+                payload["approval"] = data["approval"]
+            # Older engines omit the top-level fields when a sibling already
+            # finished before a terminal tool. The preview still carries them.
+            if "sandbox" not in payload or "approval" not in payload:
+                lifted_sandbox, lifted_approval = _markers_from_result_preview(
+                    data.get("resultPreview")
+                )
+                if "sandbox" not in payload and lifted_sandbox is not None:
+                    payload["sandbox"] = lifted_sandbox
+                if "approval" not in payload and lifted_approval is not None:
+                    payload["approval"] = lifted_approval
+            await transport.emit_notification(
+                "stream.chunk", {"streamId": stream_id, "toolResult": payload}
+            )
+        elif kind in ("soft_timeout", "budget_exhausted"):
+            await transport.emit_notification(
+                "stream.chunk",
+                {"streamId": stream_id, "notice": {"kind": kind, **data}},
+            )
+        elif kind == "hook_action":
+            # Hook-driven control flow (compaction / retry / narration /
+            # tool_choice). TraceRecorder already persists it; forward as a
+            # notice so hosts can surface it live too.
+            await transport.emit_notification(
+                "stream.chunk",
+                {"streamId": stream_id, "notice": {"kind": "hook_action", **data}},
+            )
+        elif kind == "steer":
+            # The host already rendered the user's message; this confirms the
+            # loop consumed it into the transcript (vs. still queued).
+            await transport.emit_notification(
+                "stream.chunk",
+                {
+                    "streamId": stream_id,
+                    "notice": {"kind": "steer", "content": data.get("content", "")},
+                },
+            )
+        elif kind == "error":
+            await transport.emit_notification(
+                "stream.error",
+                {
+                    "streamId": stream_id,
+                    "kind": "LoopError",
+                    "message": data["message"],
+                    **({"traceId": trace_id} if trace_id else {}),
+                    # The envelope `kind` stays "LoopError" for compatibility;
+                    # the engine's own classification travels separately so the
+                    # host can pick user-facing copy by category instead of
+                    # matching on message text.
+                    **(
+                        {"errorKind": data.get("kind")}
+                        if data.get("kind")
+                        else {}
+                    ),
+                    **{
+                        field: data[field]
+                        for field in ("proxy", "attempts", "statusCode")
+                        if data.get(field) is not None
+                    },
+                },
+            )
+        elif kind == "completion" and data.get("status") == "executing":
+            # Per-round bookkeeping (think → act → observe). Hosts seal the
+            # live thinking segment here so the next LLM burst starts a new
+            # block instead of concatenating every round into one wall.
+            await transport.emit_notification(
+                "stream.chunk",
+                {
+                    "streamId": stream_id,
+                    "notice": {
+                        "kind": "round_end",
+                        "status": "executing",
+                        "round": data.get("round"),
+                    },
+                },
+            )
+        elif kind == "completion" and data.get("status") != "executing":
+            # W6-9: forward the run's accumulated billable usage, plus a cost
+            # estimate when the model is priced (None → key omitted, never a
+            # fabricated $0.00 for unpriced/local models).
+            #
+            # Wrap-up laundering: when a narration round was granted after the
+            # turn already hit a wall, this round's natural-language summary
+            # makes the loop report `completed` — but the task did not finish.
+            # Reporting the wall keeps the host honest: it surfaces failed
+            # turns to the user and lets auto-continue resume a
+            # `budget_exhausted` pass instead of silently stopping.
+            status = data["status"]
+            reason = data["reason"]
+            wall_status = _hook_wall_status(hooks)
+            if status == "completed" and wall_status is not None:
+                status = wall_status
+                reason = (
+                    f"{reason or 'wrapped up'} [wall={wall_status}; "
+                    "narration round answered, task not finished]"
+                )
+            done: dict[str, Any] = {
+                "streamId": stream_id,
+                "ok": status == "completed",
+                "status": status,
+                "reason": reason,
+                **({"traceId": trace_id} if trace_id else {}),
+            }
+            if status == "cancelled":
+                # Same terminal signal the hard-cancel path emits, so hosts
+                # handle cooperative and forced cancellation uniformly.
+                done["cancelled"] = True
+            usage = data.get("usage")
+            if isinstance(usage, dict):
+                done["usage"] = usage
+                cost = estimate_cost_usd(
+                    model,
+                    int(usage.get("promptTokens") or 0),
+                    int(usage.get("completionTokens") or 0),
+                )
+                if cost is not None:
+                    done["usage"] = {**usage, "costUsd": cost}
+            await transport.emit_notification("stream.done", done)
+
+    # ------------------------------------------------------------------
+    # Plumbing
+    # ------------------------------------------------------------------
+
+    def _emit_ready_marker(self, health: SidecarHealth) -> None:
+        if self.config.quiet_stderr:
+            return
+        payload = json.dumps(
+            health.model_dump(exclude_none=True), separators=(",", ":")
+        )
+        sys.stderr.write(f"{READY_PREFIX}{payload}\n")
+        sys.stderr.flush()
+
+    def _configure_logging(self) -> None:
+        logging.basicConfig(
+            level=self.config.log_level,
+            format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+            stream=sys.stderr,
+        )
+
+    def _install_signal_handlers(self) -> None:
+        loop = asyncio.get_running_loop()
+        try:
+            import signal
+
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                loop.add_signal_handler(sig, lambda: self._shutdown_requested.set())
+        except (NotImplementedError, RuntimeError):
+            # Windows event-loop policies that lack add_signal_handler.
+            pass
+
+    @staticmethod
+    async def _connect_stdio() -> tuple[asyncio.StreamReader, Any]:
+        if sys.platform == "win32":
+            # ProactorEventLoop 的 connect_read/write_pipe 要求 IOCP 可关联
+            # 句柄；被 Node/Electron spawn 的子进程继承的是普通匿名管道句柄
+            # （控制台句柄亦然），注册即 OSError [WinError 6]，且读侧可能在
+            # connect 成功后才在回调里异步崩。SelectorEventLoop 在 Windows 上
+            # 根本不支持管道，因此走线程泵兜底（见 _connect_stdio_threaded）。
+            return _connect_stdio_threaded()
+        loop = asyncio.get_running_loop()
+        reader = asyncio.StreamReader(limit=STDIO_STREAM_LIMIT)
+        protocol = asyncio.StreamReaderProtocol(reader)
+        await loop.connect_read_pipe(lambda: protocol, sys.stdin)
+        transport, _ = await loop.connect_write_pipe(
+            asyncio.streams.FlowControlMixin, sys.stdout
+        )
+        writer = asyncio.StreamWriter(transport, protocol, reader, loop)
+        return reader, writer
+
+    @staticmethod
+    async def _maybe_drain(writer: Any) -> None:
+        drain = getattr(writer, "drain", None)
+        if drain is None:
+            return
+        result = drain()
+        if asyncio.iscoroutine(result):
+            await result
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class _ThreadedStdoutWriter:
+    """Duck-typed stdout writer for the Windows stdio fallback.
+
+    Matches the surface the JSON-RPC server/transport actually use:
+    synchronous ``write(bytes)`` plus optional ``drain()`` / ``close()`` /
+    ``is_closing()``. A lock keeps frames ordered when the event loop and a
+    reverse-call path write concurrently; every frame is flushed immediately
+    (line-delimited JSON-RPC). A blocking write backpressures the event loop
+    directly — acceptable here because the host always drains stdout.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._closing = False
+
+    def write(self, data: bytes) -> int:
+        with self._lock:
+            if self._closing:
+                raise RuntimeError("stdio writer is closed")
+            out = sys.stdout.buffer
+            written = out.write(data)
+            out.flush()
+            return written if written is not None else len(data)
+
+    async def drain(self) -> None:
+        return None
+
+    def close(self) -> None:
+        with self._lock:
+            self._closing = True
+            try:
+                sys.stdout.buffer.flush()
+            except Exception:
+                pass
+
+    def is_closing(self) -> bool:
+        return self._closing
+
+
+def _connect_stdio_threaded() -> tuple[asyncio.StreamReader, Any]:
+    """Windows stdio transport: blocking stdin reader thread + sync writer.
+
+    A daemon thread runs blocking ``readline()`` on stdin and feeds a
+    ``StreamReader`` via ``call_soon_threadsafe``; EOF (parent closed the
+    pipe) surfaces as ``feed_eof`` so the serve loop shuts down normally.
+    No flow control on the read side — the host sends one request frame at a
+    time, so the buffer cannot grow unboundedly in practice.
+    """
+    loop = asyncio.get_running_loop()
+    reader: asyncio.StreamReader = asyncio.StreamReader(limit=STDIO_STREAM_LIMIT)
+
+    def _pump_stdin() -> None:
+        # 用裸 fd 读而非 sys.stdin.buffer：解释器退出时会关闭带锁的
+        # BufferedReader，守护线程若正阻塞在它的锁上，finalization 会抛
+        # "_enter_buffered_busy" fatal error。os.read 不持有该锁；fd 被
+        # 关闭后 read 返回错误，按 EOF 处理即可。StreamReader 自行重组行。
+        try:
+            while True:
+                chunk = os.read(0, 65536)
+                if not chunk:
+                    loop.call_soon_threadsafe(reader.feed_eof)
+                    return
+                loop.call_soon_threadsafe(reader.feed_data, chunk)
+        except Exception:
+            # stdin broken/closed: surface as EOF so the serve loop exits.
+            try:
+                loop.call_soon_threadsafe(reader.feed_eof)
+            except RuntimeError:
+                pass  # event loop already closed
+
+    threading.Thread(
+        target=_pump_stdin, name="sidecar-stdin-pump", daemon=True
+    ).start()
+    return reader, _ThreadedStdoutWriter()
+
+
+def _markers_from_result_preview(preview: Any) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    """Sandbox and approval objects embedded in a tool-result preview.
+
+    The loop event usually lifts these itself. When it does not, they remain
+    under ``data._sandbox`` and ``data._approval`` in the preview JSON. A
+    published loop also cuts that preview at 300 characters, so a marker
+    past the cut is gone; one that still fits is read without parsing the
+    rest of the truncated JSON.
+    """
+    if not isinstance(preview, str) or not preview.startswith("{"):
+        return None, None
+    try:
+        parsed = json.loads(preview)
+    except json.JSONDecodeError:
+        return (
+            _object_after_key(preview, "_sandbox"),
+            _object_after_key(preview, "_approval"),
+        )
+    if not isinstance(parsed, dict):
+        return None, None
+    body = parsed.get("data")
+    if not isinstance(body, dict):
+        return None, None
+    sandbox = body.get("_sandbox")
+    approval = body.get("_approval")
+    return (
+        sandbox if isinstance(sandbox, dict) else None,
+        approval if isinstance(approval, dict) else None,
+    )
+
+
+def _object_after_key(text: str, key: str) -> dict[str, Any] | None:
+    needle = f'"{key}"'
+    decoder = json.JSONDecoder()
+    start = 0
+    while True:
+        found = text.find(needle, start)
+        if found < 0:
+            return None
+        colon = text.find(":", found + len(needle))
+        if colon < 0:
+            return None
+        index = colon + 1
+        while index < len(text) and text[index] in " \t\r\n":
+            index += 1
+        try:
+            value, _end = decoder.raw_decode(text, index)
+        except json.JSONDecodeError:
+            start = found + len(needle)
+            continue
+        if isinstance(value, dict):
+            return value
+        start = found + len(needle)
+
+
+def _approval_prompt_chat_id(params: dict[str, Any]) -> str | None:
+    """Chat the approval card belongs to.
+
+    A background task streams under ``task:<id>`` while the user stays in
+    the parent conversation (``toolContext.chatId``). Otherwise the stream
+    ``chatId`` is that conversation.
+    """
+    tool_context = params.get("toolContext")
+    if isinstance(tool_context, dict):
+        raw = tool_context.get("chatId")
+        if isinstance(raw, str) and raw:
+            return raw
+    raw = params.get("chatId")
+    if isinstance(raw, str) and raw:
+        return raw
+    return None
+
+
+def _require_params(params: Any) -> dict[str, Any]:
+    if not isinstance(params, dict):
+        raise JsonRpcError(
+            "params must be an object", code=-32602, kind="invalid_params"
+        )
+    return params
+
+
+def _iso_now() -> str:
+    from datetime import datetime, timezone
+
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _new_session_id() -> str:
+    return f"sess_{uuid.uuid4().hex}"
+
+
+def _new_call_id() -> str:
+    return f"call_{uuid.uuid4().hex}"
+
+
+def _new_stream_id() -> str:
+    return f"str_{uuid.uuid4().hex}"
+
+
+def _coerce_part(item: Any) -> ContentPart:
+    """Coerce one wire ``ContentPart`` (spec/chat/ContentPart.schema.json).
+
+    The wire part is authoritative when ``parts`` is present on a
+    ChatMessage; ``content`` is then just its text projection.
+    """
+    if not isinstance(item, dict):
+        raise JsonRpcError(
+            "each part must be an object", code=-32602, kind="invalid_params"
+        )
+    kind = item.get("type")
+    if kind == "text":
+        return TextPart(str(item.get("text") or ""))
+    if kind == "image":
+        url = item.get("url")
+        if url:
+            return ImagePart.from_url(
+                str(url), media_type=str(item.get("mediaType") or "image/png")
+            )
+        data = item.get("data")
+        if data:
+            return ImagePart.from_base64(
+                str(data), media_type=str(item.get("mediaType") or "image/png")
+            )
+        raise JsonRpcError(
+            "image part needs url or data", code=-32602, kind="invalid_params"
+        )
+    raise JsonRpcError(
+        f"invalid part type: {kind!r}", code=-32602, kind="invalid_params"
+    )
+
+
+def _coerce_messages(items: Any) -> list[LLMMessage]:
+    if not isinstance(items, list):
+        raise JsonRpcError(
+            "messages must be a list", code=-32602, kind="invalid_params"
+        )
+    out: list[LLMMessage] = []
+    for entry in items:
+        if not isinstance(entry, dict):
+            raise JsonRpcError(
+                "each message must be an object", code=-32602, kind="invalid_params"
+            )
+        role = entry.get("role")
+        if role not in {"system", "user", "assistant", "tool"}:
+            raise JsonRpcError(
+                f"invalid role: {role!r}", code=-32602, kind="invalid_params"
+            )
+        # Assistant 轮的工具调用/推理回传：host 历史里的 assistant 消息必须
+        # 把 toolCalls 一起带回来，否则下一轮 role:'tool' 被 OpenAI 严格协
+        # 议判为孤儿（400）；thinking 模型（DeepSeek）还要求 reasoning 回传
+        # （字段名由 provider compat 的 reasoningEchoField 决定）。
+        tool_calls = _coerce_tool_calls(entry.get("toolCalls"))
+        reasoning = entry.get("reasoning")
+        if reasoning is None:
+            reasoning = entry.get("reasoningContent")
+        if reasoning is not None and not isinstance(reasoning, str):
+            raise JsonRpcError(
+                "reasoning must be a string", code=-32602, kind="invalid_params"
+            )
+        reasoning_details = entry.get("reasoningDetails")
+        if reasoning_details is not None and not isinstance(reasoning_details, list):
+            raise JsonRpcError(
+                "reasoningDetails must be a list", code=-32602, kind="invalid_params"
+            )
+        wire_parts = entry.get("parts")
+        if wire_parts is not None:
+            if not isinstance(wire_parts, list):
+                raise JsonRpcError(
+                    "parts must be a list", code=-32602, kind="invalid_params"
+                )
+            out.append(
+                LLMMessage(
+                    role=role,  # type: ignore[arg-type]
+                    content=[_coerce_part(p) for p in wire_parts],
+                    name=entry.get("name"),
+                    tool_call_id=entry.get("toolCallId"),
+                    tool_calls=tool_calls,
+                    reasoning=reasoning,
+                    reasoning_details=reasoning_details,
+                )
+            )
+            continue
+        out.append(
+            LLMMessage.text_of(
+                role,  # type: ignore[arg-type]
+                str(entry.get("content", "")),
+                name=entry.get("name"),
+                tool_call_id=entry.get("toolCallId"),
+                tool_calls=tool_calls,
+                reasoning=reasoning,
+                reasoning_details=reasoning_details,
+            )
+        )
+    return out
+
+
+def _coerce_tool_calls(items: Any) -> list[ToolCall] | None:
+    """Validate the host-echoed assistant ``toolCalls`` array."""
+    if items is None:
+        return None
+    if not isinstance(items, list):
+        raise JsonRpcError(
+            "toolCalls must be a list", code=-32602, kind="invalid_params"
+        )
+    out: list[ToolCall] = []
+    for item in items:
+        if not isinstance(item, dict):
+            raise JsonRpcError(
+                "each toolCalls entry must be an object",
+                code=-32602,
+                kind="invalid_params",
+            )
+        arguments = item.get("arguments")
+        if not isinstance(arguments, dict):
+            arguments = {}
+        out.append(
+            ToolCall(
+                id=str(item.get("id") or ""),
+                name=str(item.get("name") or ""),
+                arguments=arguments,
+            )
+        )
+    return out or None
+
+
+def _model_tool(tool: Any) -> Any:
+    """Drop approval metadata before the provider sees the tool list.
+
+    ``mode`` and ``approvalCategory`` are host-to-sidecar fields. Provider
+    APIs reject unknown tool keys.
+    """
+    if not isinstance(tool, dict):
+        return tool
+    cleaned = {
+        key: value
+        for key, value in tool.items()
+        if key not in ("mode", "approvalCategory")
+    }
+    function = cleaned.get("function")
+    if isinstance(function, dict):
+        cleaned["function"] = {
+            key: value
+            for key, value in function.items()
+            if key not in ("mode", "approvalCategory")
+        }
+    return cleaned
+
+
+def _build_provider_kwargs(params: dict[str, Any]) -> dict[str, Any]:
+    kwargs: dict[str, Any] = {}
+    if (tools := params.get("tools")) is not None:
+        kwargs["tools"] = (
+            [_model_tool(tool) for tool in tools] if isinstance(tools, list) else tools
+        )
+    if (temp := params.get("temperature")) is not None:
+        kwargs["temperature"] = float(temp)
+    if (max_tokens := params.get("maxTokens")) is not None:
+        kwargs["max_tokens"] = int(max_tokens)
+    extra = params.get("providerOptions") or {}
+    if isinstance(extra, dict):
+        kwargs.update(extra)
+    return kwargs
+
+
+def _use_coreloop(params: dict[str, Any]) -> bool:
+    """Flag resolution for the CoreLoop chat path: per-request
+    ``useCoreLoop`` wins; otherwise the ``STEERABLE_SIDECAR_CORELOOP`` env
+    var; default off (legacy direct-stream path)."""
+
+    flag = params.get("useCoreLoop")
+    if flag is not None:
+        return bool(flag)
+    return os.environ.get("STEERABLE_SIDECAR_CORELOOP", "").strip().lower() in {
+        "1",
+        "true",
+        "yes",
+    }
+
+
+def _last_message_content(
+    messages: list[LLMMessage], role: str, *, tail: int | None = None
+) -> str:
+    """Content of the last message with ``role`` (for anti-hallucination
+    routing/judging context). ``tail`` truncates to the trailing N chars."""
+
+    for message in reversed(messages):
+        if message.role == role and message.content_text:
+            content = message.content_text
+            return content[-tail:] if tail else content
+    return ""
+
+
+def _hook_wall_status(hooks: Any | None) -> str | None:
+    """Pre-wrap-up terminal status a ``before_completion`` hook swallowed.
+
+    Optional capability, probed with ``getattr`` so any hooks assembly —
+    a bare ``NoopHooks``, a product chain, an embedder factory — answers
+    None without implementing it. See ``LoopHooks.wall_status``.
+    """
+
+    probe = getattr(hooks, "wall_status", None)
+    if not callable(probe):
+        return None
+    try:
+        status = probe()
+    except Exception:  # noqa: BLE001 — reporting must never break the stream
+        logger.exception("hook_wall_status_failed")
+        return None
+    return status if isinstance(status, str) and status else None
+
+
+#: ``trace.fetch`` event cap. ~50k events ≈ 12 MB of JSON — comfortably inside
+#: the host's fetch deadline and MySQL's default ``max_allowed_packet`` (64 MB),
+#: while still covering all but the longest runs whole. Override per call with
+#: ``maxEvents`` or globally with ``STEERABLE_TRACE_FETCH_MAX_EVENTS`` (``0``
+#: disables the cap and restores the old unbounded fetch).
+_DEFAULT_TRACE_FETCH_MAX_EVENTS = 50_000
+
+
+def _trace_fetch_max_events(params: dict[str, Any]) -> int | None:
+    """Resolve the ``trace.fetch`` event cap; None means unbounded."""
+
+    raw: Any = params.get("maxEvents")
+    if raw is None:
+        raw = os.environ.get("STEERABLE_TRACE_FETCH_MAX_EVENTS")
+    if raw is None:
+        return _DEFAULT_TRACE_FETCH_MAX_EVENTS
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        return _DEFAULT_TRACE_FETCH_MAX_EVENTS
+    return None if value <= 0 else value
+
+
+def _summarizer_for(provider: Any) -> Any | None:
+    """Wire the turn's provider as the compaction summarizer.
+
+    The desktop rolling summary made a genuine model call; the deterministic
+    excerpt fallback would be a quality regression now that the framework is
+    the sole owner of cross-turn compaction. Reusing the turn provider for the
+    one-off ``complete`` mirrors how AntiHallucinationHooks already reuses it
+    for the grounding judge. Opt out with ``STEERABLE_SIDECAR_SUMMARIZER=0``
+    (cost-sensitive deployments keep the deterministic excerpts).
+    """
+    flag = os.environ.get("STEERABLE_SIDECAR_SUMMARIZER", "1").strip().lower()
+    if flag in {"0", "false", "no", "off"}:
+        return None
+    return provider
+
+
+def _assemble_default_harness(
+    params: dict[str, Any], summarizer: Any | None = None
+) -> Any:
+    """Assemble the bundled ``default.harness.yaml`` into the loop's seams
+    (W1.2.4: the declarative spec is the single source of truth for the
+    default harness — this function only resolves the sidecar's runtime
+    parameters and deployment env knobs).
+
+    Returns the full ``AssembledHarness``: callers take ``.hooks`` for the
+    hook chain and drive the tools dimension against their tool surface —
+    ``wire_tools(router)`` where an in-process router exists (headless,
+    ACP), ``select_tools`` everywhere. Router-backed tools strategies
+    (progressive) raise on selection without wiring, so a path with no
+    router must not select them.
+    """
+    from dataclasses import replace
+
+    from steerable_agent_runtime.harness_spec import assemble_harness
+    from steerable_agent_runtime.tokens import resolve_context_window
+
+    # Explicit maxContextTokens wins; otherwise the model's known context
+    # window (a fixed 60k against a 131k model compacted far earlier than the
+    # provider required — the dogfood 22-compacts/5-traces pathology).
+    max_ctx = resolve_context_window(
+        params.get("model"),
+        explicit=int(params.get("maxContextTokens") or 0) or None,
+        provider=params.get("provider"),
+        base_url=params.get("baseUrl"),
+    )
+    spec = _default_harness_spec()
+    # STEERABLE_SIDECAR_SPILL=0 is deployment policy, not harness strategy:
+    # it drops the spill dimension before assembly rather than wrapping hooks.
+    flag = os.environ.get("STEERABLE_SIDECAR_SPILL", "1").strip().lower()
+    if flag in {"0", "false", "no", "off"}:
+        spec = replace(spec, context=[c for c in spec.context if c.impl != "spill"])
+    # STEERABLE_RETRY_* is the same kind of knob: the desktop cadence
+    # (3×200ms) dies instantly on Harbor's OpenRouter 429s, so eval jobs
+    # retune the spec's simple retry without editing the bundled YAML.
+    retry_params = _retry_params_from_env()
+    if retry_params:
+        spec = replace(
+            spec,
+            retry=[
+                replace(c, params={**c.params, **retry_params})
+                if c.impl == "simple"
+                else c
+                for c in spec.retry
+            ],
+        )
+    model = params.get("model")
+    # P3: the knob set is resolved explicitly per model/window — no hidden
+    # if/else at the assembly site. (Desktop 60k–131k keeps 2 tool results;
+    # GLM 1M Harbor traces need 16 or compile/train tails fold away.)
+    policy = resolve_compaction_policy(model=model, max_context_tokens=max_ctx)
+    # Spill budgets branch on the same window size class as the compaction
+    # policy; the threshold lives in compaction_policy, not here.
+    large = is_large_window(max_ctx)
+    return assemble_harness(
+        spec,
+        provider=summarizer,
+        runtime_params={
+            "pressure_compaction": {
+                "max_context_tokens": max_ctx,
+                "model": model,
+                **policy.as_params(),
+            },
+            "informed_backtrack": {"max_context_tokens": max_ctx, "model": model},
+            # Desktop 16k inline. GLM 1M Harbor keeps full 100k bash clips
+            # until compaction; 2k previews hid compile/train endings.
+            "spill": {
+                "directory": _spill_directory(),
+                "max_inline_bytes": 100_000 if large else 16_000,
+                "preview_bytes": 8_000 if large else 2_000,
+            },
+        },
+    )
+
+
+def _default_loop_hooks(
+    params: dict[str, Any], summarizer: Any | None = None
+) -> LoopHooks:
+    """The default harness's hook chain (assembly: `_assemble_default_harness`).
+
+    Slice order is the spec's: pressure compaction's ``pre_step`` first,
+    spill's ``post_tool_result``, then overflow backtrack ahead of
+    taxonomy-routed backoff on ``on_request_error``.
+    """
+    return _assemble_default_harness(params, summarizer).hooks
+
+
+def _retry_params_from_env() -> dict[str, int]:
+    """STEERABLE_RETRY_* deployment overrides for the spec's simple retry.
+
+    Desktop default is 3×200ms. Harbor OpenRouter 429s need minutes.
+
+    The ``TRANSPORT_`` prefixed names configure the connection-failure policy
+    (5 attempts, 1s base, 8s cap, 60s deadline) separately from the shared
+    one, because a proxy or a flaky link needs waits an API error does not.
+    """
+    params: dict[str, int] = {}
+    for env_name, param in (
+        ("STEERABLE_RETRY_MAX_ATTEMPTS", "max_attempts"),
+        ("STEERABLE_RETRY_BASE_DELAY_MS", "base_delay_ms"),
+        ("STEERABLE_RETRY_MAX_DELAY_MS", "max_delay_ms"),
+        ("STEERABLE_RETRY_TRANSPORT_ATTEMPTS", "transport_max_attempts"),
+        ("STEERABLE_RETRY_TRANSPORT_BASE_DELAY_MS", "transport_base_delay_ms"),
+        ("STEERABLE_RETRY_TRANSPORT_MAX_DELAY_MS", "transport_max_delay_ms"),
+        ("STEERABLE_RETRY_TRANSPORT_DEADLINE_MS", "transport_deadline_ms"),
+    ):
+        raw = os.environ.get(env_name, "").strip()
+        if not raw:
+            continue
+        try:
+            value = int(raw)
+        except ValueError:
+            continue
+        if value > 0:
+            params[param] = value
+    return params
+
+
+@lru_cache(maxsize=1)
+def _default_harness_spec():
+    """Load the bundled default spec once per process (every chat turn reads
+    it for loop limits and tool selection; the parse is not free).
+
+    The cache lives on this function, not on a per-call inner closure — a
+    closure redefined each call carries a fresh empty cache and re-parses.
+    """
+    from steerable_agent_runtime.harness_spec import load_harness_spec
+
+    return load_harness_spec(_DEFAULT_HARNESS_SPEC_PATH)
+
+
+def _spill_directory() -> str:
+    """Stable per-host spill dir (findable across a session), overridable
+    with STEERABLE_SPILL_DIR."""
+    import tempfile
+
+    override = os.environ.get("STEERABLE_SPILL_DIR")
+    if override:
+        return override
+    try:
+        base = tempfile.gettempdir()
+    except FileNotFoundError:
+        # 受限沙箱（如 Windows restricted-token 只放行声明过的 writable
+        # root）下系统临时目录不可写，gettempdir() 探测失败。回落到
+        # ~/.steerable——宿主沙箱策略始终放行的根。
+        base = os.path.join(Path.home(), ".steerable")
+    return os.path.join(base, "steerable-spill")
+
+
+def _build_loop_config(params: dict[str, Any]) -> LoopConfig:
+    # Loop-limit precedence (W3.4.2.4): explicit request param > the bundled
+    # default spec's `loop:` section > the baseline. `resolve_loop_limits` is
+    # that one rule, shared with headless and ACP.
+    resolved = resolve_loop_limits(
+        _default_harness_spec().loop,
+        max_rounds=(
+            int(params["maxRounds"]) if params.get("maxRounds") is not None else None
+        ),
+        max_tool_errors=(
+            int(params["maxToolErrors"])
+            if params.get("maxToolErrors") is not None
+            else None
+        ),
+    )
+    max_rounds = resolved.max_rounds
+    max_tool_errors = resolved.max_tool_errors
+    budget = None
+    if (budget_tokens := params.get("budgetTokens")) is not None:
+        budget = BudgetLimit(
+            max_tokens=int(budget_tokens),
+            max_steps=max_rounds,
+            max_tool_calls=int(params.get("budgetMaxToolCalls", 10_000)),
+        )
+    else:
+        # Only the token axis of BudgetLimit is consumed by the loop
+        # (steps/tool_calls stay inert). The token axis is cumulative over
+        # the run while a context window is
+        # a per-request size, so a flat multiple of the window caps the round
+        # count instead of the spend: an agentic turn re-sends its prompt
+        # every round, and even a fully cache-hit window still bills
+        # ``cached_token_weight × window``. Scaling with an explicit round
+        # cap keeps that cap primary and leaves the token axis a backstop.
+        # The default cap is unlimited — a derived token budget would just
+        # re-introduce the wall — so an uncapped run has no token budget
+        # unless the caller passed ``budgetTokens``.
+        from steerable_agent_runtime.tokens import resolve_context_window
+
+        if max_rounds >= UNLIMITED_LOOP_LIMIT:
+            budget = None
+        else:
+            window = resolve_context_window(
+                params.get("model"),
+                explicit=int(params.get("maxContextTokens") or 0) or None,
+                provider=params.get("provider"),
+                base_url=params.get("baseUrl"),
+            )
+            budget = BudgetLimit(
+                max_tokens=max(
+                    2 * window,
+                    math.floor(max_rounds * window * DEFAULT_CACHED_TOKEN_WEIGHT),
+                ),
+                max_steps=max_rounds,
+                max_tool_calls=10_000,
+            )
+    return LoopConfig(
+        max_rounds=max_rounds,
+        max_tool_errors=max_tool_errors,
+        budget=budget,
+        tool_dedup=resolved.tool_dedup,
+        temperature=(
+            float(params["temperature"])
+            if params.get("temperature") is not None
+            else None
+        ),
+        max_tokens=int(params["maxTokens"])
+        if params.get("maxTokens") is not None
+        else None,
+        soft_timeout_ms=(
+            int(params["softTimeoutMs"])
+            if params.get("softTimeoutMs") is not None
+            else None
+        ),
+        # Per-tool backstop against hung executors (in-process or remote).
+        # LoopConfig carries the default; the param only overrides.
+        **(
+            {"tool_timeout_ms": int(params["toolTimeoutMs"])}
+            if params.get("toolTimeoutMs") is not None
+            else {}
+        ),
+        # W2.8.1: mid-turn steer policy — "boundary" (default) drains at the
+        # next round boundary; "interrupt" cancels the in-flight tool phase
+        # so the steer reaches the model at the very next request.
+        **(
+            {"steer_mode": params["steerMode"]}
+            if params.get("steerMode") in ("boundary", "interrupt")
+            else {}
+        ),
+    )
+
+
+_shared_calibration: Any | None = None
+_shared_calibration_path: str | None = None
+
+
+def _get_shared_calibration() -> Any:
+    """Process-level UsageCalibration singleton.
+
+    The provider factory runs per chat-stream request; a per-request
+    calibration would accumulate samples only within one turn and rarely
+    reach the persist threshold. A process-shared singleton accumulates
+    across turns and is flushed periodically (persist_every) and on
+    shutdown.
+    """
+    global _shared_calibration, _shared_calibration_path
+    if _shared_calibration is None:
+        from steerable_agent_runtime import UsageCalibration
+
+        path = os.environ.get("STEERABLE_TOKEN_CALIBRATION_PATH") or os.path.join(
+            os.path.expanduser("~"), ".steerable", "token-calibration.json"
+        )
+        _shared_calibration = UsageCalibration.load(path)
+        _shared_calibration.register_factors()
+        _shared_calibration_path = path
+    return _shared_calibration
+
+
+def _flush_shared_calibration() -> None:
+    if _shared_calibration is not None and _shared_calibration_path is not None:
+        try:
+            _shared_calibration.save(_shared_calibration_path)
+        except OSError:
+            pass  # shutdown flush is best-effort; periodic flushes already ran
+
+
+def _wrap_with_calibration(provider: LLMProvider) -> LLMProvider:
+    """Wrap the provider so every request records estimated-vs-observed usage.
+
+    Default-on: dogfooding should accumulate calibration samples with zero
+    setup. Disable with ``STEERABLE_TOKEN_CALIBRATION=0``; override the
+    aggregates file with ``STEERABLE_TOKEN_CALIBRATION_PATH`` (default
+    ``~/.steerable/token-calibration.json``). Previously accumulated factors
+    are registered into MODEL_TOKEN_FACTORS on load, so a restarted sidecar
+    resumes with its measured corrections.
+    """
+    flag = os.environ.get("STEERABLE_TOKEN_CALIBRATION", "1").strip().lower()
+    if flag in {"0", "false", "no", "off"}:
+        return provider
+    from steerable_agent_runtime import CalibratingProvider
+
+    return CalibratingProvider(
+        provider,
+        _get_shared_calibration(),
+        persist_path=_shared_calibration_path,
+    )
+
+
+def _wrap_with_recording(provider: LLMProvider) -> LLMProvider:
+    """Wrap the provider so every outbound request lands in a JSONL record.
+
+    Opt-in via ``STEERABLE_REQUEST_RECORD_PATH=<file.jsonl>`` — the E2E
+    harness and dogfood runs set it to assert the prompt invariants
+    (``assert_stable_prefix`` / ``assert_bounded_items``) on real traffic.
+    Off by default: the record carries full prompt contents.
+    """
+
+    path = os.environ.get("STEERABLE_REQUEST_RECORD_PATH", "").strip()
+    if not path:
+        return provider
+    from steerable_agent_runtime import JsonlRequestSink, RecordingProvider
+
+    return RecordingProvider(provider, JsonlRequestSink(path))
+
+
+def _catalog_base_url(provider_kind: str) -> str | None:
+    """The catalog's api base URL for a first-party provider kind."""
+    from steerable_agent_runtime.model_resolve import provider_endpoint
+
+    endpoint = provider_endpoint(provider_kind)
+    return endpoint.api_base_url if endpoint else None
+
+
+#: The bundled default harness spec (W1.2.4): the built-in chain as data.
+#: The JSON copy is the runtime-loaded one — PyYAML is deliberately not a
+#: runtime dependency, and JSON is a YAML subset the loader parses with
+#: stdlib json. Resolved inside the installed steerable_agent_runtime
+#: package (shipped as package data) so pip-installed venvs — Harbor trial
+#: containers — find it; the repo layout lands on the same file through
+#: the editable install. default.harness.yaml stays the commented source;
+#: test_harness_spec pins the two in sync.
+_DEFAULT_HARNESS_SPEC_PATH = (
+    Path(importlib.util.find_spec("steerable_agent_runtime").origin).resolve().parent
+    / "default.harness.json"
+)
+
+
+def _resolve_preset_param(
+    params: dict[str, Any],
+) -> ProviderPreset | Literal["auto", "off"]:
+    """Map the host's ``presets`` chat param onto the provider's ``preset`` field.
+
+    Absent or ``{"enabled": true}`` → ``"auto"`` (registry match on
+    base-URL+model); ``{"enabled": false}`` → ``"off"``; ``{"override": {...}}``
+    pins an explicit preset (parsed fail-loud by ``ProviderPreset.from_dict``).
+    A malformed payload raises ``ValueError`` rather than silently falling
+    back to auto — the host made a choice, it must apply or fail.
+    """
+    from steerable_agent_runtime.llm import ProviderPreset
+
+    raw = params.get("presets")
+    if raw is None:
+        return "auto"
+    if not isinstance(raw, dict):
+        raise TypeError("presets param must be an object")
+    override = raw.get("override")
+    if override is not None:
+        if not isinstance(override, dict):
+            raise TypeError("presets.override must be an object")
+        return ProviderPreset.from_dict(override)
+    return "auto" if raw.get("enabled", True) else "off"
+
+
+def default_llm_provider_factory(params: dict[str, Any]) -> LLMProvider:
+    """Construct an LLMProvider from a chat-stream request payload.
+
+    Embedders can override this by passing ``llm_provider_factory=`` to
+    ``Sidecar(...)`` — useful for tests or for sites that want to enforce a
+    single configured provider.
+    """
+
+    provider_kind = (params.get("provider") or "").strip().lower()
+    model = params.get("model")
+    if not model:
+        raise ValueError("model is required")
+    base_url = params.get("baseUrl") or params.get("base_url")
+    api_key = params.get("apiKey") or params.get("api_key") or ""
+
+    # The host model picker's per-request reasoning effort. Parsed once for
+    # every provider family and validated at construction so an
+    # unsupportable level is an RPC error here, not a mid-stream failure
+    # (EVALS 2.5.22 fail-loud). The wire path re-validates with the
+    # branch-resolved base_url.
+    reasoning_effort = params.get("reasoningEffort") or params.get(
+        "reasoning_effort"
+    )
+    if reasoning_effort:
+        from steerable_agent_runtime import clamp_reasoning_effort
+
+        clamp_reasoning_effort(
+            str(model),
+            str(reasoning_effort),
+            provider=provider_kind or None,
+            base_url=base_url,
+            strict=True,
+        )
+
+    # The host asked this one endpoint to skip the proxy (see
+    # `ProviderConfig.force_direct`). Per request, not per process: a product
+    # may send one model service direct and leave the rest proxied.
+    direct_connection = bool(params.get("directConnection"))
+
+    if provider_kind in {"openai", "openai_compat", "openai-compatible", "ollama"}:
+        from steerable_agent_runtime.llm import (
+            OpenAICompatFlags,
+            OpenAICompatProvider,
+            compat_for_base_url,
+        )
+
+        if provider_kind == "ollama":
+            # Ollama's OpenAI-compatible API lives under /v1. Callers that
+            # configure the native daemon root (e.g. the desktop app stores
+            # http://127.0.0.1:11434 for its native /api/chat client) would
+            # otherwise 404 on /chat/completions.
+            base_url = (base_url or "http://127.0.0.1:11434").rstrip("/")
+            if not base_url.endswith("/v1"):
+                base_url = f"{base_url}/v1"
+
+        # W5.3.1: a catalogued provider name supplies its own endpoint —
+        # ``provider: deepseek`` needs no hand-written base_url. Unknown
+        # kinds (openai_compat shims, ollama) keep the OpenAI default.
+        resolved_base_url = (
+            base_url or _catalog_base_url(provider_kind) or "https://api.openai.com/v1"
+        )
+        # Vendor divergences arrive as data: an explicit ``compat`` payload
+        # wins; otherwise auto-detect from the base-URL host (pi-style).
+        compat_param = params.get("compat")
+        compat = (
+            OpenAICompatFlags.from_dict(compat_param)
+            if isinstance(compat_param, dict)
+            else compat_for_base_url(resolved_base_url)
+        )
+        return _wrap_with_recording(
+            _wrap_with_calibration(
+                OpenAICompatProvider(
+                    name=provider_kind or "openai_compat",
+                    base_url=resolved_base_url,
+                    api_key=api_key,
+                    model=str(model),
+                    compat=compat,
+                    preset=_resolve_preset_param(params),
+                    reasoning_effort=(
+                        str(reasoning_effort) if reasoning_effort else None
+                    ),
+                    force_direct=direct_connection,
+                )
+            )
+        )
+    if provider_kind in {"anthropic", "claude"}:
+        from steerable_agent_runtime.llm import AnthropicProvider
+
+        return _wrap_with_recording(
+            _wrap_with_calibration(
+                _wrap_with_cache_control(
+                    AnthropicProvider(
+                        name=provider_kind or "anthropic",
+                        api_key=api_key,
+                        model=str(model),
+                        base_url=base_url,
+                    )
+                )
+            )
+        )
+    if provider_kind in {"openai-responses", "openai_responses", "responses", "xai"}:
+        from steerable_agent_runtime.llm import OpenAIResponsesProvider
+
+        resolved_base_url = (
+            base_url
+            or ("https://api.x.ai/v1" if provider_kind == "xai" else None)
+            or "https://api.openai.com/v1"
+        )
+        return _wrap_with_recording(
+            _wrap_with_calibration(
+                OpenAIResponsesProvider(
+                    name=provider_kind or "openai-responses",
+                    base_url=resolved_base_url,
+                    api_key=api_key,
+                    model=str(model),
+                    preset=_resolve_preset_param(params),
+                    reasoning_effort=(
+                        str(reasoning_effort) if reasoning_effort else None
+                    ),
+                    force_direct=direct_connection,
+                )
+            )
+        )
+    if provider_kind in {"google", "gemini", "google-genai", "google_genai"}:
+        from steerable_agent_runtime.llm import GoogleGenAIProvider
+
+        return _wrap_with_recording(
+            _wrap_with_calibration(
+                GoogleGenAIProvider(
+                    name=provider_kind or "google",
+                    base_url=base_url or "https://generativelanguage.googleapis.com",
+                    api_key=api_key,
+                    model=str(model),
+                    preset=_resolve_preset_param(params),
+                    force_direct=direct_connection,
+                )
+            )
+        )
+
+    raise ValueError(f"unknown provider: {provider_kind!r}")
+
+
+def _wrap_with_cache_control(provider: LLMProvider) -> LLMProvider:
+    """Emit prompt-cache breakpoints (Wave 4, W4-4) — default-on.
+
+    Anthropic is the only provider with an explicit breakpoint API; for the
+    implicit prefix caches (OpenAI-compatible, Ollama) the wrapper is a
+    pass-through. ``STEERABLE_CACHE_CONTROL=0`` disables it (a debugging
+    escape hatch, e.g. diffing wire bytes against a recorded fixture).
+    ``STEERABLE_PROMPT_CACHE_TTL=1h`` opts the breakpoints into Anthropic's
+    1-hour TTL (CC ``CLAUDE_CODE_PROMPT_CACHE_TTL`` parity); anything else
+    keeps the 5-minute default.
+    """
+
+    flag = os.environ.get("STEERABLE_CACHE_CONTROL", "1").strip().lower()
+    if flag in {"0", "false", "no", "off"}:
+        return provider
+    from steerable_agent_runtime import CacheControlProvider
+
+    ttl = os.environ.get("STEERABLE_PROMPT_CACHE_TTL", "").strip().lower()
+    retention = "long" if ttl in {"1h", "3600", "3600s", "long"} else "short"
+    return CacheControlProvider(provider, retention=retention)