Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

153 KB
Raw Blame
"""OpenCode agent implementation (coordinator).

Most heavy lifting lives in:
- server.py: OpenCode generations (processes) and their HTTP API
- client_manager.py: the OpenCode instance's generation set and launch specs
- poll_loop.py: unified poll loop
- session.py: session mapping + concurrency guards
"""

from __future__ import annotations

import asyncio
from contextlib import asynccontextmanager
import logging
import os
import secrets
import time
from dataclasses import dataclass, field
from typing import Any, AsyncIterator, Dict, Optional

import aiohttp

from core.backend_failure import emit_backend_failure
from core.caller_context import (
    AVIBE_CALLER_PLATFORM_ENV,
    AVIBE_CALLER_REMOTE_ENV,
    AVIBE_CALLER_USER_ID_ENV,
    AVIBE_SESSION_ID_ENV,
    caller_env_for_platform_payload,
    validated_caller_env_snapshot,
)
from core.agent_output import TurnEnd, TurnOutcome, emit_output
from core.message_output import terminal_output_for
from core.managed_skills import (
    BUILTIN_SKILLS_ROOT_ENV,
    managed_skill_environment,
    managed_skill_project_base,
)
from core.processing_indicator import STOPPED_REACTION_EMOJI
from core.native_dispatch_phase import (
    mark_backend_dispatch_attempted,
    prewrite_user_stop_requested,
)
from core.resource_governance import (
    AgentResourceFailure,
    observe_agent_resource_pressure,
    governor_from_controller,
    pids_failure_labels,
)
from core.run_settlement import SETTLED_BY_BACKEND_REFRESH
from core.runtime_activation import RuntimeActivationIdentity
from core.runtime_ownership import (
    RuntimeResourceTarget,
    RuntimeSessionBinding,
    wake_runtime_ownership,
)
from core.services.agent_steering import (
    ActiveSteerTarget,
    SteerOutcome,
    SteerReconcileRequest,
    SteerRequest,
    SteerResult,
    result as steer_result,
)
from core.system_prompt_injection import (
    build_system_prompt_injection,
    get_enabled_agents_for_prompt,
)
from modules.agents.base import AgentRequest, BaseAgent, message_with_files
from modules.agents.runtime_generations import RuntimeBinding, RuntimeUnitStopping
from modules.agents.model_hub import (
    ModelHubLaunch,
    OpenCodeOverlay,
    bind_launch,
    bind_turn_mode,
    launch_refusal_copy,
    opencode_model_for_overlay,
    opencode_model_catalog_for_overlay,
    opencode_requested_model_for_overlay,
    persisted_launch_identity,
    resolve_opencode_overlay_launch,
)
from modules.agents.catalog import display_name_for_backend
from vibe.i18n import t as i18n_t

from .caller_context import (
    bind_session as bind_caller_context_session,
    refresh_session as refresh_caller_context_session,
    unbind_session as unbind_caller_context_session,
)
from .client_manager import OpenCodeRuntime
from .message_processor import OpenCodeMessageProcessorMixin
from .poll_loop import (
    OpenCodePollLoop,
    restored_context_from_poll_info,
    restored_platform_from_poll_info,
    restored_session_key_from_poll_info,
)
from .server import (
    OpenCodeDirectoryBootstrapTimeoutError,
    OpenCodeGeneration,
    OpenCodeLaunchSpec,
    StopOutcome,
    OpenCodePromptRejectedError,
    OpenCodeRuntimeConfigInvalidError,
    native_part_id_for_attempt,
    other_runtimes_live_records,
)
from .session import (
    OpenCodeResumeUnavailableError,
    OpenCodeSessionManager,
    requires_message_order_repair,
)
from .utils import resolve_opencode_model_id, resolve_opencode_reasoning_effort

logger = logging.getLogger(__name__)
_STEERING_SNAPSHOT_KEY = "opencode_native_steering"
_MODEL_HUB_DISPLAY_MODEL_KEY = "model_hub_display_model"
_CALLER_CONTEXT_ENV_SNAPSHOT_KEY = "opencode_caller_context_env"
# The generation whose process runs a polled native turn; polls persisted by
# releases before generations lack it.
_GENERATION_SNAPSHOT_KEY = "opencode_generation_id"
_MANAGED_SKILL_PROJECT_BASE_SNAPSHOT_KEY = "opencode_managed_skill_project_base"
_MANAGED_SKILL_BUILTIN_CATALOG_KEY = "opencode_managed_skill_builtin_catalog"
_STATUS_RECONCILIATION_FAILURE_LIMIT = 3
# A successful prompt_async response transfers ownership to a forked worker,
# but does not prove that worker will publish its first message. Keep this
# handoff bounded independently of the optional whole-turn timeout.
_ASYNC_PROMPT_ACCEPTED_ACTIVITY_TIMEOUT_SECONDS = 120.0
# OpenCode can report idle just before the completed assistant message becomes
# visible through the message-list endpoint.
_ASYNC_PROMPT_RESULT_CONFIRMATION_TIMEOUT_SECONDS = 5.0
# A prompt accepted at the end of the previous native turn can race its final
# status transition. Let that transition settle before trusting the write as a
# same-turn steer.
_STEER_POST_WRITE_STATUS_SETTLE_SECONDS = 0.1
_RESTORED_IM_REGISTRATION_RETRY_DELAY_SECONDS = 0.25
_RESTORED_IM_PLATFORMS = {"slack", "discord", "telegram", "lark", "wechat"}
_CALLER_CONTEXT_BINDING_REFRESH_SECONDS = 60 * 60
_CALLER_CONTEXT_BINDING_RETRY_SECONDS = 1.0


def _caller_context_path_for_server(server: object) -> str | None:
    resolver = getattr(server, "caller_context_binding_path", None)
    if not callable(resolver):
        return None
    try:
        value = os.fspath(resolver())
    except (TypeError, OSError):
        return None
    return value or None


def _binding_path_kwargs(path: str | None) -> dict[str, str]:
    return {"path": path} if path else {}


def _poll_generation_id(poll_info: Any) -> str | None:
    snapshot = getattr(poll_info, "processing_indicator", None)
    value = snapshot.get(_GENERATION_SNAPSHOT_KEY) if isinstance(snapshot, dict) else None
    return value if isinstance(value, str) and value else None


class _RestoredPollUnrecorded(RuntimeError):
    """A restored poll binds elsewhere than it names, and that was not recorded."""


@dataclass
class _RestoredPollHandoff:
    """A poll task a restore started, waiting for the restore to publish it."""

    ready: asyncio.Future[bool]
    published: asyncio.Event
    poll_info: Any
    task: asyncio.Task


def _poll_runs_in(poll_info: Any, records: list[dict[str, Any]]) -> bool:
    """Whether one of ``records`` names the process executing a poll's run.

    That is the generation the poll names; a poll from before generations
    names none, and the process marking its native session as running does.
    """

    generation_id = _poll_generation_id(poll_info)
    if generation_id is not None:
        return any(record.get("generation_id") == generation_id for record in records)
    return any(
        isinstance(record.get("active_run_sessions"), list)
        and poll_info.opencode_session_id in record["active_run_sessions"]
        for record in records
    )


def _log_lifecycle_failure(task: asyncio.Task) -> None:
    if not task.cancelled() and task.exception() is not None:
        logger.error("OpenCode generation lifecycle step failed", exc_info=task.exception())


@dataclass
class _TurnGeneration:
    """The binding that keeps a turn's generation alive until the turn settles."""

    binding: RuntimeBinding | None = None


def _task_is_stopping(task: asyncio.Task) -> bool:
    cancelling = getattr(task, "cancelling", None)
    return task.done() or bool(cancelling and cancelling())


@dataclass
class _OpenCodeSteerState:
    task: asyncio.Task
    base_session_id: str
    target_session_id: str
    logical_turn_id: str
    native_session_id: str
    directory: str
    agent: Optional[str]
    model: Optional[Dict[str, str]]
    reasoning_effort: Optional[str]
    system: Optional[str]
    baseline_message_ids: set[str]
    catalog_accepted: Any = None
    lock: asyncio.Lock = field(default_factory=asyncio.Lock)
    closing: bool = False
    awaiting_after_message_ids: set[str] | None = None
    awaiting_user_text: str | None = None
    awaiting_prompt_accepted: bool = False
    awaiting_prompt_activity_deadline: float | None = None
    awaiting_active_status_observed: bool = False
    awaiting_result_confirmation_deadline: float | None = None
    idle_reconciliation_message: str = ""
    restored: bool = False
    reconcile_initial_status: bool = False
    status_reconciliation_failures: int = 0
    terminal_status_failure_messages: list[Dict[str, Any]] | None = None
    terminal_status_failure_generation: int = 0
    # The generation whose process runs this native turn.
    generation: Any = None

    @property
    def native_turn_id(self) -> str:
        return f"opencode:{self.native_session_id}:{id(self.task)}"


class _SteeringAwareOpenCodeServer:
    """Keep the primary poll owner alive across an accepted async prompt."""

    def __init__(
        self,
        server: OpenCodeGeneration,
        state: _OpenCodeSteerState,
    ) -> None:
        self._server = server
        self._state = state
        self.last_list_native_live: bool | None = None

    def __getattr__(self, name: str) -> Any:
        return getattr(self._server, name)

    @staticmethod
    def _message_ids(messages: list[Dict[str, Any]]) -> set[str]:
        return {
            str(message.get("info", {}).get("id"))
            for message in messages
            if message.get("info", {}).get("id")
        }

    def _is_final_assistant_snapshot(self, messages: list[Dict[str, Any]]) -> bool:
        if not messages:
            return False
        info = messages[-1].get("info", {})
        return bool(
            info.get("id") not in self._state.baseline_message_ids
            and info.get("role") == "assistant"
            and info.get("time", {}).get("completed")
            and info.get("finish") != "tool-calls"
            and not info.get("error")
        )

    @staticmethod
    def _message_text(message: Dict[str, Any]) -> str:
        return "".join(
            str(part.get("text") or "")
            for part in (message.get("parts") or [])
            if part.get("type") == "text"
        )

    @staticmethod
    def _last_is_completed_error(messages: list[Dict[str, Any]]) -> bool:
        if not messages:
            return False
        info = messages[-1].get("info", {}) or {}
        return bool(
            info.get("role") == "assistant"
            and info.get("time", {}).get("completed")
            and info.get("error")
        )

    @staticmethod
    def _has_post_boundary_activity(
        messages: list[Dict[str, Any]],
        boundary_ids: set[str],
        baseline_ids: set[str],
    ) -> bool:
        # Evidence means a message the restored poll loop would treat as new:
        # outside the reconciliation boundary AND outside the pre-prompt
        # baseline. The baseline term matters when the sampled boundary is
        # empty (only baseline messages existed when it was sampled).
        for message in messages:
            message_id = (message.get("info", {}) or {}).get("id")
            if not message_id:
                continue
            if message_id not in boundary_ids and message_id not in baseline_ids:
                return True
        return False

    @classmethod
    def _inserted_user_index(
        cls,
        messages: list[Dict[str, Any]],
        excluded_message_ids: set[str],
        inserted_user_text: str,
    ) -> int:
        return next(
            (
                index
                for index, message in enumerate(messages)
                if message.get("info", {}).get("role") == "user"
                and message.get("info", {}).get("id") not in excluded_message_ids
                and cls._message_text(message) == inserted_user_text
            ),
            -1,
        )

    @classmethod
    def _has_final_assistant_after(
        cls,
        messages: list[Dict[str, Any]],
        excluded_message_ids: set[str],
        *,
        inserted_user_text: str | None = None,
    ) -> bool:
        inserted_user_index = -1
        if inserted_user_text is not None:
            inserted_user_index = cls._inserted_user_index(
                messages,
                excluded_message_ids,
                inserted_user_text,
            )
            if inserted_user_index < 0:
                return False
        return any(
            index > inserted_user_index
            and message.get("info", {}).get("role") == "assistant"
            and message.get("info", {}).get("id") not in excluded_message_ids
            and message.get("info", {}).get("time", {}).get("completed")
            and message.get("info", {}).get("finish") != "tool-calls"
            and not message.get("info", {}).get("error")
            for index, message in enumerate(messages)
        )

    @classmethod
    def _has_completed_error_after(
        cls,
        messages: list[Dict[str, Any]],
        excluded_message_ids: set[str],
        *,
        inserted_user_text: str | None = None,
    ) -> bool:
        inserted_user_index = -1
        if inserted_user_text is not None:
            inserted_user_index = cls._inserted_user_index(
                messages,
                excluded_message_ids,
                inserted_user_text,
            )
            if inserted_user_index < 0:
                return False
        return any(
            index > inserted_user_index
            and message.get("info", {}).get("role") == "assistant"
            and message.get("info", {}).get("id") not in excluded_message_ids
            and message.get("info", {}).get("time", {}).get("completed")
            and message.get("info", {}).get("error")
            for index, message in enumerate(messages)
        )

    def _has_pending_question_tool(self, messages: list[Dict[str, Any]]) -> bool:
        return any(
            message.get("info", {}).get("id") not in self._state.baseline_message_ids
            and part.get("type") == "tool"
            and part.get("tool") == "question"
            and (part.get("state") or {}).get("status") != "completed"
            for message in messages
            for part in (message.get("parts") or [])
        )

    def _completed_assistant_boundary(
        self,
        messages: list[Dict[str, Any]],
    ) -> set[str]:
        last_completed_index = next(
            (
                index
                for index in range(len(messages) - 1, -1, -1)
                if messages[index].get("info", {}).get("role") == "assistant"
                and messages[index].get("info", {}).get("time", {}).get("completed")
                and messages[index].get("info", {}).get("id")
                not in self._state.baseline_message_ids
            ),
            -1,
        )
        return self._message_ids(messages[: last_completed_index + 1])

    def _idle_reconciliation_error_text(self) -> str:
        if self._state.idle_reconciliation_message:
            return self._state.idle_reconciliation_message
        default_label = str(i18n_t("common.default", "en"))
        return str(
            i18n_t(
                "error.opencodeEmptyResponse",
                "en",
                provider=default_label,
                model=default_label,
                variant=default_label,
            )
        )

    def _clear_awaiting_reconciliation(self) -> None:
        self._state.awaiting_after_message_ids = None
        self._state.awaiting_user_text = None
        self._state.awaiting_prompt_accepted = False
        self._state.awaiting_prompt_activity_deadline = None
        self._state.awaiting_active_status_observed = False
        self._state.awaiting_result_confirmation_deadline = None

    def _terminal_reconciliation_failure(
        self,
        session_id: str,
        messages: list[Dict[str, Any]],
        *,
        name: str,
        message: str,
    ) -> list[Dict[str, Any]]:
        self._state.closing = True
        failure = {
            "info": {
                "id": f"avibe-status-reconciliation:{session_id}",
                "role": "assistant",
                "time": {"completed": time.time()},
                # Keep the restored poll in its bounded error path until it
                # emits the terminal failure through the existing Result owner.
                "finish": "tool-calls",
                "error": {
                    "name": name,
                    "data": {"message": message},
                },
            },
            "parts": [],
        }
        self._state.terminal_status_failure_messages = [*messages, failure]
        return self._state.terminal_status_failure_messages

    async def list_messages(self, session_id: str, directory: str) -> list[Dict[str, Any]]:
        while True:
            wait_for_insert = False
            async with self._state.lock:
                self.last_list_native_live = None
                if self._state.terminal_status_failure_messages is not None:
                    return self._state.terminal_status_failure_messages
                messages = await self._server.list_messages(session_id, directory)
                if self._has_pending_question_tool(messages):
                    self._state.closing = True
                    return messages
                awaiting = self._state.awaiting_after_message_ids
                inserted_user_text = self._state.awaiting_user_text
                final_snapshot = self._is_final_assistant_snapshot(messages)
                reconcile_initial_status = self._state.reconcile_initial_status
                reconcile_insert = awaiting is not None
                if reconcile_insert or final_snapshot or reconcile_initial_status:
                    try:
                        status = await self._server.get_session_status(session_id, directory)
                        from modules.agents.opencode.poll_loop import _native_session_is_live

                        self.last_list_native_live = _native_session_is_live(status)
                    except Exception as exc:
                        self._state.status_reconciliation_failures += 1
                        if (
                            self._state.status_reconciliation_failures
                            >= _STATUS_RECONCILIATION_FAILURE_LIMIT
                        ):
                            evidence_boundary = (
                                awaiting
                                if awaiting is not None
                                else self._state.baseline_message_ids
                            )
                            last_message_id = (
                                messages[-1].get("info", {}).get("id")
                                if messages
                                else None
                            )
                            boundary_answer_is_latest = (
                                self._state.restored
                                and inserted_user_text is None
                                and last_message_id in evidence_boundary
                            )
                            if final_snapshot and (
                                boundary_answer_is_latest
                                or self._has_final_assistant_after(
                                    messages,
                                    evidence_boundary,
                                    inserted_user_text=inserted_user_text,
                                )
                            ):
                                self._clear_awaiting_reconciliation()
                                self._state.reconcile_initial_status = False
                                self._state.closing = True
                                return messages
                            return self._terminal_reconciliation_failure(
                                session_id,
                                messages,
                                name="StatusReconciliationError",
                                message=str(exc),
                            )
                        wait_for_insert = True
                    else:
                        self._state.status_reconciliation_failures = 0
                        if status is not None and status.get("type") in {"busy", "retry"}:
                            if reconcile_initial_status and awaiting is None:
                                self._state.awaiting_after_message_ids = (
                                    self._completed_assistant_boundary(messages)
                                )
                            if reconcile_insert and (
                                inserted_user_text is None
                                or self._inserted_user_index(
                                    messages,
                                    awaiting,
                                    inserted_user_text,
                                )
                                >= 0
                            ):
                                # Start confirmed: the inserted user message is
                                # visible while the native session reports
                                # activity (or a restored poll sampled its
                                # boundary during activity). Hand the in-progress
                                # snapshot back to the poll loop so live tool
                                # activity keeps streaming; the result-confirmation
                                # window still guards the idle boundary below.
                                if inserted_user_text is not None:
                                    self._state.awaiting_active_status_observed = True
                                    self._state.awaiting_result_confirmation_deadline = None
                                    if final_snapshot or self._has_final_assistant_after(
                                        messages,
                                        awaiting,
                                        inserted_user_text=inserted_user_text,
                                    ):
                                        # The final assistant already exists even
                                        # though the session still reports busy
                                        # (status settles after the message lands):
                                        # settle like the idle path does.
                                        self._clear_awaiting_reconciliation()
                                        self._state.closing = True
                                if self._last_is_completed_error(messages):
                                    # Keep terminal error snapshots gated while the
                                    # native runtime has not settled: the poll loop
                                    # would emit its own terminal failure (or a
                                    # competing "continue") while OpenCode's native
                                    # retry is still active.
                                    wait_for_insert = True
                                elif inserted_user_text is None and not self._has_post_boundary_activity(
                                    messages,
                                    awaiting,
                                    self._state.baseline_message_ids,
                                ):
                                    # Restored boundary-sampled polls: a busy
                                    # snapshot holding only boundary messages
                                    # (ending in a pre-restore final answer) must
                                    # not be handed back, or the restored poll
                                    # loop would re-emit the old answer and drop
                                    # the still-running poll. Wait for post-boundary
                                    # or in-progress evidence.
                                    wait_for_insert = True
                                else:
                                    return messages
                            wait_for_insert = True
                        else:
                            self._state.reconcile_initial_status = False
                            if reconcile_insert:
                                inserted_user_missing = (
                                    inserted_user_text is None
                                    or (
                                        self._inserted_user_index(
                                            messages,
                                            awaiting,
                                            inserted_user_text,
                                        )
                                        < 0
                                    )
                                )
                                if not inserted_user_missing:
                                    self._state.awaiting_active_status_observed = True
                                last_message_id = (
                                    messages[-1].get("info", {}).get("id")
                                    if messages
                                    else None
                                )
                                if (
                                    inserted_user_missing
                                    and final_snapshot
                                    and last_message_id in awaiting
                                    and not self._state.awaiting_prompt_accepted
                                ):
                                    self._clear_awaiting_reconciliation()
                                    self._state.closing = True
                                    return messages
                                has_final_insert_result = (
                                    final_snapshot
                                    and self._has_final_assistant_after(
                                        messages,
                                        awaiting,
                                        inserted_user_text=inserted_user_text,
                                    )
                                )
                                has_post_boundary_error = self._has_completed_error_after(
                                    messages,
                                    awaiting,
                                    inserted_user_text=inserted_user_text,
                                )
                                if has_final_insert_result or has_post_boundary_error:
                                    self._clear_awaiting_reconciliation()
                                    if has_final_insert_result:
                                        self._state.closing = True
                                    return messages
                                if self._state.awaiting_active_status_observed:
                                    result_deadline = (
                                        self._state.awaiting_result_confirmation_deadline
                                    )
                                    if result_deadline is None:
                                        self._state.awaiting_result_confirmation_deadline = (
                                            time.monotonic()
                                            + _ASYNC_PROMPT_RESULT_CONFIRMATION_TIMEOUT_SECONDS
                                        )
                                        wait_for_insert = True
                                    elif time.monotonic() < result_deadline:
                                        wait_for_insert = True
                                    else:
                                        self._clear_awaiting_reconciliation()
                                        return self._terminal_reconciliation_failure(
                                            session_id,
                                            messages,
                                            name="NativeSessionEndedBeforeResult",
                                            message=self._idle_reconciliation_error_text(),
                                        )
                                elif self._state.awaiting_prompt_accepted:
                                    # A successful prompt_async response transfers
                                    # ownership before OpenCode must publish a
                                    # message or mark the session busy.
                                    activity_deadline = (
                                        self._state.awaiting_prompt_activity_deadline
                                    )
                                    if activity_deadline is None:
                                        activity_deadline = (
                                            time.monotonic()
                                            + _ASYNC_PROMPT_ACCEPTED_ACTIVITY_TIMEOUT_SECONDS
                                        )
                                        self._state.awaiting_prompt_activity_deadline = (
                                            activity_deadline
                                        )
                                    if time.monotonic() < activity_deadline:
                                        wait_for_insert = True
                                    else:
                                        self._clear_awaiting_reconciliation()
                                        return self._terminal_reconciliation_failure(
                                            session_id,
                                            messages,
                                            name="NativeSessionEndedBeforeResult",
                                            message=self._idle_reconciliation_error_text(),
                                        )
                                else:
                                    self._clear_awaiting_reconciliation()
                                    return self._terminal_reconciliation_failure(
                                        session_id,
                                        messages,
                                        name="NativeSessionEndedBeforeResult",
                                        message=self._idle_reconciliation_error_text(),
                                    )
                            else:
                                self._clear_awaiting_reconciliation()
                                if final_snapshot:
                                    self._state.closing = True
                                elif (
                                    reconcile_initial_status
                                    and not self._has_final_assistant_after(
                                        messages,
                                        self._state.baseline_message_ids,
                                    )
                                ):
                                    return self._terminal_reconciliation_failure(
                                        session_id,
                                        messages,
                                        name="NativeSessionEndedBeforeResult",
                                        message=self._idle_reconciliation_error_text(),
                                    )
                                return messages
                else:
                    self._clear_awaiting_reconciliation()
                    return messages
            if wait_for_insert:
                await asyncio.sleep(0.1)

    async def prompt_async(self, *args, **kwargs) -> None:
        async with self._state.lock:
            terminal_messages = self._state.terminal_status_failure_messages
            if terminal_messages is not None:
                # The normal poll loop retries a first native error with
                # "continue". Do not dispatch new work after reconciliation
                # already proved terminal; advance only the synthetic evidence
                # ID so its existing retry budget reaches terminal delivery.
                self._state.terminal_status_failure_generation += 1
                failure = terminal_messages[-1]
                info = dict(failure.get("info", {}))
                info["id"] = (
                    f"avibe-status-reconciliation:{self._state.native_session_id}:"
                    f"{self._state.terminal_status_failure_generation}"
                )
                self._state.terminal_status_failure_messages = [
                    *terminal_messages[:-1],
                    {**failure, "info": info},
                ]
                return
            kwargs_map = dict(kwargs)
            prompt_text = str(kwargs_map.get("text") or "")
            snapshot_ids = kwargs_map.pop("awaiting_after_ids", None)
            if snapshot_ids is None:
                session_id = str(kwargs_map.get("session_id") or "")
                directory = str(kwargs_map.get("directory") or "")
                if session_id and directory:
                    try:
                        current = await self._server.list_messages(session_id, directory)
                    except Exception:
                        current = []
                    snapshot_ids = self._message_ids(current)
            if snapshot_ids is not None:
                self._state.awaiting_after_message_ids = set(snapshot_ids)
                self._state.awaiting_user_text = prompt_text or None
                self._state.awaiting_prompt_accepted = False
                self._state.awaiting_prompt_activity_deadline = None
                self._state.awaiting_active_status_observed = False
                self._state.awaiting_result_confirmation_deadline = None
            await self._server.prompt_async(*args, **{k: v for k, v in kwargs.items() if k != "awaiting_after_ids"})
            if kwargs.get("system") == self._state.system and self._state.catalog_accepted:
                self._state.catalog_accepted()
            if snapshot_ids is not None:
                self._state.awaiting_prompt_accepted = True
                self._state.awaiting_prompt_activity_deadline = (
                    time.monotonic()
                    + _ASYNC_PROMPT_ACCEPTED_ACTIVITY_TIMEOUT_SECONDS
                )

    async def abort_session(self, *args, **kwargs) -> bool:
        async with self._state.lock:
            self._state.closing = True
            return await self._server.abort_session(*args, **kwargs)


def resolve_opencode_model_dict(model_str: str | None, default_provider: str | None) -> dict[str, str] | None:
    if not model_str:
        return None
    parts = model_str.split("/", 1)
    if len(parts) == 2:
        return {"providerID": parts[0], "modelID": parts[1]}
    if isinstance(default_provider, str) and default_provider.strip():
        return {"providerID": default_provider.strip(), "modelID": model_str}
    return None


def _raw_settings_key_from_session_key(session_key: str) -> str:
    parts = str(session_key or "").split("::")
    if len(parts) >= 3 and parts[1] in {"user", "channel", "platform", "project"}:
        return "::".join(parts[2:])
    if len(parts) >= 2:
        return "::".join(parts[1:])
    return str(session_key or "")


def _target_agent_session_id(request: AgentRequest) -> str:
    payload = request.context.platform_specific or {}
    target = payload.get("agent_session_target") if isinstance(payload, dict) else None
    if isinstance(target, dict) and target.get("id"):
        return str(target["id"])
    return str(payload.get("agent_session_id") or "") if isinstance(payload, dict) else ""


class OpenCodeAgent(OpenCodeMessageProcessorMixin, BaseAgent):
    """OpenCode Server API integration via HTTP."""

    name = "opencode"
    # How a forced stop settles the work bound to its process: a runtime update,
    # unless a disable's shutdown named its own reason.
    _forced_stop_reason: str = SETTLED_BY_BACKEND_REFRESH

    def __init__(self, controller, opencode_config):
        super().__init__(controller)
        self.opencode_config = opencode_config

        self._runtime = OpenCodeRuntime(
            opencode_config,
            resource_governor=governor_from_controller(controller),
        )
        self._runtime.durable_poll_generations = self._durable_poll_generations
        self._runtime.on_generation_ready = self._attach_generation_activation
        self._runtime.on_generation_stopping = self._on_generation_stopping
        self._runtime.holds_activities = self._generation_holds_activities
        self._session_manager = OpenCodeSessionManager(self.settings_manager, self.name)

        self._poll_loop = OpenCodePollLoop(self)

        self._active_requests: Dict[str, asyncio.Task] = {}
        # Sessions whose in-flight task is being cancelled BY THE USER. The
        # cancellation lands in the request coroutine, which cannot otherwise
        # tell a /stop from any other teardown; see ``handle_stop``.
        self._user_stopped_sessions: set[str] = set()
        self._session_last_activity: Dict[str, float] = {}
        self._steering_states: Dict[str, _OpenCodeSteerState] = {}
        self._restored_poll_servers: Dict[asyncio.Task, _SteeringAwareOpenCodeServer] = {}
        # Request tasks already settling, interrupted by a forced refresh or in
        # their own cleanup. A forced refresh never cancels these again, and a
        # restored poll it interrupted retires its own durable record.
        self._settling_request_tasks: set[asyncio.Task] = set()
        # The generation each running native turn is bound to, by base session.
        self._session_generations: Dict[str, OpenCodeGeneration] = {}
        # Binding releases and reaps run apart from the turn that ends them, so
        # no turn's cleanup waits on another generation's start or stop.
        self._lifecycle_tasks: set[asyncio.Task] = set()
        self._resource_failures: Dict[tuple[Any, ...], AgentResourceFailure | None] = {}
        # One restore at a time: an enable-triggered restore can overlap an
        # IM-ready or reconnect one, and a poll is claimed only at its handoff.
        self._restore_lock = asyncio.Lock()
        # Durable polls a restore left for a later one; the sweep restores again.
        self._polls_awaiting_restore: set[str] = set()

    def _durable_poll_generations(self) -> Dict[str, Optional[str]]:
        return {
            session_id: _poll_generation_id(poll_info)
            for session_id, poll_info in self.sessions.get_all_active_polls().items()
        }

    async def _prepare_launch(
        self,
        context: Any = None,
    ) -> tuple[Any, OpenCodeOverlay | None, OpenCodeLaunchSpec, Any]:
        """Snapshot every launch input in one step, then derive the launch from it.

        The Model Hub snapshot and the runtime's own inputs (CLI path, renewal
        epoch, binary, config, and credential identities) are read together,
        before the first await, with the ``agents.opencode`` settings they came
        from. The overlay and the spec derive from that snapshot only, and the
        turn takes its per-turn settings from the returned settings, so a save
        or renewal that lands meanwhile changes nothing about this turn; the
        next one moves.
        """

        model_hub_runtime = getattr(self.controller, "model_hub_runtime", None)
        snapshot = getattr(model_hub_runtime, "snapshot", None)
        config = snapshot() if callable(snapshot) else None
        inputs = self._runtime.launch_inputs()
        snapshot_kwargs = {"config": config} if config is not None else {}
        turn_mode = getattr(model_hub_runtime, "turn_mode", None)
        if context is not None and callable(turn_mode):
            bind_turn_mode(context, turn_mode("opencode", **snapshot_kwargs))
        prepare_overlay = getattr(model_hub_runtime, "prepare_opencode_overlay", None)
        overlay = await prepare_overlay(**snapshot_kwargs) if callable(prepare_overlay) else None
        return config, overlay, await self._runtime.launch_spec(overlay, inputs), inputs.settings

    async def _ensure_adopted(self) -> None:
        """Adopt a previous controller's generations against the current spec."""

        if self._runtime.adopted:
            return
        try:
            _config, _overlay, current_spec, _settings = await self._prepare_launch()
        except Exception:
            # Without a spec nothing can keep serving; every adopted generation
            # retires and stops once its restored work drains.
            logger.warning("Adopting OpenCode generations without the current launch spec", exc_info=True)
            current_spec = None
        await self._runtime.ensure_adopted(current_spec)

    @asynccontextmanager
    async def _outside_turn_admission(self) -> AsyncIterator[None]:
        """Admit work outside a turn the way a turn is admitted.

        A native migration drains the backend, and work outside a turn waits
        for it to end. Admitted work counts as active until it is bound, so
        the migration never overlaps the start of an OpenCode process.
        """

        agent_service = getattr(self.controller, "agent_service", None)
        is_ready = getattr(agent_service, "is_backend_ready", None)
        while True:
            # Counted before the check, in one step with it, so a drain that
            # begins later sees this work.
            self._runtime.outside_turn_acquisitions += 1
            if not callable(is_ready) or is_ready(self.name):
                break
            self._runtime.outside_turn_acquisitions -= 1
            await agent_service.wait_backend_ready(self.name)
        try:
            yield
        finally:
            self._runtime.outside_turn_acquisitions -= 1

    @asynccontextmanager
    async def current_server(self) -> AsyncIterator[OpenCodeGeneration]:
        """Pin the current generation for one controller-side request sequence."""

        async with self._outside_turn_admission():
            _config, _overlay, spec, _settings = await self._prepare_launch()
            binding = await self._runtime.acquire(spec)
        try:
            yield binding.generation.runtime
        finally:
            await self._release_binding(binding)

    async def lease_generation(self, purpose: str, *, ttl_seconds: float) -> Dict[str, Any]:
        """Pin the current generation for a caller outside the controller."""

        async with self._outside_turn_admission():
            _config, _overlay, spec, _settings = await self._prepare_launch()
            lease_id, generation = await self._runtime.lease(spec, ttl_seconds)
        logger.info(
            "Leased OpenCode generation %s for %s (%s)",
            generation.generation_id,
            purpose,
            lease_id,
        )
        return {"lease_id": lease_id, "server": generation}

    async def release_generation_lease(self, lease_id: str) -> bool:
        # After a controller restart the lease lives only in its generation's
        # record until adoption re-holds it; release it there, not nowhere.
        await self._ensure_adopted()
        return await self._runtime.release_lease(lease_id)

    def _track_lifecycle(self, operation: Any) -> None:
        task = asyncio.get_running_loop().create_task(operation)
        self._lifecycle_tasks.add(task)
        task.add_done_callback(self._lifecycle_tasks.discard)
        task.add_done_callback(_log_lifecycle_failure)

    async def _release_binding(self, binding: RuntimeBinding | None) -> None:
        # Release is bookkeeping only; the set stops a drained generation in
        # its own reconciler, so no turn's cleanup waits on a teardown.
        if binding is not None:
            await binding.release()

    def _schedule_reap(self) -> None:
        self._track_lifecycle(self._runtime.reap())

    async def _maintain_caller_context_binding(
        self,
        session_id: str,
        binding_token: str,
        binding_path: str | None,
        *,
        payload: dict[str, Any] | None,
        working_directory: str,
        extra_env: dict[str, str],
        initially_bound: bool,
        message: Any = None,
        fallback_platform: str | None = None,
    ) -> None:
        """Keep one Turn binding published and renewed for its full lifetime."""

        bound = initially_bound
        while True:
            await asyncio.sleep(
                _CALLER_CONTEXT_BINDING_REFRESH_SECONDS
                if bound
                else _CALLER_CONTEXT_BINDING_RETRY_SECONDS
            )
            if bound:
                try:
                    refreshed = bool(
                        await asyncio.to_thread(
                            refresh_caller_context_session,
                            session_id,
                            binding_token=binding_token,
                            **_binding_path_kwargs(binding_path),
                        )
                    )
                except Exception:
                    logger.warning(
                        "Failed to renew OpenCode caller context for session %s",
                        session_id,
                        exc_info=True,
                    )
                    bound = False
                else:
                    if not refreshed:
                        return
                    bound = True
                    continue
            try:
                bound = bool(
                    await asyncio.to_thread(
                        bind_caller_context_session,
                        session_id,
                        payload,
                        base_env=os.environ,
                        working_dir=working_directory,
                        extra_env=extra_env,
                        binding_token=binding_token,
                        replace_existing=False,
                        **_binding_path_kwargs(binding_path),
                        message=message,
                        fallback_platform=fallback_platform,
                    )
                )
                if not bound:
                    return
            except Exception:
                logger.warning(
                    "Failed to republish OpenCode caller context for session %s",
                    session_id,
                    exc_info=True,
                )
                bound = False

    @staticmethod
    async def _stop_caller_context_binding_renewal(
        task: asyncio.Task[None] | None,
    ) -> None:
        if task is None:
            return
        task.cancel()
        try:
            await task
        except asyncio.CancelledError:
            pass

    def _active_poll_is_persisted(self, session_id: str) -> bool:
        try:
            return session_id in self.sessions.get_all_active_polls()
        except Exception:
            logger.warning(
                "Could not verify OpenCode active poll retention for session %s",
                session_id,
                exc_info=True,
            )
            return True

    def _attach_generation_activation(self, generation: OpenCodeGeneration) -> None:
        registry = getattr(getattr(self, "controller", None), "runtime_activation", None)
        if registry is not None:
            generation.identity = registry.attach(self.name, f"opencode:{generation.generation_id}")

    def _retire_generation_activation(self, generation: OpenCodeGeneration) -> None:
        registry = getattr(getattr(self, "controller", None), "runtime_activation", None)
        identity = generation.identity
        if registry is not None and isinstance(identity, RuntimeActivationIdentity):
            # A turn never needs one particular unbound generation, and bound
            # work keeps a generation from stopping unless it is forced. No
            # commit fenced by this identity is lost when it retires.
            registry.retire_if_current(identity, lambda: True)

    def _generation_holds_activities(self, generation: OpenCodeGeneration) -> bool:
        service = getattr(self.controller, "agent_service", None)
        holds = getattr(service, "activation_has_activities", None)
        identity = generation.identity if isinstance(generation.identity, RuntimeActivationIdentity) else None
        return bool(callable(holds) and holds(self.name, identity))

    async def _on_generation_stopping(self, generation: OpenCodeGeneration, force: bool) -> None:
        self._retire_generation_activation(generation)
        if force:
            await self._interrupt_generation_work(generation)

    async def _interrupt_generation_work(self, generation: OpenCodeGeneration) -> None:
        """Settle every turn and Activity of a generation being force-stopped.

        Only this agent's bindings name the sessions, so a disabled agent's
        stop never reaches a re-enabled agent's work. A stop is retried while
        its process survives, and a retry settles only the sessions no earlier
        attempt settled: the core settles turns by session, and a settled
        session's next turn may already run on the re-enabled agent. Every
        Activity started under this generation's activation settles too, bound
        session or not: an Activity can outlive its foreground turn.
        """

        sessions = {
            base_session_id
            for base_session_id, bound in self._session_generations.items()
            if bound is generation
        }
        logger.warning(
            "Force-stopping OpenCode generation %s interrupts %s session(s)",
            generation.generation_id,
            len(sessions),
        )
        unsettled = sessions - generation.interrupted_sessions
        force_end = getattr(getattr(self.controller, "agent_service", None), "force_end_runtime_work", None)
        if callable(force_end):
            await force_end(
                self.name,
                base_session_ids=unsettled,
                activation_identities={generation.identity},
                reason=self._forced_stop_reason,
                agent=self,
            )
            generation.interrupted_sessions |= unsettled
        if sessions:
            await self._cancel_active_requests(base_session_ids=sessions)

    def _bound_generation(self, base_session_id: str | None) -> OpenCodeGeneration | None:
        return self._session_generations.get(str(base_session_id or ""))

    def runtime_activation_identity_for_request(
        self,
        request: Any,
    ) -> RuntimeActivationIdentity | None:
        generation = self._bound_generation(getattr(request, "base_session_id", None)) or self._runtime.current()
        identity = getattr(generation, "identity", None)
        return identity if isinstance(identity, RuntimeActivationIdentity) else None

    def runtime_activation_identity_for_session_binding(
        self,
        *,
        session_anchor: str,
        workdir: str | None,
    ) -> RuntimeActivationIdentity | None:
        normalized_anchor = str(session_anchor or "").strip()
        normalized_workdir = str(workdir or "").strip()
        if not normalized_anchor:
            raise ValueError("OpenCode Session binding has no anchor")
        active = self._session_manager.get_request_session(normalized_anchor)
        if active is not None and str(active[1] or "").strip() != normalized_workdir:
            raise ValueError("OpenCode Session binding changed workdir")
        generation = self._bound_generation(normalized_anchor) or self._runtime.current()
        identity = getattr(generation, "identity", None)
        return identity if isinstance(identity, RuntimeActivationIdentity) else None

    def _idle_reconciliation_message(
        self,
        model: Optional[Dict[str, str]],
        reasoning_effort: Optional[str],
    ) -> str:
        controller_translate = getattr(self.controller, "_t", None)
        lang = getattr(getattr(self.controller, "config", None), "language", "en")

        def translate(key: str, **kwargs: Any) -> str:
            if callable(controller_translate):
                return str(controller_translate(key, **kwargs))
            return str(i18n_t(key, lang, **kwargs))

        default_label = translate("common.default")
        return translate(
            "error.opencodeEmptyResponse",
            provider=(model or {}).get("providerID") or default_label,
            model=(model or {}).get("modelID") or default_label,
            variant=reasoning_effort or default_label,
        )

    def _resource_failure_for_server(
        self,
        server: Any,
    ) -> AgentResourceFailure | None:
        """Attribute a generation's own exit to shared resource pressure, once."""

        observed_exit = getattr(server, "observed_exit_pid", None)
        if callable(observed_exit):
            pid = observed_exit()
            key: tuple[Any, ...] = ("generation", getattr(server, "generation_id", None), pid)
        else:
            # The turn has no generation: the start itself failed.
            pid = self._runtime.last_start_failure_pid
            key = ("startup", self._runtime.start_failures, pid)
        if not isinstance(pid, int) or pid <= 0:
            return None
        if key in self._resource_failures:
            return self._resource_failures[key]
        failure = observe_agent_resource_pressure(self.controller)
        self._resource_failures[key] = failure
        if failure is not None:
            logger.error(
                "OpenCode server exited while the shared Agent cgroup reported resource pressure: %s",
                failure.message,
            )
        return failure

    def _resource_failure_suffix(
        self,
        failure: AgentResourceFailure | None,
    ) -> str:
        if failure is None:
            return ""
        language = str(
            getattr(getattr(self.controller, "config", None), "language", "en")
            or "en"
        )
        if failure.kind == "pids":
            return (
                f" {i18n_t('error.agentPidsLimit', language, **pids_failure_labels(failure, language))}"
            )
        if failure.kind == "memory":
            return f" {i18n_t('error.agentMemoryLimit', language)}"
        return ""

    def _server_start_error_display_text(
        self,
        error: BaseException,
        *,
        resource_failure: AgentResourceFailure | None = None,
    ) -> str:
        language = str(
            getattr(getattr(self.controller, "config", None), "language", "en")
            or "en"
        )
        if isinstance(error, OpenCodeRuntimeConfigInvalidError):
            message = i18n_t("error.opencodeRuntimeConfigInvalid", language)
        elif isinstance(error, OpenCodeDirectoryBootstrapTimeoutError):
            message = i18n_t("error.opencodeDirectoryBootstrapTimeout", language)
        elif isinstance(error, RuntimeUnitStopping):
            # The backend was disabled after this turn looked its agent up.
            message = i18n_t(
                "error.agentRuntimeRetired",
                language,
                agent=display_name_for_backend(self.name),
            )
        else:
            message = f"Failed to start OpenCode server: {error}"
        return f"❌ {message}{self._resource_failure_suffix(resource_failure)}"

    async def prepare_runtime_restart(self) -> None:
        """Adopt the generations a previous controller left running."""
        await self._ensure_adopted()

    async def retire_for_native_migration(self) -> None:
        """Strictly stop every generation; native custody needs no OpenCode process."""
        await self._ensure_adopted()
        if self.runtime_has_active_turns():
            raise RuntimeError("OpenCode runtime is busy")
        await self._runtime.retire_all_strict()

    def runtime_has_active_turns(self) -> bool:
        # A lease is a binding: an OAuth flow or another leased sequence between
        # its HTTP requests keeps its process in use.
        if self._runtime.outside_turn_acquisitions or self._runtime.has_bound_work():
            return True
        if any(not task.done() for task in self._active_requests.values()):
            return True
        return any(not generation.is_drained() for generation in self._runtime.generations())

    def runtime_ownership_snapshots(self) -> tuple[Any, ...] | None:
        """Map each generation to the exact durable identities it serves.

        Unbound Sessions acquire the current generation, so its target keeps
        every backend Session in view. A retiring generation serves only the
        Sessions bound to it.
        """

        generations = self._runtime.generations()
        if not generations:
            return ()
        request_sessions = self._session_manager.list_all()
        get_agent_session_id = getattr(
            self._session_manager,
            "get_agent_session_id",
            None,
        )
        if request_sessions and not callable(get_agent_session_id):
            logger.error("OpenCode durable Session ownership mapping is unavailable")
            return None
        bindings: list[RuntimeSessionBinding] = []
        for base_session_id, (
            _native_session_id,
            working_path,
            session_key,
        ) in request_sessions.items():
            agent_session_id = str(
                get_agent_session_id(base_session_id) or ""
            ).strip()
            if not agent_session_id or not working_path or not session_key:
                logger.error("OpenCode runtime ownership mapping is incomplete")
                return None
            bindings.append(
                RuntimeSessionBinding(
                    session_id=agent_session_id,
                    session_anchor=base_session_id,
                    workdir=working_path,
                    activity_runtime_keys=(f"{base_session_id}:{working_path}",),
                    fallback_route_keys=(session_key,),
                )
            )
        provider = getattr(self.controller, "runtime_ownership", None)
        snapshot = getattr(provider, "snapshot", None)
        if not callable(snapshot):
            logger.error("OpenCode runtime ownership provider is unavailable")
            return None
        catch_all = self._runtime.current() or generations[-1]
        results = []
        for generation in generations:
            serves_all = generation is catch_all
            served = tuple(
                binding
                for binding in bindings
                if serves_all or self._bound_generation(binding.session_anchor) is generation
            )
            target = RuntimeResourceTarget(
                backend="opencode",
                resource_key=f"opencode:{generation.generation_id}",
                bindings=served,
                known_activity_runtime_keys=tuple(
                    sorted(key for binding in served for key in binding.activity_runtime_keys)
                ),
                known_fallback_route_keys=tuple(
                    sorted(key for binding in served for key in binding.fallback_route_keys)
                ),
                include_all_backend_sessions=serves_all,
                maps_all_backend_activities=serves_all,
                maps_all_backend_fallback_runs=serves_all,
            )
            result = snapshot(target)
            wake_runtime_ownership(self.controller, result)
            results.append(result)
        return tuple(results)

    def record_runtime_turn_start(
        self,
        *,
        runtime_key: str,
        request: AgentRequest | None,
    ) -> None:
        del runtime_key
        if request is not None:
            self._session_last_activity[request.base_session_id] = time.monotonic()

    def _adopt_runtime_config(self, opencode_config) -> None:
        self.opencode_config = opencode_config
        self.controller.config.opencode = opencode_config
        self._runtime.config = opencode_config

    async def renew_runtime(self, opencode_config, *, config_save: bool = False) -> None:
        """Adopt persisted runtime config; the next turn moves to a new generation.

        Nothing reloads or drains here: running turns finish on the generation
        they started on. Every ``agents.opencode`` field is read per turn except
        the CLI path, whose binary identity is already a launch spec input, so a
        plain config save renews nothing. Credential flows, a manual Restart,
        and installs can change what a process loaded without touching a file
        the spec reads, so they renew every generation.
        """
        self._adopt_runtime_config(opencode_config)
        if not config_save:
            self._runtime.renew()
        self._schedule_reap()

    async def refresh_runtime_config(self, opencode_config, *, force: bool = False) -> None:
        """Adopt runtime config; ``force`` interrupts every generation's work first."""
        if not force:
            await self.renew_runtime(opencode_config)
            return
        self._adopt_runtime_config(opencode_config)
        await self._cancel_active_requests()
        # The interrupted work releases its bindings, and each generation
        # stops as it drains. A new turn starts on a fresh generation.
        await self._runtime.retire_all()

    async def adopt_model_hub_catalog(self) -> None:
        """Nothing to apply: each turn builds its overlay from one catalog snapshot.

        A turn whose overlay changed gets a new generation by the same rule as
        any other launch-input change.
        """

    async def reap_runtime_generations(self) -> None:
        await self._runtime.reap()
        await self._restore_left_polls()

    async def _restore_left_polls(self) -> None:
        """Restore again every durable poll a restore left for a later one.

        Startup restores each transport's polls once, so a poll a transient
        failure left would otherwise wait for the next restart.
        """
        if not self._polls_awaiting_restore:
            return
        self._polls_awaiting_restore &= set(self.sessions.get_all_active_polls())
        restore = getattr(self.controller, "restore_polls_on_ready_transports", None)
        if self._polls_awaiting_restore and callable(restore):
            try:
                await restore()
            except Exception:
                logger.warning("Restoring the OpenCode polls an earlier restore left failed", exc_info=True)

    async def shutdown_runtime(self, settle_reason: str | None = None) -> None:
        """The backend is disabled, or the service stops: stop every process now.

        A disable passes ``settle_reason``, and every forced stop settles the
        turns and Activities bound to its process with it. The core's
        backend-wide interrupt may have failed, or been skipped because the
        backend was enabled again, so this is the settlement a retry relies on.
        A previous controller's servers stop too. Admission closes, and a turn
        that raced the disable fails with the localized retired error. Raises
        while any process survives; a retry is safe at any point.
        """
        if settle_reason is not None:
            # This agent never serves again, so every later stop of its
            # processes, a retry's included, belongs to the same disable.
            self._forced_stop_reason = settle_reason
        await self._runtime.shutdown()

    async def retire_current_generation(self) -> StopOutcome | None:
        """Retire the current generation and report its confirmed outcome.

        ``None`` means no generation was running. The next turn starts a fresh
        generation either way.
        """
        outcomes = await self._runtime.retire_confirmed()
        return next(iter(outcomes.values()), None)

    async def _cancel_active_requests(self, base_session_ids: set[str] | None = None) -> None:
        """Cancel request tasks before a forced generation stop.

        Turn owners cancel foreground requests first; restored polls have no
        owner, so without this they would poll the stopped server until their
        failure limit and report a transport error for an intended interrupt.
        """
        cancelled: list[asyncio.Task] = []
        for base_session_id, task in list(self._active_requests.items()):
            if base_session_ids is not None and base_session_id not in base_session_ids:
                continue
            # Cancelling a task that is already settling could abort the
            # retirement in its cleanup.
            if task.done() or task in self._settling_request_tasks:
                continue
            state = self._steering_states.get(base_session_id)
            if state is not None and state.task is task:
                state.closing = True
            self._settling_request_tasks.add(task)
            task.add_done_callback(self._settling_request_tasks.discard)
            # Cancel without the steering lock, which the task itself may hold
            # across a native call, and without a native abort: the teardown
            # that follows ends the native run.
            task.cancel()
            cancelled.append(task)
        if cancelled:
            # Bounded like force_cancel_backend_turns: a stuck cleanup must not
            # hold the teardown, and retirement does not depend on this wait.
            # A task still settling keeps its session, as /stop and a new
            # request already wait for it, so no successor shares its record.
            await asyncio.wait(cancelled, timeout=2.0)

    async def handle_message(self, request: AgentRequest) -> None:
        lock = self._session_manager.get_session_lock(request.base_session_id)
        task: Optional[asyncio.Task] = None

        async with lock:
            existing_task = self._active_requests.get(request.base_session_id)
            if existing_task and not existing_task.done():
                logger.info(
                    "OpenCode session %s already running; cancelling before new request",
                    request.base_session_id,
                )
                req_info = self._session_manager.get_request_session(request.base_session_id)
                server = self._bound_generation(request.base_session_id)
                if req_info and server is not None:
                    await self._abort_active_request(
                        request.base_session_id,
                        existing_task,
                        req_info,
                    )
                    await self._session_manager.wait_for_session_idle(server, req_info[0], req_info[1])

                existing_task.cancel()
                try:
                    await existing_task
                except asyncio.CancelledError:
                    pass

                logger.info(
                    "OpenCode session %s cancelled; continuing with new request",
                    request.base_session_id,
                )

            task = asyncio.create_task(self._process_message(request))
            self._active_requests[request.base_session_id] = task

        if not task:
            return

        try:
            await task
        except asyncio.CancelledError:
            logger.debug(f"OpenCode task cancelled for {request.base_session_id}")
        finally:
            # Stop holds this same lock until the native abort has settled. Keep
            # the old request's Turn/session ownership until then, so a queued
            # successor cannot reuse the native session under an in-flight abort.
            async with lock:
                if self._active_requests.get(request.base_session_id) is task:
                    self._active_requests.pop(request.base_session_id, None)
                    self._session_manager.pop_request_session(request.base_session_id)
                # The poll loop ran to completion above (handle_message awaits the
                # task), so the turn is fully settled here. Release any web-Chat
                # stream waiter: a no-result failure (only a notify was emitted)
                # ends the spinner now instead of waiting out the safety timeout.
                # Token-guarded + no-op for IM/CLI; success already released via the
                # result emit during the poll. Defensive: tolerate controllers
                # without streaming completion support.
                _mark = getattr(self.controller, "mark_turn_complete", None)
                if callable(_mark):
                    _mark(request.context)

    async def _process_message(self, request: AgentRequest) -> None:
        turn = _TurnGeneration()
        try:
            await self._run_turn(request, turn)
        finally:
            generation = turn.binding.generation.runtime if turn.binding is not None else None
            if generation is not None and self._session_generations.get(request.base_session_id) is generation:
                self._session_generations.pop(request.base_session_id, None)
            await self._release_binding(turn.binding)

    async def _run_turn(self, request: AgentRequest, turn: _TurnGeneration) -> None:
        run_registered = False
        steer_state: _OpenCodeSteerState | None = None
        poll_server: _SteeringAwareOpenCodeServer | None = None
        model_hub_overlay: OpenCodeOverlay | None = None
        model_hub_config: Any = None
        model_hub_launch: ModelHubLaunch | None = None
        server = None
        # Bind early: get_or_create_session_id (below) can raise BEFORE assigning
        # session_id (a transient server error now that get_session raises on
        # non-404), and the error-cleanup paths reference session_id — keep it
        # defined so they can't trip UnboundLocalError (Codex P2).
        session_id = None
        logical_turn_id = ""
        start_attempt_id = ""
        native_start_phase = "before_write"
        activation_identity: RuntimeActivationIdentity | None = None
        caller_context_binding_session_id: str | None = None
        caller_context_binding_token: str | None = None
        caller_context_binding_path: str | None = None
        caller_context_binding_renewal: asyncio.Task[None] | None = None
        active_poll_persisted = False
        active_poll_removal_pending = False
        resource_failure: AgentResourceFailure | None = None

        def remove_active_poll() -> None:
            nonlocal active_poll_persisted, active_poll_removal_pending
            if session_id:
                active_poll_persisted = False
                active_poll_removal_pending = True
        try:
            model_hub_runtime = getattr(self.controller, "model_hub_runtime", None)
            # One Model Hub load serves this turn end to end: its overlay is a
            # launch spec input, and its model resolves from the same overlay.
            model_hub_config, model_hub_overlay, launch_spec, opencode_settings = await self._prepare_launch(
                request.context
            )
            turn.binding = await self._runtime.acquire(launch_spec)
            server = turn.binding.generation.runtime
            self._session_generations[request.base_session_id] = server
            caller_context_binding_path = _caller_context_path_for_server(server)
            activation_identity = getattr(server, "identity", None)
            await self._session_manager.ensure_working_dir(request.working_path)
            # A healthy server may still be bootstrapping this directory (about
            # a minute on a fresh host). Waiting here, before the ack is deleted,
            # keeps the turn visibly in progress and leaves session creation to
            # its ordinary request timeout.
            await server.ensure_directory_ready(request.working_path)
        except asyncio.CancelledError:
            await self._finish_prestart_cancellation(request)
            raise
        except Exception as e:
            resource_failure = self._resource_failure_for_server(server)
            logger.error(f"Failed to start OpenCode server: {e}", exc_info=True)
            await emit_backend_failure(
                self.controller,
                request.context,
                self.name,
                str(e),
                display_text=self._server_start_error_display_text(
                    e,
                    resource_failure=resource_failure,
                ),
                request=request,
            )
            await self._remove_ack_reaction(request)
            return

        try:
            await self._delete_ack(request)
        except BaseException as error:
            if isinstance(error, asyncio.CancelledError):
                await self._finish_prestart_cancellation(request)
            raise

        try:
            session_id = await self._session_manager.get_or_create_session_id(request, server)
        except asyncio.CancelledError:
            await self._finish_prestart_cancellation(request)
            raise
        except OpenCodeResumeUnavailableError as e:
            resource_failure = resource_failure or self._resource_failure_for_server(server)
            # The previous session is gone server-side — surface it as a terminal
            # ERROR result (outbound chokepoint turns the dot red), don't silently
            # fork a fresh session and lose context.
            await emit_backend_failure(
                self.controller,
                request.context,
                self.name,
                str(e),
                display_text=f"❌ {e}{self._resource_failure_suffix(resource_failure)}",
                request=request,
            )
            await self._remove_ack_reaction(request)
            return
        except Exception as e:
            resource_failure = resource_failure or self._resource_failure_for_server(server)
            # A transient/transport/auth failure while acquiring the session
            # (get_session now raises on non-404, Codex P2): surface it as a
            # terminal error result instead of letting it propagate unhandled or be
            # mislabeled as expiry. Route auth errors through the reset-OAuth flow
            # (which settles the dot itself); otherwise emit the error result here.
            logger.error(f"OpenCode session acquisition failed: {e}", exc_info=True)
            message = f"OpenCode error: {type(e).__name__}: {e}".strip()
            await emit_backend_failure(
                self.controller,
                request.context,
                self.name,
                str(e),
                display_text=f"{message}{self._resource_failure_suffix(resource_failure)}",
                request=request,
            )
            await self._remove_ack_reaction(request)
            return
        if not session_id:
            await emit_backend_failure(
                self.controller,
                request.context,
                self.name,
                "Failed to obtain OpenCode session ID",
                display_text="Failed to obtain OpenCode session ID",
                request=request,
            )
            await self._remove_ack_reaction(request)
            return

        try:
            self._session_manager.set_request_session(
                request.base_session_id,
                session_id,
                request.working_path,
                request.session_key,
            )
            self._session_manager.set_agent_session_id(
                request.base_session_id,
                _target_agent_session_id(request),
            )
        except BaseException as error:
            if isinstance(error, asyncio.CancelledError):
                await self._finish_prestart_cancellation(request)
            raise

        try:
            override_agent, override_model, override_reasoning = self.controller.get_opencode_overrides(request.context)
            override_model = request.vibe_agent_model or override_model
            override_reasoning = request.vibe_agent_reasoning_effort or override_reasoning

            override_agent = request.subagent_name or override_agent
            if request.subagent_name:
                override_model = request.subagent_model or override_model
                override_reasoning = request.subagent_reasoning_effort

            if request.subagent_name and not override_reasoning:
                override_reasoning = server.get_agent_reasoning_effort_from_config(request.subagent_name)

            agent_to_use = override_agent
            if not agent_to_use:
                agent_to_use = server.get_default_agent_from_config()

            model_dict = None
            from core.agent_model_selection import require_agent_model

            model_str = require_agent_model(
                override_model, "opencode", getattr(self.controller.config, "language", "en")
            )
            requested_model_str = opencode_requested_model_for_overlay(
                model_str,
                model_hub_overlay,
            )
            if model_hub_runtime is not None and requested_model_str:
                model_hub_launch = await resolve_opencode_overlay_launch(
                    self.controller,
                    requested_model_str,
                    model_hub_overlay,
                    context=request.context,
                    config=model_hub_config,
                )
                bind_launch(request.context, model_hub_launch)
            model_str = opencode_model_for_overlay(
                requested_model_str,
                model_hub_overlay,
            )
            # Direct mode needs an explicit provider as well as a model; Gateway
            # mode resolves the provider from Avibe's model route.
            default_provider = (
                None
                if model_hub_overlay is not None
                else getattr(opencode_settings, "default_provider", None)
            )
            model_dict = resolve_opencode_model_dict(model_str, default_provider)
            if model_dict is None:
                raise ValueError(i18n_t(
                    "errors.opencodeModelProviderRequired", getattr(self.controller.config, "language", "en")
                ))
            display_model_dict = resolve_opencode_model_dict(
                requested_model_str,
                default_provider,
            )

            reasoning_effort = override_reasoning
            if not reasoning_effort:
                reasoning_effort = server.get_agent_reasoning_effort_from_config(agent_to_use)
            if not reasoning_effort:
                reasoning_effort = getattr(opencode_settings, "default_reasoning_effort", None)
            if model_dict:
                try:
                    model_catalog = (
                        opencode_model_catalog_for_overlay(model_hub_overlay)
                        if model_hub_overlay is not None
                        else await server.get_available_models(request.working_path)
                    )
                    resolved_model_id = resolve_opencode_model_id(
                        model_catalog,
                        model_dict.get("providerID"),
                        model_dict.get("modelID"),
                    )
                    if resolved_model_id and resolved_model_id != model_dict.get("modelID"):
                        model_dict = {**model_dict, "modelID": resolved_model_id}
                    reasoning_effort = resolve_opencode_reasoning_effort(
                        model_dict,
                        reasoning_effort,
                        model_catalog,
                    )
                except Exception as err:
                    logger.debug("Failed to resolve OpenCode model variant support: %s", err)

            baseline_message_ids: set[str] = set()
            baseline_messages = None
            try:
                baseline_messages = await server.list_messages(
                    session_id=session_id,
                    directory=request.working_path,
                )
            except Exception as err:
                logger.debug(f"Failed to snapshot OpenCode messages before prompt: {err}")

            if baseline_messages is not None:
                if requires_message_order_repair(baseline_messages):
                    session_id = await self._session_manager.repair_message_order(
                        request,
                        server,
                        session_id,
                        baseline_messages,
                    )
                    self._session_manager.set_request_session(
                        request.base_session_id,
                        session_id,
                        request.working_path,
                        request.session_key,
                    )
                    baseline_messages = await server.list_messages(
                        session_id=session_id,
                        directory=request.working_path,
                    )
                for message in baseline_messages:
                    message_id = message.get("info", {}).get("id")
                    if message_id:
                        baseline_message_ids.add(message_id)

            # Prepare message with file attachment info if present
            prompt_text = self._prepare_message_with_files(request)
            platform = (
                request.context.platform
                or (request.context.platform_specific or {}).get("platform")
                or self.controller.config.platform
            )

            # Bind this turn's caller identity to the backend process.
            caller_context_env = caller_env_for_platform_payload(
                request.context.platform_specific or {},
                message=request.context,
                fallback_platform=platform,
            )

            project_base = managed_skill_project_base(request.context)
            managed_skills_env = managed_skill_environment(
                request.working_path,
                project_base=project_base,
            )
            binding_extra_env = {**caller_context_env, **managed_skills_env}
            binding_token = secrets.token_hex(16)
            binding_payload = request.context.platform_specific or {}
            binding_bound = False
            try:
                binding_bound = await asyncio.to_thread(
                    bind_caller_context_session,
                    session_id,
                    binding_payload,
                    base_env=os.environ,
                    working_dir=request.working_path,
                    extra_env=binding_extra_env,
                    binding_token=binding_token,
                    **_binding_path_kwargs(caller_context_binding_path),
                    # The creation origin travels with the identity: an OpenCode shell
                    # command running ``vibe task add`` sources this binding, and it is
                    # the only place the conversation behind the definition is visible.
                    message=request.context,
                    fallback_platform=platform,
                )
            except Exception:
                logger.warning(
                    "Starting OpenCode turn without caller context for session %s",
                    session_id,
                    exc_info=True,
                )
            caller_context_binding_session_id = session_id
            caller_context_binding_token = binding_token
            caller_context_binding_renewal = asyncio.create_task(
                self._maintain_caller_context_binding(
                    session_id,
                    binding_token,
                    caller_context_binding_path,
                    payload=binding_payload,
                    working_directory=request.working_path,
                    extra_env=binding_extra_env,
                    initially_bound=bool(binding_bound),
                    message=request.context,
                    fallback_platform=platform,
                )
            )

            skill_catalog_sink: list[dict] = []
            system_prompt_injection = await asyncio.to_thread(
                build_system_prompt_injection,
                agent_instructions=request.vibe_agent_system_prompt or "",
                include_quick_replies=getattr(self.controller.config, "reply_enhancements", True)
                and platform != "wechat",
                context=request.context,
                fallback_platform=platform,
                enabled_agents=get_enabled_agents_for_prompt(self.controller),
                skills_cwd=request.working_path if binding_bound else None,
                skills_project_base=project_base,
                skill_catalog_sink=skill_catalog_sink,
            )
            raw_settings_key = _raw_settings_key_from_session_key(request.session_key)
            platform_payload = request.context.platform_specific or {}
            logical_turn_id = str(platform_payload.get("turn_token") or "").strip()
            start_attempt_id = str(
                platform_payload.get("delivery_start_attempt_id") or ""
            ).strip()
            processing_indicator = self.controller.processing_indicator.snapshot_request(
                request
            )
            if caller_context_env:
                processing_indicator[_CALLER_CONTEXT_ENV_SNAPSHOT_KEY] = validated_caller_env_snapshot(caller_context_env)
            if project_base:
                processing_indicator[_MANAGED_SKILL_PROJECT_BASE_SNAPSHOT_KEY] = project_base
            if BUILTIN_SKILLS_ROOT_ENV in managed_skills_env:
                processing_indicator[_MANAGED_SKILL_BUILTIN_CATALOG_KEY] = {
                    "root": managed_skills_env[BUILTIN_SKILLS_ROOT_ENV],
                }
            target_session_id = _target_agent_session_id(request)
            if target_session_id and logical_turn_id:
                processing_indicator[_STEERING_SNAPSHOT_KEY] = {
                    "target_session_id": target_session_id,
                    "logical_turn_id": logical_turn_id,
                    "agent": agent_to_use,
                    "system": system_prompt_injection,
                }
            if start_attempt_id:
                processing_indicator["delivery_start_attempt_id"] = start_attempt_id
            launch_identity = persisted_launch_identity(model_hub_launch)
            if launch_identity is not None:
                processing_indicator["model_hub_launch"] = launch_identity
            if display_model_dict is not None:
                processing_indicator[_MODEL_HUB_DISPLAY_MODEL_KEY] = display_model_dict
            # A restored poll resumes on the process that runs this native turn.
            processing_indicator[_GENERATION_SNAPSHOT_KEY] = server.generation_id

            await server.mark_run_active(session_id)
            run_registered = True
            # Persist the complete recovery address before the first native write.
            # A crash after OpenCode accepts the exact attempt part can now rebuild
            # the poll and Turn owner even if no post-prompt Python statement ran.
            self.sessions.add_active_poll(
                opencode_session_id=session_id,
                base_session_id=request.base_session_id,
                channel_id=request.context.channel_id,
                thread_id=request.context.thread_id,
                settings_key=raw_settings_key,
                working_path=request.working_path,
                baseline_message_ids=list(baseline_message_ids),
                ack_reaction_message_id=request.ack_reaction_message_id,
                ack_reaction_emoji=request.ack_reaction_emoji,
                typing_indicator_active=request.typing_indicator_active,
                context_token=str(platform_payload.get("context_token") or ""),
                processing_indicator=processing_indicator,
                user_id=request.context.user_id or "",
                platform=request.context.platform or platform_payload.get("platform") or "",
                prompt_started_at=None,
                model_dict=model_dict,
                reasoning_effort=reasoning_effort,
                session_key=request.session_key,
            )
            active_poll_persisted = True
            prompt_text = self.render_input(prompt_text, getattr(request, "input_metadata", None))
            mark_backend_dispatch_attempted(request.context)
            native_start_phase = "may_have_written"
            await server.prompt_async(
                session_id=session_id,
                directory=request.working_path,
                text=prompt_text,
                attempt_id=start_attempt_id or None,
                agent=agent_to_use,
                model=model_dict,
                reasoning_effort=reasoning_effort,
                system=system_prompt_injection,
                tools={"question": False, "skill": False},
            )
            from core.skill_observability import accept_catalog

            accept_catalog(self.controller, request.context, skill_catalog_sink[0] if skill_catalog_sink else None, backend="opencode")
            try:
                read_prompt_started_at = getattr(server, "get_last_prompt_started_at", None)
                prompt_started_at = (
                    read_prompt_started_at(session_id)
                    if callable(read_prompt_started_at)
                    else None
                ) or time.time()
                update_active_poll = getattr(
                    self.sessions,
                    "update_active_poll_state",
                    None,
                )
                if callable(update_active_poll):
                    update_active_poll(
                        session_id,
                        prompt_started_at=prompt_started_at,
                    )
            except Exception:
                # The pre-write active-poll record remains a safe recovery fallback:
                # its started_at is only moments older than native acceptance. Do not
                # fail a live accepted Turn because this timestamp refinement failed.
                logger.warning(
                    "Failed to persist OpenCode prompt start time for %s",
                    session_id,
                    exc_info=True,
                )
            current_task = asyncio.current_task()
            if current_task is None:
                raise RuntimeError("OpenCode runner task is unavailable")
            steer_state = _OpenCodeSteerState(
                task=current_task,
                base_session_id=request.base_session_id,
                target_session_id=target_session_id,
                logical_turn_id=logical_turn_id,
                native_session_id=session_id,
                directory=request.working_path,
                agent=agent_to_use,
                model=model_dict,
                reasoning_effort=reasoning_effort,
                system=system_prompt_injection,
                baseline_message_ids=set(baseline_message_ids),
                generation=server,
                catalog_accepted=lambda: accept_catalog(
                    self.controller, request.context, skill_catalog_sink[0] if skill_catalog_sink else None,
                    backend="opencode",
                ),
                awaiting_after_message_ids=set(baseline_message_ids),
                awaiting_user_text=prompt_text,
                awaiting_prompt_accepted=True,
                awaiting_prompt_activity_deadline=(
                    time.monotonic()
                    + _ASYNC_PROMPT_ACCEPTED_ACTIVITY_TIMEOUT_SECONDS
                ),
                idle_reconciliation_message=self._idle_reconciliation_message(
                    display_model_dict,
                    reasoning_effort,
                ),
            )
            self._steering_states[request.base_session_id] = steer_state
            self.mark_runtime_turn_started(
                request.context,
                activation_identity=activation_identity,
            )
            native_start_phase = "accepted"

            logger.info(
                "Starting OpenCode poll loop for %s (thread=%s, cwd=%s)",
                session_id,
                request.base_session_id,
                request.working_path,
            )

            poll_server = _SteeringAwareOpenCodeServer(
                server,
                steer_state,
            )
            final_text, should_emit = await self._poll_loop.run_prompt_poll(
                request,
                poll_server,
                session_id,
                agent_to_use=agent_to_use,
                model_dict=model_dict,
                reasoning_effort=reasoning_effort,
                baseline_message_ids=baseline_message_ids,
                settings=opencode_settings,
            )

            if not should_emit:
                remove_active_poll()
                await self._remove_ack_reaction(request)
                return

            if final_text:
                await self.emit_result_message(
                    request.context,
                    final_text,
                    subtype="success",
                    started_at=request.started_at,
                    parse_mode="markdown",
                    request=request,
                )
            else:
                await self.emit_result_message(
                    request.context,
                    "(No response from OpenCode)",
                    subtype="warning",
                    started_at=request.started_at,
                    request=request,
                )

            self._maybe_backfill_session_title(request, session_id, retry_delay_seconds=3.0)
            remove_active_poll()

        except asyncio.CancelledError:
            logger.info(f"OpenCode request cancelled for {request.base_session_id}")
            # A /stop is silent by design, so the ⏹️ replacing the 👀 is the only
            # thing that tells the user this turn ended on their command. Every
            # other cancellation (shutdown, clear_sessions, supersede) leaves the
            # plain removal, because none of those are the user's doing.
            await self._remove_ack_reaction(
                request,
                terminal_emoji=(
                    STOPPED_REACTION_EMOJI
                    if self._claim_user_stop_receipt(request)
                    else None
                ),
            )
            if session_id:
                remove_active_poll()
            raise
        except OpenCodePromptRejectedError as e:
            error_text = f"{type(e).__name__}: {e}"
            resource_failure = resource_failure or self._resource_failure_for_server(server)
            logger.error("OpenCode prompt was definitively rejected: %s", e)

            poll_can_be_removed = not (logical_turn_id and start_attempt_id)
            if logical_turn_id and start_attempt_id:
                session_turns = getattr(self.controller, "session_turns", None)
                try:
                    if e.is_permanent_input_rejection:
                        settle_invalid = getattr(
                            session_turns,
                            "settle_start_attempt_invalid_input",
                            None,
                        )
                        if callable(settle_invalid):
                            poll_can_be_removed = bool(
                                settle_invalid(
                                    logical_turn_id,
                                    start_attempt_id,
                                    backend=self.name,
                                )
                            )
                    else:
                        reconcile = getattr(
                            session_turns,
                            "reconcile_start_attempt_not_written",
                            None,
                        )
                        if callable(reconcile):
                            poll_can_be_removed = bool(
                                reconcile(
                                    logical_turn_id,
                                    start_attempt_id,
                                    backend=self.name,
                                )
                            )
                except Exception:
                    logger.exception(
                        "Failed to persist definitive rejected OpenCode start "
                        "for Turn=%s; preserving its active poll",
                        logical_turn_id,
                    )

            await self._remove_ack_reaction(request)
            if session_id and poll_can_be_removed:
                remove_active_poll()

            await self.record_model_hub_native_failure(request.context, error_text)
            await emit_backend_failure(
                self.controller,
                request.context,
                self.name,
                error_text,
                display_text=(
                    f"OpenCode request failed: {error_text}"
                    f"{self._resource_failure_suffix(resource_failure)}"
                ),
                request=request,
            )
        except Exception as e:
            error_name = type(e).__name__
            error_details = str(e).strip()
            error_text = f"{error_name}: {error_details}" if error_details else error_name

            resource_failure = resource_failure or self._resource_failure_for_server(server)
            logger.error(f"OpenCode request failed: {error_text}", exc_info=True)
            await self.record_model_hub_native_failure(request.context, error_text)
            try:
                abort_server = poll_server or server
                await abort_server.abort_session(session_id, request.working_path)
            except Exception as abort_err:
                logger.warning(f"Failed to abort OpenCode session after error: {abort_err}")

            await self._remove_ack_reaction(request)
            if session_id and native_start_phase != "may_have_written":
                remove_active_poll()
            elif session_id:
                logger.warning(
                    "Preserving OpenCode active poll after ambiguous native start "
                    "failure for Turn=%s attempt=%s",
                    logical_turn_id,
                    start_attempt_id,
                )

            refusal = launch_refusal_copy(self.controller, e)
            if refusal is not None:
                display_text = f"❌ {refusal}"
            else:
                display_text = (
                    f"OpenCode request failed: {error_text}"
                    f"{self._resource_failure_suffix(resource_failure)}"
                )
            await emit_backend_failure(
                self.controller,
                request.context,
                self.name,
                error_text,
                display_text=display_text,
                request=request,
                cause=e,
            )
        finally:
            await self._stop_caller_context_binding_renewal(
                caller_context_binding_renewal
            )
            if steer_state is not None:
                async with steer_state.lock:
                    steer_state.closing = True
                if self._steering_states.get(request.base_session_id) is steer_state:
                    self._steering_states.pop(request.base_session_id, None)
            if active_poll_removal_pending and run_registered:
                active_poll_persisted = not await self._retire_active_poll(
                    server,
                    session_id,
                )
            elif active_poll_removal_pending and session_id:
                self.sessions.remove_active_poll(session_id)
                active_poll_persisted = False
            if (
                caller_context_binding_session_id
                and caller_context_binding_token
                and not active_poll_persisted
            ):
                try:
                    await asyncio.to_thread(
                        unbind_caller_context_session,
                        caller_context_binding_session_id,
                        binding_token=caller_context_binding_token,
                        **_binding_path_kwargs(caller_context_binding_path),
                    )
                except Exception:
                    logger.warning(
                        "Failed to unbind OpenCode caller context for session %s",
                        caller_context_binding_session_id,
                        exc_info=True,
                    )

    async def _retire_active_poll(
        self,
        server: Any,
        session_id: str,
    ) -> bool:
        try:
            await server.mark_run_inactive(session_id)
        except Exception:
            logger.exception(
                "Failed to clear OpenCode run marker for session=%s; preserving its active poll",
                session_id,
            )
            return False
        self.sessions.remove_active_poll(session_id)
        # A retiring generation may have just drained.
        self._schedule_reap()
        return True

    async def _finish_prestart_cancellation(self, request: AgentRequest) -> None:
        await self._remove_ack_reaction(
            request,
            terminal_emoji=(
                STOPPED_REACTION_EMOJI
                if self._claim_user_stop_receipt(request)
                else None
            ),
        )

    def _claim_user_stop_receipt(self, request: AgentRequest) -> bool:
        """Recognize adapter-local and shared prewrite Stop ownership."""

        return self.consume_user_stop_intent(
            request.base_session_id
        ) or prewrite_user_stop_requested(request.context)

    def additional_steer_targets(self, session_id: str) -> list[ActiveSteerTarget]:
        """Expose restored poll owners that did not pass through AgentService."""

        targets: list[ActiveSteerTarget] = []
        for state in list(self._steering_states.values()):
            if not state.restored or state.target_session_id != session_id or not state.logical_turn_id:
                continue
            targets.append(
                ActiveSteerTarget(
                    runtime_key=state.base_session_id,
                    logical_turn_id=state.logical_turn_id,
                    context=None,
                    agent_request=None,
                    agent=self,
                )
            )
        return targets

    def steering_native_turn_id(self, target: ActiveSteerTarget) -> Optional[str]:
        active_request = target.agent_request
        base_session_id = active_request.base_session_id if active_request is not None else target.runtime_key
        task = self._active_requests.get(base_session_id)
        state = self._steering_states.get(base_session_id)
        if (
            task is None
            or _task_is_stopping(task)
            or state is None
            or state.task is not task
            or state.closing
        ):
            return None
        return state.native_turn_id

    async def steer_active_turn(
        self,
        request: SteerRequest,
        target: ActiveSteerTarget,
    ) -> SteerResult:
        active_request = target.agent_request
        base_session_id = active_request.base_session_id if active_request is not None else target.runtime_key
        task = self._active_requests.get(base_session_id)
        request_session = self._session_manager.get_request_session(base_session_id)
        state = self._steering_states.get(base_session_id)
        if task is None or _task_is_stopping(task) or request_session is None or state is None:
            return steer_result(SteerOutcome.NOT_ACTIVE, reason="no_active_native_run", backend=self.name)

        native_session_id, directory, _session_key = request_session
        native_turn_id = state.native_turn_id
        if native_turn_id != request.expected_native_turn_id:
            return steer_result(SteerOutcome.NOT_ACTIVE, reason="stale_native_turn", backend=self.name)

        # Status, prompts, and aborts act on one process's in-memory run state,
        # so a steer goes to the generation that runs this native turn.
        server = state.generation
        if server is None:
            return steer_result(SteerOutcome.REFUSED, reason="runtime_unavailable", backend=self.name)

        try:
            async with state.lock:
                if (
                    state.closing
                    or state.task is not task
                    or self._active_requests.get(base_session_id) is not task
                    or _task_is_stopping(task)
                    or self._session_manager.get_request_session(base_session_id) != request_session
                ):
                    return steer_result(
                        SteerOutcome.NOT_ACTIVE,
                        reason="no_active_native_run",
                        backend=self.name,
                    )
                try:
                    messages = await server.list_messages(native_session_id, directory)
                    status = await server.get_session_status(native_session_id, directory)
                except (asyncio.TimeoutError, TimeoutError, aiohttp.ClientConnectionError) as exc:
                    return steer_result(
                        SteerOutcome.REFUSED,
                        reason="preflight_unavailable",
                        backend=self.name,
                        diagnostic=str(exc),
                    )
                except Exception as exc:  # noqa: BLE001 - no input write was attempted
                    return steer_result(
                        SteerOutcome.REFUSED,
                        reason="preflight_failed",
                        backend=self.name,
                        diagnostic=str(exc),
                    )

                if status is None or status.get("type") not in {"busy", "retry"}:
                    return steer_result(
                        SteerOutcome.NOT_ACTIVE,
                        reason="native_session_idle",
                        backend=self.name,
                    )
                before_insert = _SteeringAwareOpenCodeServer._message_ids(messages)
                prompt_text = self.render_input(message_with_files(request.text, request.files), request.input_metadata)
                try:
                    prompt_kwargs = {
                        "session_id": native_session_id,
                        "directory": directory,
                        "text": prompt_text,
                        "agent": state.agent,
                        "model": state.model,
                        "reasoning_effort": state.reasoning_effort,
                        "system": state.system,
                        "tools": {"question": False, "skill": False},
                    }
                    if request.attempt_id:
                        prompt_kwargs["attempt_id"] = request.attempt_id
                    await server.prompt_async(
                        **prompt_kwargs,
                    )
                except aiohttp.ClientConnectorError:
                    raise
                except (asyncio.TimeoutError, TimeoutError, aiohttp.ClientConnectionError):
                    state.awaiting_after_message_ids = before_insert
                    state.awaiting_user_text = prompt_text
                    state.awaiting_prompt_accepted = False
                    state.awaiting_prompt_activity_deadline = None
                    state.awaiting_active_status_observed = False
                    raise
                state.awaiting_after_message_ids = before_insert
                state.awaiting_user_text = prompt_text
                state.awaiting_prompt_accepted = True
                if state.catalog_accepted:
                    state.catalog_accepted()
                state.awaiting_prompt_activity_deadline = (
                    time.monotonic()
                    + _ASYNC_PROMPT_ACCEPTED_ACTIVITY_TIMEOUT_SECONDS
                )
                state.awaiting_active_status_observed = False
                await asyncio.sleep(_STEER_POST_WRITE_STATUS_SETTLE_SECONDS)
                try:
                    status_after_write = await server.get_session_status(
                        native_session_id,
                        directory,
                    )
                except (asyncio.TimeoutError, TimeoutError, aiohttp.ClientConnectionError) as exc:
                    # The native write may have been accepted, so leave the
                    # reconciliation evidence armed for the poll owner.
                    return steer_result(
                        SteerOutcome.UNKNOWN,
                        reason="post_write_status_unknown",
                        backend=self.name,
                        diagnostic=str(exc),
                    )
                except Exception as exc:  # noqa: BLE001 - write already happened
                    return steer_result(
                        SteerOutcome.UNKNOWN,
                        reason="post_write_status_unknown",
                        backend=self.name,
                        diagnostic=str(exc),
                    )
                if (
                    status_after_write is None
                    or status_after_write.get("type") not in {"busy", "retry"}
                ):
                    # The prompt write is durable, but OpenCode can take longer
                    # than this first status sample to register the continuation as
                    # busy. Keep the five-second reconciliation evidence armed so
                    # the poll owner can observe either start confirmation or the
                    # exact native attempt before any retry is admitted.
                    return steer_result(
                        SteerOutcome.UNKNOWN,
                        reason="native_turn_start_pending",
                        backend=self.name,
                    )
        except OpenCodePromptRejectedError as exc:
            outcome = SteerOutcome.NOT_ACTIVE if exc.status == 404 else SteerOutcome.REFUSED
            reason = "native_session_missing" if exc.status == 404 else "backend_refused"
            return steer_result(
                outcome,
                reason=reason,
                backend=self.name,
                status=exc.status,
                diagnostic=exc.response_text,
            )
        except aiohttp.ClientConnectorError as exc:
            return steer_result(
                SteerOutcome.REFUSED,
                reason="runtime_unavailable",
                backend=self.name,
                diagnostic=str(exc),
            )
        except (asyncio.TimeoutError, TimeoutError, aiohttp.ClientConnectionError) as exc:
            return steer_result(
                SteerOutcome.UNKNOWN,
                reason="acknowledgement_ambiguous",
                backend=self.name,
                diagnostic=str(exc),
            )
        except Exception as exc:  # noqa: BLE001 - a response is a definitive rejection
            return steer_result(
                SteerOutcome.REFUSED,
                reason="backend_refused",
                backend=self.name,
                diagnostic=str(exc),
            )

        if self._active_requests.get(base_session_id) is not task or _task_is_stopping(task):
            return steer_result(
                SteerOutcome.UNKNOWN,
                reason="runner_generation_changed",
                backend=self.name,
            )
        return steer_result(
            SteerOutcome.ACCEPTED,
            backend=self.name,
            native_session_id=native_session_id,
            runner_generation=native_turn_id,
        )

    async def reconcile_steer_attempt(
        self,
        request: SteerReconcileRequest,
        target: ActiveSteerTarget,
    ) -> SteerResult:
        """Resolve one prior OpenCode write by its exact native part identity."""

        if not request.attempt_id:
            return steer_result(
                SteerOutcome.UNKNOWN,
                reason="missing_attempt_identity",
                backend=self.name,
            )
        active_request = target.agent_request
        base_session_id = (
            active_request.base_session_id
            if active_request is not None
            else target.runtime_key
        )
        request_session = self._session_manager.get_request_session(base_session_id)
        if request_session is None:
            return steer_result(
                SteerOutcome.UNKNOWN,
                reason="native_session_unavailable",
                backend=self.name,
            )
        native_session_id, directory, _session_key = request_session
        if not request.expected_native_turn_id.startswith(f"opencode:{native_session_id}:"):
            return steer_result(
                SteerOutcome.UNKNOWN,
                reason="stale_native_session",
                backend=self.name,
            )
        # The part lives in the shared database, so any generation can find it.
        server = self._bound_generation(base_session_id) or self._runtime.current()
        if server is None:
            return steer_result(
                SteerOutcome.UNKNOWN,
                reason="runtime_unavailable",
                backend=self.name,
            )
        native_part_id = native_part_id_for_attempt(request.attempt_id)
        try:
            messages = await server.list_messages(
                native_session_id,
                directory,
            )
        except Exception as exc:  # noqa: BLE001 - absence is not negative proof
            return steer_result(
                SteerOutcome.UNKNOWN,
                reason="attempt_evidence_unavailable",
                backend=self.name,
                diagnostic=str(exc),
            )
        for message in messages:
            info = message.get("info") if isinstance(message, dict) else None
            parts = message.get("parts") if isinstance(message, dict) else None
            if (
                isinstance(info, dict)
                and info.get("role") == "user"
                and isinstance(parts, list)
                and any(
                    isinstance(part, dict)
                    and str(part.get("id") or "") == native_part_id
                    for part in parts
                )
            ):
                return steer_result(
                    SteerOutcome.ACCEPTED,
                    reason="native_attempt_part_found",
                    backend=self.name,
                    native_message_id=str(info.get("id") or ""),
                    native_part_id=native_part_id,
                )
        return steer_result(
            SteerOutcome.UNKNOWN,
            reason="untrusted_attempt_evidence",
            backend=self.name,
        )

    def consume_user_stop_intent(self, base_session_id: str) -> bool:
        """Let the cancelled request coroutine claim its /stop receipt once."""

        if not base_session_id or base_session_id not in self._user_stopped_sessions:
            return False
        self._user_stopped_sessions.discard(base_session_id)
        return True

    async def handle_stop(self, request: AgentRequest) -> bool:
        lock = self._session_manager.get_session_lock(request.base_session_id)
        async with lock:
            # Read the task only after claiming the same ownership boundary used
            # to start and retire requests. A result that completed while Stop
            # waited for the lock remains authoritative.
            task = self._active_requests.get(request.base_session_id)
            if not task or task.done():
                request.stop_failure_reason = "not_active"
                return False

            req_info = self._session_manager.get_request_session(request.base_session_id)
            opencode_session_id = None
            if req_info:
                opencode_session_id = req_info[0]
            # Read before the task settles: its cleanup unbinds the generation.
            generation = self._bound_generation(request.base_session_id)
            # Claimed BEFORE the abort: the request coroutine is what owns the 👀,
            # and its cancellation handler is the only place that trades it for the
            # ⏹️ receipt. The helper waits for any already-started steering write,
            # then cancels under that same lock before awaiting the native abort.
            self._user_stopped_sessions.add(request.base_session_id)
            cancellation_claimed = False
            try:
                try:
                    cancellation_claimed = await self._abort_active_request(
                        request.base_session_id,
                        task,
                        req_info,
                        cancel_before_abort=True,
                    )
                except Exception as e:
                    logger.warning(f"Failed to abort OpenCode session: {e}")
                    cancellation_claimed = task.cancelling() > 0 or task.cancelled()

                if not cancellation_claimed:
                    # The runner completed while Stop was waiting for a steering
                    # write. Its result/error is authoritative; do not append a
                    # stopped receipt or a silent cancellation settlement.
                    logger.info(
                        "OpenCode session %s completed before /stop claimed it",
                        request.base_session_id,
                    )
                    return True

                try:
                    await task
                except asyncio.CancelledError:
                    pass
            finally:
                # Only reached with the intent still set if something above raised
                # past the handlers; a claimed intent is already gone.
                self._user_stopped_sessions.discard(request.base_session_id)

            if (
                opencode_session_id
                and generation is not None
                and self._active_poll_is_persisted(opencode_session_id)
            ):
                await self._retire_active_poll(generation, opencode_session_id)

            # A user-initiated stop is terminal but intentional, so it carries NO
            # user-facing message: a single SILENT result settles the dot to idle +
            # releases the SSE waiter through the outbound chokepoint without a bubble
            # (``level="silent"`` makes that explicit rather than faking it via empty text).
            # A ``STOPPED`` end (not the terminal-turn default) keeps this empty body out
            # of the run's terminal state so the stop settles it ``canceled`` instead of
            # ``succeeded`` (``stop_output_for`` explains why).
            await emit_output(
                self.controller,
                request.context,
                TurnEnd(outcome=TurnOutcome.STOPPED, silent=True, output=terminal_output_for(request)),
            )
            logger.info(f"OpenCode session {request.base_session_id} terminated via /stop")
            return True

    async def clear_sessions(self, session_key: str) -> int:
        self.sessions.clear_agent_sessions(session_key, self.name)
        terminated = 0
        for base_id, task in list(self._active_requests.items()):
            req_info = self._session_manager.get_request_session(base_id)
            if req_info and len(req_info) >= 3 and req_info[2] == session_key:
                opencode_session_id = req_info[0]
                generation = self._bound_generation(base_id)
                if not task.done():
                    try:
                        await self._abort_active_request(base_id, task, req_info)
                    except Exception:
                        pass
                    task.cancel()
                    try:
                        await task
                    except asyncio.CancelledError:
                        pass
                    terminated += 1
                if generation is not None and self._active_poll_is_persisted(opencode_session_id):
                    await self._retire_active_poll(generation, opencode_session_id)
        return terminated

    async def _abort_active_request(
        self,
        base_session_id: str,
        task: asyncio.Task,
        request_session: tuple[str, str, str] | None,
        *,
        cancel_before_abort: bool = False,
    ) -> bool:
        # Only the process running the native turn can abort it. Without a bound
        # generation no native run exists yet.
        server = self._bound_generation(base_session_id)
        state = self._steering_states.get(base_session_id)
        if state is not None and state.task is task:
            async with state.lock:
                state.closing = True
                if cancel_before_abort:
                    if task.done():
                        return False
                    task.cancel()
                if request_session and server is not None:
                    await server.abort_session(request_session[0], request_session[1])
            return True
        if cancel_before_abort:
            if task.done():
                return False
            task.cancel()
        if request_session and server is not None:
            await server.abort_session(request_session[0], request_session[1])
        return True

    def runtime_turn_keys_for_session_key(self, session_key: str) -> set[str]:
        return {
            f"{base_id}:{req_info[1]}"
            for base_id, req_info in self._session_manager.list_for_session_key(session_key).items()
        }

    def runtime_turn_keys(self) -> set[str]:
        return {
            f"{base_id}:{req_info[1]}"
            for base_id, req_info in self._session_manager.list_all().items()
        }

    async def _delete_ack(self, request: AgentRequest) -> None:
        service = getattr(self.controller, "processing_indicator", None)
        if service is not None:
            await service.delete_ack_message(request)
            return
        ack_id = request.ack_message_id
        if ack_id and hasattr(self.im_client, "delete_message"):
            try:
                await self.im_client.delete_message(request.context.channel_id, ack_id)
            except Exception as err:
                logger.debug("Could not delete ack message: %s", err)
            finally:
                request.ack_message_id = None

    # _remove_ack_reaction is inherited from BaseAgent

    @staticmethod
    def _workbench_session_id_for_poll(poll_info) -> Optional[str]:
        """Resolve the avibe workbench session id a restored poll belongs to, or
        ``None`` for an IM poll.

        Mirrors how the inbound chokepoint resolves it
        (``Controller._session_id_from_context`` reads
        ``platform_specific["agent_session_id"]``): for an avibe turn the dispatch
        stamps ``agent_session_id`` = the workbench session PK, which equals the
        session's anchor and therefore the OpenCode ``base_session_id`` the poll
        ran under (see ``internal_server._build_session_context`` +
        ``SessionHandler.get_base_session_id``). The persisted poll snapshot does
        not carry ``agent_session_id``, so we recover it from ``base_session_id``
        for avibe polls only — IM polls return ``None`` and get no status dot.
        """
        if restored_platform_from_poll_info(poll_info) != "avibe":
            return None
        base_session_id = poll_info.base_session_id or ""
        return base_session_id or None

    async def restore_active_polls(self, platforms: set[str] | None = None) -> int:
        """Restore active poll loops that were interrupted by vibe-remote restart.

        Callers pass only platforms whose transport can deliver. Overlapping
        calls run one after another, so a poll whose loop one of them started
        is seen as running by the next and never gets a second loop.
        """

        async with self._restore_lock:
            handed_off: list[_RestoredPollHandoff] = []
            try:
                return await self._restore_active_polls(platforms, handed_off)
            finally:
                await self._abandon_unpublished_polls(handed_off)

    async def _abandon_unpublished_polls(self, handed_off: list["_RestoredPollHandoff"]) -> None:
        """Cancel every poll task a restore handed off but never published.

        A restore that ends early, cancelled or failing, would leave each such
        task waiting for a publication that never comes, holding its request
        and binding. Cancelled before its poll loop starts, the task releases
        both, and the poll stays durable for the sweep's next restore.
        """

        abandoned: list[asyncio.Task] = []
        for handoff in handed_off:
            if handoff.published.is_set():
                continue
            self._polls_awaiting_restore.add(handoff.poll_info.opencode_session_id)
            handoff.task.cancel()
            abandoned.append(handoff.task)
        if abandoned:
            # Bounded like a forced stop's cancellation: a stuck cleanup must
            # not hold the restore lock, and each task still finishes its own.
            await asyncio.wait(abandoned, timeout=2.0)

    async def _restore_active_polls(
        self,
        platforms: set[str] | None,
        restoration_results: list["_RestoredPollHandoff"],
    ) -> int:
        active_polls = self.sessions.get_all_active_polls()
        if not active_polls:
            logger.debug("No active polls to restore")
            return 0
        # A run another desktop Runtime's live process executes is that
        # Runtime's: its poll is never bound, rewritten, or settled here.
        foreign_records = await asyncio.to_thread(other_runtimes_live_records)

        restored_count = 0
        stale_poll_ids = []

        for session_id, poll_info in active_polls.items():
            poll_platform = restored_platform_from_poll_info(poll_info)
            if platforms is not None and poll_platform not in platforms:
                continue
            existing_task = self._active_requests.get(poll_info.base_session_id)
            if existing_task is not None and not existing_task.done():
                continue
            if _poll_runs_in(poll_info, foreign_records):
                logger.info(
                    "Leaving OpenCode poll %s to the desktop Runtime whose server runs it",
                    session_id,
                )
                continue
            self._polls_awaiting_restore.discard(session_id)
            processing_snapshot = (
                poll_info.processing_indicator
                if isinstance(poll_info.processing_indicator, dict)
                else {}
            )
            start_attempt_id = str(
                processing_snapshot.get("delivery_start_attempt_id") or ""
            ).strip()
            steering_snapshot = processing_snapshot.get(_STEERING_SNAPSHOT_KEY)
            logical_turn_id = (
                str(steering_snapshot.get("logical_turn_id") or "").strip()
                if isinstance(steering_snapshot, dict)
                else ""
            )
            verification_unknown = False
            binding: RuntimeBinding | None = None
            server: OpenCodeGeneration | None = None
            try:
                try:
                    binding = await self._bind_restored_poll(poll_info)
                    server = binding.generation.runtime
                    messages = await server.list_messages(
                        session_id=poll_info.opencode_session_id,
                        directory=poll_info.working_path,
                    )
                except RuntimeUnitStopping:
                    # OpenCode was disabled while restoring: the poll stays durable
                    # for the next controller that has OpenCode enabled.
                    continue
                except _RestoredPollUnrecorded:
                    # Still naming its old process, the poll waits for a later restore.
                    self._polls_awaiting_restore.add(session_id)
                    continue
                except Exception as err:
                    logger.warning(f"Failed to verify OpenCode session {session_id} for restoration: {err}")
                    messages = []
                    verification_unknown = True

                baseline_message_ids = set(poll_info.baseline_message_ids)
                start_attempt_part_id = (
                    native_part_id_for_attempt(start_attempt_id)
                    if start_attempt_id
                    else ""
                )
                start_attempt_found = any(
                    start_attempt_part_id
                    and message.get("info", {}).get("role") == "user"
                    and any(
                        isinstance(part, dict)
                        and str(part.get("id") or "") == start_attempt_part_id
                        for part in (message.get("parts") or [])
                    )
                    for message in messages
                )
                has_in_progress = False
                last_assistant_finish = None
                last_completed_assistant_index = -1
                for index, message in enumerate(messages):
                    info = message.get("info", {})
                    if info.get("role") != "assistant":
                        continue
                    time_info = info.get("time") or {}
                    if not time_info.get("completed"):
                        has_in_progress = True
                        continue
                    if info.get("id") in baseline_message_ids:
                        continue
                    last_completed_assistant_index = index
                    last_assistant_finish = info.get("finish")

                has_post_assistant_user = any(
                    last_completed_assistant_index >= 0
                    and index > last_completed_assistant_index
                    and message.get("info", {}).get("role") == "user"
                    and message.get("info", {}).get("id") not in baseline_message_ids
                    for index, message in enumerate(messages)
                )
                reconcile_after_message_ids = (
                    {
                        str(message.get("info", {}).get("id"))
                        for message in messages[: last_completed_assistant_index + 1]
                        if message.get("info", {}).get("id")
                    }
                    if has_post_assistant_user
                    else None
                )
                status_unknown = verification_unknown
                native_status = None
                if not verification_unknown:
                    try:
                        native_status = await server.get_session_status(
                            poll_info.opencode_session_id,
                            poll_info.working_path,
                        )
                    except Exception as err:
                        logger.debug("Failed to read OpenCode status while restoring %s: %s", session_id, err)
                        status_unknown = True

                native_status_is_active = (
                    native_status is not None
                    and native_status.get("type") in {"busy", "retry"}
                )
                if native_status_is_active and reconcile_after_message_ids is None:
                    reconcile_after_message_ids = {
                        str(message.get("info", {}).get("id"))
                        for message in messages[: last_completed_assistant_index + 1]
                        if message.get("info", {}).get("id")
                    }
                session_still_active = (
                    status_unknown
                    or native_status_is_active
                    or has_in_progress
                    or last_assistant_finish == "tool-calls"
                    or has_post_assistant_user
                    or start_attempt_found
                )
                if not session_still_active:
                    if start_attempt_id and logical_turn_id:
                        try:
                            self.controller.session_turns.reconcile_start_attempt_not_written(
                                logical_turn_id,
                                start_attempt_id,
                                backend="opencode",
                            )
                        except Exception:
                            logger.exception(
                                "Failed to persist definitive missing OpenCode start "
                                "attempt for Turn=%s",
                                logical_turn_id,
                            )
                            await self._release_binding(binding)
                            self._polls_awaiting_restore.add(session_id)
                            continue
                    logger.info(f"OpenCode session {session_id} has completed, removing from active polls")
                    try:
                        await server.mark_run_inactive(poll_info.opencode_session_id)
                    except Exception:
                        logger.exception(
                            "Failed to clear OpenCode run marker for session=%s; "
                            "preserving its active poll and continuing restoration",
                            poll_info.opencode_session_id,
                        )
                        await self._release_binding(binding)
                        self._polls_awaiting_restore.add(session_id)
                        continue
                    await self._release_binding(binding)
                    await self._poll_loop.remove_restored_ack(poll_info)
                    stale_poll_ids.append(session_id)
                    continue

                logger.info(
                    f"Restoring poll loop for OpenCode session {session_id} "
                    f"(thread={poll_info.base_session_id}, cwd={poll_info.working_path})"
                )

                restored_binding_token = secrets.token_hex(16)
                restored_binding_path = (
                    _caller_context_path_for_server(server) if server is not None else None
                )
                restored_caller_env = validated_caller_env_snapshot(
                    processing_snapshot.get(_CALLER_CONTEXT_ENV_SNAPSHOT_KEY)
                )
                restored_context = restored_context_from_poll_info(poll_info)
                if (
                    poll_platform == "avibe"
                    and str(restored_context.user_id or "").startswith("remote:")
                ):
                    # Legacy persisted polls do not carry the authorization snapshot.
                    # Keep them remote-but-unprivileged instead of silently treating an
                    # absent snapshot as a local caller.
                    restored_caller_env.setdefault(AVIBE_SESSION_ID_ENV, poll_info.base_session_id)
                    restored_caller_env.setdefault(AVIBE_CALLER_PLATFORM_ENV, "avibe")
                    restored_caller_env.setdefault(
                        AVIBE_CALLER_USER_ID_ENV,
                        str(restored_context.user_id),
                    )
                    restored_caller_env.setdefault(AVIBE_CALLER_REMOTE_ENV, "1")
                restored_project_base = processing_snapshot.get(
                    _MANAGED_SKILL_PROJECT_BASE_SNAPSHOT_KEY
                )
                restored_project_base = (
                    restored_project_base
                    if isinstance(restored_project_base, str) and restored_project_base
                    else None
                )
                restored_catalog_root = None
                catalog_present = (
                    _MANAGED_SKILL_BUILTIN_CATALOG_KEY in processing_snapshot
                    or "opencode_managed_skill_builtin_snapshot" in processing_snapshot
                )
                restored_catalog = processing_snapshot.get(
                    _MANAGED_SKILL_BUILTIN_CATALOG_KEY
                )
                if restored_catalog is None:
                    restored_catalog = processing_snapshot.get(
                        "opencode_managed_skill_builtin_snapshot"
                    )
                if isinstance(restored_catalog, dict) and isinstance(
                    restored_catalog.get("root"), str
                ):
                    restored_catalog_root = restored_catalog.get("root")
                elif catalog_present:
                    restored_catalog_root = ""
                restored_managed_skills_env = managed_skill_environment(
                    poll_info.working_path,
                    project_base=restored_project_base,
                    builtin_catalog_root=restored_catalog_root,
                )
                restored_bound = False
                for attempt in range(3):
                    try:
                        restored_bound = await asyncio.to_thread(
                            bind_caller_context_session,
                            poll_info.opencode_session_id,
                            None,
                            base_env=os.environ,
                            working_dir=poll_info.working_path,
                            extra_env={
                                **restored_caller_env,
                                **restored_managed_skills_env,
                            },
                            binding_token=restored_binding_token,
                            **_binding_path_kwargs(restored_binding_path),
                        )
                    except Exception:
                        logger.warning(
                            "Failed to restore OpenCode caller context for session=%s (attempt %s/3)",
                            poll_info.opencode_session_id,
                            attempt + 1,
                            exc_info=True,
                        )
                    if restored_bound:
                        break
                    if attempt < 2:
                        await asyncio.sleep(0)
                if not restored_bound:
                    logger.error(
                        "Restoring OpenCode poll without caller context for session=%s",
                        poll_info.opencode_session_id,
                    )

                restoration_ready = asyncio.get_running_loop().create_future()
                restoration_published = asyncio.Event()
                task = asyncio.create_task(
                    self._run_restored_poll_loop_with_tracking(
                        poll_info,
                        generation_binding=binding,
                        reconcile_initial_status=status_unknown,
                        reconcile_after_message_ids=reconcile_after_message_ids,
                        restoration_ready=restoration_ready,
                        restoration_published=restoration_published,
                        caller_context_binding_token=(
                            restored_binding_token
                        ),
                        caller_context_binding_path=restored_binding_path,
                        caller_context_binding_extra_env={
                            **restored_caller_env,
                            **restored_managed_skills_env,
                        },
                        caller_context_binding_initially_bound=restored_bound,
                    )
                )
            except BaseException:
                # Until the poll task owns the binding, nothing else releases it.
                await self._release_binding(binding)
                raise
            restoration_results.append(
                _RestoredPollHandoff(restoration_ready, restoration_published, poll_info, task)
            )
            self._active_requests[poll_info.base_session_id] = task
            self._session_manager.set_request_session(
                poll_info.base_session_id,
                poll_info.opencode_session_id,
                poll_info.working_path,
                restored_session_key_from_poll_info(poll_info),
            )
            set_agent_session_id = getattr(
                self._session_manager,
                "set_agent_session_id",
                None,
            )
            if callable(set_agent_session_id):
                set_agent_session_id(
                    poll_info.base_session_id,
                    self._workbench_session_id_for_poll(poll_info),
                )
        for session_id in stale_poll_ids:
            self.sessions.remove_active_poll(session_id)

        if restoration_results:
            registered = await asyncio.gather(
                *(handoff.ready for handoff in restoration_results)
            )
            for is_registered, handoff in zip(
                registered,
                restoration_results,
            ):
                try:
                    if not is_registered:
                        continue
                    workbench_session_id = self._workbench_session_id_for_poll(handoff.poll_info)
                    if workbench_session_id:
                        self.controller.session_turns.restore_running(workbench_session_id)
                    restored_count += 1
                finally:
                    handoff.published.set()

        if restored_count > 0:
            logger.info(f"Restored {restored_count} active poll loop(s)")
        if stale_poll_ids:
            logger.info(f"Removed {len(stale_poll_ids)} stale active poll(s)")

        return restored_count

    async def _run_restored_poll_loop_with_tracking(
        self,
        poll_info,
        *,
        generation_binding: RuntimeBinding | None = None,
        reconcile_initial_status: bool = False,
        reconcile_after_message_ids: set[str] | None = None,
        restoration_ready: asyncio.Future[bool] | None = None,
        restoration_published: asyncio.Event | None = None,
        caller_context_binding_token: str | None = None,
        caller_context_binding_path: str | None = None,
        caller_context_binding_extra_env: dict[str, str] | None = None,
        caller_context_binding_initially_bound: bool = False,
    ) -> None:
        current_task = asyncio.current_task()
        steer_state = None
        server = None
        restoration_registered = False
        terminal_poll_cleanup = False
        caller_context_binding_renewal = (
            asyncio.create_task(
                self._maintain_caller_context_binding(
                    poll_info.opencode_session_id,
                    caller_context_binding_token,
                    caller_context_binding_path,
                    payload=None,
                    working_directory=poll_info.working_path,
                    extra_env=caller_context_binding_extra_env or {},
                    initially_bound=caller_context_binding_initially_bound,
                )
            )
            if caller_context_binding_token
            else None
        )
        try:
            poll_platform = restored_platform_from_poll_info(poll_info)
            registration_attempts = 2 if poll_platform in _RESTORED_IM_PLATFORMS else 1
            for attempt in range(registration_attempts):
                try:
                    if generation_binding is not None and generation_binding.generation.stopped:
                        # A forced stop took the process before this poll
                        # registered on it; a live generation settles the run.
                        await self._release_binding(generation_binding)
                        generation_binding = None
                    if generation_binding is None:
                        generation_binding = await self._bind_restored_poll(poll_info)
                    server = generation_binding.generation.runtime
                    self._session_generations[poll_info.base_session_id] = server
                    await server.mark_run_active(poll_info.opencode_session_id)
                    break
                except Exception:
                    if attempt + 1 >= registration_attempts:
                        raise
                    logger.warning(
                        "Retrying restored OpenCode IM poll registration for session=%s",
                        poll_info.opencode_session_id,
                        exc_info=True,
                    )
                    await asyncio.sleep(_RESTORED_IM_REGISTRATION_RETRY_DELAY_SECONDS)
            steering_snapshot = (
                poll_info.processing_indicator.get(_STEERING_SNAPSHOT_KEY)
                if isinstance(poll_info.processing_indicator, dict)
                else None
            )
            target_session_id = (
                str(steering_snapshot.get("target_session_id") or "")
                if isinstance(steering_snapshot, dict)
                else ""
            )
            logical_turn_id = (
                str(steering_snapshot.get("logical_turn_id") or "")
                if isinstance(steering_snapshot, dict)
                else ""
            )
            has_steering_identity = bool(target_session_id and logical_turn_id)
            display_model_dict = (
                poll_info.processing_indicator.get(_MODEL_HUB_DISPLAY_MODEL_KEY)
                if isinstance(poll_info.processing_indicator, dict)
                else None
            )
            if not isinstance(display_model_dict, dict):
                display_model_dict = poll_info.model_dict
            if current_task is not None and (
                has_steering_identity
                or reconcile_initial_status
                or reconcile_after_message_ids is not None
            ):
                steer_state = _OpenCodeSteerState(
                    task=current_task,
                    base_session_id=poll_info.base_session_id,
                    target_session_id=target_session_id,
                    logical_turn_id=logical_turn_id,
                    native_session_id=poll_info.opencode_session_id,
                    directory=poll_info.working_path,
                    agent=(
                        steering_snapshot.get("agent")
                        if isinstance(steering_snapshot, dict)
                        and isinstance(steering_snapshot.get("agent"), str)
                        else None
                    ),
                    model=poll_info.model_dict,
                    reasoning_effort=poll_info.reasoning_effort,
                    system=(
                        steering_snapshot.get("system")
                        if isinstance(steering_snapshot, dict)
                        and isinstance(steering_snapshot.get("system"), str)
                        else None
                    ),
                    baseline_message_ids=set(poll_info.baseline_message_ids),
                    awaiting_after_message_ids=(
                        set(reconcile_after_message_ids)
                        if reconcile_after_message_ids is not None
                        else None
                    ),
                    idle_reconciliation_message=self._idle_reconciliation_message(
                        display_model_dict,
                        poll_info.reasoning_effort,
                    ),
                    restored=True,
                    reconcile_initial_status=reconcile_initial_status,
                    generation=server,
                )
                if has_steering_identity:
                    self._steering_states[poll_info.base_session_id] = steer_state
                self._restored_poll_servers[current_task] = _SteeringAwareOpenCodeServer(
                    server,
                    steer_state,
                )
            restoration_registered = True
            if restoration_ready is not None and not restoration_ready.done():
                restoration_ready.set_result(True)
            if restoration_published is not None:
                await restoration_published.wait()
            delivery_recovery_complete = getattr(
                self.controller,
                "_delivery_recovery_complete",
                None,
            )
            if delivery_recovery_complete is not None:
                await delivery_recovery_complete.wait()
            terminal_poll_cleanup = bool(
                await self._poll_loop.run_restored_poll_loop(
                    poll_info,
                    self._restored_poll_servers.get(current_task) or server,
                )
            )
        except _RestoredPollUnrecorded:
            if restoration_registered:
                raise
            # Unregistered and still naming its old process, the poll stays
            # durable with its Turn live, and a later restore retries it.
            self._polls_awaiting_restore.add(poll_info.opencode_session_id)
        except Exception as err:
            if restoration_registered:
                raise
            else:
                steering_snapshot = (
                    poll_info.processing_indicator.get(_STEERING_SNAPSHOT_KEY)
                    if isinstance(poll_info.processing_indicator, dict)
                    else None
                )
                logical_turn_id = (
                    str(steering_snapshot.get("logical_turn_id") or "").strip()
                    if isinstance(steering_snapshot, dict)
                    else ""
                )
                terminal_persisted = False
                if logical_turn_id:
                    try:
                        terminal_persisted = bool(
                            self.controller.session_turns.fail_restored_backend_turn(
                                logical_turn_id,
                                backend="opencode",
                                reason="poll_registration_failed",
                            )
                        )
                    except Exception:
                        logger.exception(
                            "Failed to terminalize OpenCode Turn=%s after poll registration error",
                            logical_turn_id,
                        )
                if terminal_persisted:
                    terminal_poll_cleanup = True
                logger.error(
                    "OpenCode poll registration failed for session=%s: %s",
                    poll_info.opencode_session_id,
                    err,
                )
        finally:
            try:
                interrupted = current_task in self._settling_request_tasks
                if current_task is not None:
                    # Settling from here on, however the poll ended.
                    self._settling_request_tasks.add(current_task)
                    current_task.add_done_callback(self._settling_request_tasks.discard)
                await self._stop_caller_context_binding_renewal(
                    caller_context_binding_renewal
                )
                if current_task is not None:
                    self._restored_poll_servers.pop(current_task, None)
                if steer_state is not None:
                    async with steer_state.lock:
                        steer_state.closing = True
                    if self._steering_states.get(poll_info.base_session_id) is steer_state:
                        self._steering_states.pop(poll_info.base_session_id, None)
                if (terminal_poll_cleanup or interrupted) and server is not None:
                    await self._retire_active_poll(
                        server,
                        poll_info.opencode_session_id,
                    )
                elif interrupted:
                    # Interrupted before registering a run marker: only the durable
                    # record would bring the run back after a restart.
                    self.sessions.remove_active_poll(poll_info.opencode_session_id)
                if caller_context_binding_token and not self._active_poll_is_persisted(
                    poll_info.opencode_session_id
                ):
                    try:
                        await asyncio.to_thread(
                            unbind_caller_context_session,
                            poll_info.opencode_session_id,
                            binding_token=caller_context_binding_token,
                            **_binding_path_kwargs(caller_context_binding_path),
                        )
                    except Exception:
                        logger.warning(
                            "Failed to clear restored OpenCode caller context for session %s",
                            poll_info.opencode_session_id,
                            exc_info=True,
                        )
            finally:
                # A cancel that lands while the cleanup above awaits must not
                # leave this poll's request, generation, or binding behind.
                if self._active_requests.get(poll_info.base_session_id) is current_task:
                    self._active_requests.pop(poll_info.base_session_id, None)
                    self._session_manager.pop_request_session(poll_info.base_session_id)
                if server is not None and self._session_generations.get(poll_info.base_session_id) is server:
                    self._session_generations.pop(poll_info.base_session_id, None)
                await self._release_binding(generation_binding)
                if restoration_ready is not None and not restoration_ready.done():
                    restoration_ready.set_result(False)

    async def _bind_restored_poll(self, poll_info) -> RuntimeBinding:
        """Bind a restored poll to the generation whose process runs its native turn."""

        await self._ensure_adopted()
        generation_id = _poll_generation_id(poll_info)
        generation = self._runtime.generation(generation_id) if generation_id else None
        if generation is None and generation_id is None:
            # Polls written before generations name no process: the adopted
            # legacy server is the one that recorded their run.
            generation = next(
                (
                    candidate
                    for candidate in self._runtime.generations()
                    if poll_info.opencode_session_id in candidate.active_run_sessions
                ),
                None,
            )
        if generation is not None:
            binding = await self._runtime.bind(generation)
        else:
            # No live process owns this run any more. Its messages are in the
            # shared database, so the current generation reads and settles it.
            _config, _overlay, spec, _settings = await self._prepare_launch()
            binding = await self._runtime.acquire(spec)
        bound_id = binding.generation.runtime.generation_id
        if bound_id != generation_id:
            # The poll names the process that now runs its native turn, so a
            # later restart adopts that process for it and binds it there.
            indicator = poll_info.processing_indicator if isinstance(poll_info.processing_indicator, dict) else {}
            try:
                self.sessions.update_active_poll_state(
                    poll_info.opencode_session_id,
                    processing_indicator={**indicator, _GENERATION_SNAPSHOT_KEY: bound_id},
                )
            except Exception as exc:
                # Never run a poll whose record still names another process: a
                # crash would bind its next restore to the wrong server.
                await self._release_binding(binding)
                logger.warning(
                    "Could not record OpenCode generation %s for restored poll %s; a later restore retries it",
                    bound_id,
                    poll_info.opencode_session_id,
                    exc_info=True,
                )
                raise _RestoredPollUnrecorded(poll_info.opencode_session_id) from exc
        return binding

    def _prepare_message_with_files(self, request: AgentRequest) -> str:
        return message_with_files(request.message, request.files)