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.

138 KB
Raw Blame
"""Session management handlers for Claude SDK sessions"""

import asyncio
import logging
import os
import re
import time
from dataclasses import dataclass
from types import SimpleNamespace
from typing import TYPE_CHECKING, Optional, Dict, Any, Tuple
from uuid import uuid4
from modules.im import MessageContext
from modules.claude_sdk_compat import (
    CLAUDE_SDK_HOOKS_AVAILABLE,
    CLAUDE_SDK_MAX_BUFFER_SIZE,
    ClaudeAgentOptions,
    ClaudeSDKClient,
    HookMatcher,
    PermissionResultAllow,
    is_claude_sdk_buffer_error,
)
from modules.agents.native_sessions.base import build_resume_preview
from modules.agents.claude_process_reaper import (
    AVIBE_CLAUDE_PROCESS_OWNER_ENV,
    AVIBE_CLAUDE_SESSION_OWNER,
    get_claude_client_pid,
    get_claude_client_returncode,
    claude_stderr_tail_section,
    claude_process_exit_reason,
    claude_process_exit_reason_i18n,
    register_claude_owned_process,
    reap_duplicate_claude_resume_processes,
    reap_orphaned_claude_processes,
    get_claude_client_process,
    stop_claude_process,
)
from config.v2_config import (
    DEFAULT_STUCK_ACTIVE_IDLE_EVICTION_FLOOR_SECONDS,
    DEFAULT_STUCK_ACTIVE_IDLE_EVICTION_MULTIPLIER,
)
from core.agent_tool_policy import (
    ALWAYS_SESSION_ONLY_TOOL_NAMES,
    check_tool_call,
    session_only_background_tool_names,
)
from core.agent_session_context import resolve_context_agent_session_target
from core.caller_context import AVIBE_SESSION_ID_ENV, caller_env_for_platform_payload
from core.managed_skills import (
    managed_skill_environment,
    managed_skill_project_base,
)
from core.message_context import build_thread_session_anchor, resolve_context_thread_id
from core.resource_governance import (
    observe_agent_resource_pressure,
    governor_from_controller,
    pids_failure_labels,
)
from core.runtime_activation import RuntimeActivationIdentity
from core.services.session_fork import pending_native_fork_source
from core.system_prompt_injection import (
    build_system_prompt_injection,
    get_enabled_agents_for_prompt,
)
from vibe import backend_model_catalog

from .base import BaseHandler

logger = logging.getLogger(__name__)

# A Claude CLI process the service terminated on purpose surfaces as SIGTERM
# (-15) or the SIGKILL escalation (-9). The SDK may report it as a returncode
# or only as text on the transport error, so both shapes are recognized. The
# text arrives in two shapes: the SDK transport reader raises "Command failed
# with exit code -9", while write failures raise "Cannot write to terminated
# process (exit code: -9)".
CLAUDE_TEARDOWN_RETURNCODES = frozenset({-9, -15})
CLAUDE_TEARDOWN_EXIT_PATTERN = re.compile(r"exit code:?\s*(-9|-15)\b")
# Teardown intent is dropped as soon as a new client takes the key; this bound
# only limits how long a stale record can survive when that never happens.
CLAUDE_INTENTIONAL_TEARDOWN_TTL_SECONDS = 120.0

if TYPE_CHECKING:
    from core.runtime_ownership import RuntimeResourceTarget
    from modules.agents.model_hub import ModelHubLaunch

CLAUDE_NO_CONVERSATION_RE = re.compile(r"No conversation found with session ID:\s*(\S+)")
CLAUDE_REMOTE_DISALLOWED_TOOLS = [
    "AskUserQuestion",
    "EnterPlanMode",
    "ExitPlanMode",
    "Skill",
]
CLAUDE_REMOTE_PERMISSION_MODE = "bypassPermissions"
CLAUDE_REMOTE_SANDBOX = {"enabled": False}


# How long a cancelled turn waits for its client's connect to unwind before
# stopping the CLI process directly.
CLAUDE_ABANDONED_CONNECT_TIMEOUT_SECONDS = 10.0


class ClaudeSessionNotFoundError(RuntimeError):
    """Claude Code could not resume a persisted session in the current cwd."""

    def __init__(self, session_id: str, working_path: str, stderr: str = ""):
        self.session_id = session_id
        self.working_path = working_path
        self.stderr = stderr
        super().__init__(
            f"Claude Code session not found in current working directory: {session_id} ({working_path})"
        )


class ClaudeBackendDisabledError(RuntimeError):
    """Claude was turned off before this turn's client could serve it."""


class ClaudeInputNotSentError(RuntimeError):
    """A local admission failure with definitive evidence of no native write."""

    def __init__(self, reason: str, message_key: str):
        self.reason = reason
        self.message_key = message_key
        super().__init__(reason)


class _ClaudeReceiverCleanupRequired(RuntimeError):
    """Signal that a dead generation must be retried after receiver cleanup."""

    def __init__(self, composite_key: str):
        self.composite_key = composite_key
        super().__init__(f"Claude receiver cleanup is still pending for {composite_key}")


@dataclass(frozen=True)
class _ClaudeLaunchInputs:
    """One Claude turn's whole configuration, read in one step at admission.

    Its Model Hub resolution, client reuse check, and any new client all derive
    from it, so a save or renewal landing mid-admission cannot split them.
    """

    epoch: int
    config: Any
    hub_config: Any


@dataclass(frozen=True)
class _ResolvedClaudeAgentInputs:
    """One selected agent's effective prompt, authority, and model."""

    system_prompt: Optional[str]
    allowed_tools: list[str] | None
    model: Optional[str]


class SessionHandler(BaseHandler):
    """Handles all session-related operations"""

    def __init__(self, controller):
        """Initialize with reference to main controller"""
        super().__init__(controller)
        self.session_manager = controller.session_manager
        self.claude_sessions = controller.claude_sessions
        self.receiver_tasks = controller.receiver_tasks
        self.stored_session_mappings = controller.stored_session_mappings
        self.session_last_activity = getattr(controller, "session_last_activity", {})
        self.session_turn_started = getattr(controller, "session_turn_started", {})
        self.active_sessions = getattr(controller, "claude_active_sessions", set())
        self.claude_system_prompts = getattr(controller, "claude_system_prompts", {})
        self.claude_session_creates = getattr(controller, "claude_session_creates", {})
        self.claude_runtime_generation_locks = getattr(
            controller,
            "claude_runtime_generation_locks",
            {},
        )
        self.claude_intentional_teardowns = getattr(
            controller,
            "claude_intentional_teardowns",
            {},
        )
        controller.session_last_activity = self.session_last_activity
        controller.session_turn_started = self.session_turn_started
        controller.claude_active_sessions = self.active_sessions
        controller.claude_system_prompts = self.claude_system_prompts
        controller.claude_session_creates = self.claude_session_creates
        controller.claude_runtime_generation_locks = self.claude_runtime_generation_locks
        controller.claude_intentional_teardowns = self.claude_intentional_teardowns

    @staticmethod
    def _cached_claude_subagent_model(
        explicit_model: Optional[str],
        model_hub_launch: "ModelHubLaunch",
    ) -> Optional[str]:
        if model_hub_launch.channel in {"native_cli", "hub"}:
            return model_hub_launch.runtime_model
        return explicit_model

    def touch_session_activity(self, composite_key: str) -> None:
        if composite_key:
            self.session_last_activity[composite_key] = time.monotonic()

    def mark_session_active(self, composite_key: str) -> None:
        if not composite_key:
            return
        # Stamp the turn-start baseline only on the idle→active transition, so a
        # second queued request on an already-active session does not reset the
        # "busy for" clock (it stays anchored to the first in-flight request).
        if composite_key not in self.active_sessions:
            self.session_turn_started[composite_key] = time.monotonic()
        self.active_sessions.add(composite_key)

    def mark_session_turn_started(self, composite_key: str) -> None:
        """Record exact native acceptance as the fresh progress baseline."""

        if not composite_key:
            return
        now = time.monotonic()
        self.active_sessions.add(composite_key)
        self.session_turn_started[composite_key] = now
        self.session_last_activity[composite_key] = now

    def mark_session_idle(self, composite_key: str) -> None:
        if not composite_key:
            return
        self.active_sessions.discard(composite_key)
        self.session_turn_started.pop(composite_key, None)
        if composite_key in self.claude_sessions:
            self.touch_session_activity(composite_key)

    def clear_session_tracking(self, composite_key: str) -> None:
        if not composite_key:
            return
        self.active_sessions.discard(composite_key)
        self.session_last_activity.pop(composite_key, None)
        self.session_turn_started.pop(composite_key, None)
        self.claude_system_prompts.pop(composite_key, None)

    def _live_claude_client_pids(self) -> tuple[set[int], bool]:
        """Claude CLI pids owned by registered clients, and whether that set is whole.

        The duplicate reaper matches on the native ``--resume`` id, which is
        reused across reconnects and therefore cannot distinguish a leaked
        generation from a live client for the same session. Membership in
        ``claude_sessions`` is the authoritative ownership signal, so these
        pids are never eligible for a duplicate reap.

        A registered client whose pid cannot be resolved is still an owner — it
        just cannot be named — so the second element reports whether every
        owner is accounted for. ``reap_orphaned_claude_sessions`` already draws
        this distinction with ``owner_set_complete``; without it a partial set
        reads as the whole ownership picture and a live replacement resuming
        this native id can be selected by the process-table scan.
        """
        pids: set[int] = set()
        complete = True
        for client in list(self.claude_sessions.values()):
            pid = get_claude_client_pid(client)
            if pid:
                pids.add(pid)
            else:
                complete = False
        return pids, complete

    def _mark_claude_teardown_intentional(self, composite_key: str, client) -> None:
        """Record that this generation is being torn down by the service."""
        if client is not None:
            setattr(client, "_vibe_intentional_teardown", True)
        if not composite_key:
            return
        now = time.monotonic()
        # Keys that never get a replacement client would otherwise keep their
        # record forever; drop expired ones on the way in.
        for key, started_at in list(self.claude_intentional_teardowns.items()):
            if now - started_at > CLAUDE_INTENTIONAL_TEARDOWN_TTL_SECONDS:
                self.claude_intentional_teardowns.pop(key, None)
        self.claude_intentional_teardowns[composite_key] = now

    def _clear_claude_teardown_intent(self, composite_key: str) -> None:
        """Drop the teardown record once a new generation owns the key.

        A fresh client must never inherit the previous generation's teardown
        marker, otherwise its own failures would be silently swallowed.

        The key-level record is therefore the *replacement's* view, not the
        torn-down generation's: an in-flight query from the old generation can
        still reach ``handle_session_error`` after this runs. That case is
        carried by the per-client ``_vibe_intentional_teardown`` attribute
        instead, which is why callers pass the exact client whose failure they
        observed rather than letting the handler re-read ``claude_sessions``.
        """
        if composite_key:
            self.claude_intentional_teardowns.pop(composite_key, None)

    def _is_intentional_teardown_signal(
        self,
        composite_key: str,
        error: Exception,
        returncode: Optional[int],
        client=None,
    ) -> bool:
        """Was this failure our own SIGTERM/SIGKILL against a torn-down client?

        Cleanup escalates SIGTERM to SIGKILL, so the SDK reports ``exit code
        -15``/``-9`` for a process the service killed on purpose. Reporting
        that as a session error makes a deliberate teardown look like a backend
        crash.
        """
        if not getattr(client, "_vibe_intentional_teardown", False):
            started_at = self.claude_intentional_teardowns.get(composite_key)
            if started_at is None:
                return False
            if time.monotonic() - started_at > CLAUDE_INTENTIONAL_TEARDOWN_TTL_SECONDS:
                self.claude_intentional_teardowns.pop(composite_key, None)
                return False
        if returncode is not None:
            return returncode in CLAUDE_TEARDOWN_RETURNCODES
        return bool(CLAUDE_TEARDOWN_EXIT_PATTERN.search(str(error)))

    def claude_teardown_is_intentional(
        self,
        composite_key: str,
        error: Exception,
        *,
        client=None,
    ) -> bool:
        """Public probe: is this failure a teardown the service performed itself?

        Callers need the answer *before* they record backend-health evidence.
        ``record_model_hub_native_failure`` converts the pending attempt into a
        failed one, so classifying only afterwards lets operational cleanup
        settle a Model Hub source as unhealthy for a process nobody reported a
        fault in.
        """
        resolved = client if client is not None else self.claude_sessions.get(composite_key)
        return self._is_intentional_teardown_signal(
            composite_key,
            error,
            get_claude_client_returncode(resolved),
            resolved,
        )

    async def _wait_for_claude_session_idle(self, composite_key: str) -> None:
        while composite_key in self.active_sessions:
            await asyncio.sleep(0.05)

    async def _wait_for_claude_receiver_cleanup(self, composite_key: str) -> None:
        """Wait for the receiver task to finish its post-error cleanup."""
        receiver_task = self.receiver_tasks.get(composite_key)
        if receiver_task is None or receiver_task is asyncio.current_task():
            return
        try:
            await asyncio.shield(receiver_task)
        except asyncio.CancelledError:
            if receiver_task.cancelled():
                return
            raise
        except Exception:
            # The receiver already reported its failure; cleanup must still retire
            # the cached client and drain the task without masking that failure.
            logger.debug(
                "Claude receiver task ended with an error while waiting for cleanup: %s",
                composite_key,
                exc_info=True,
            )

    def bind_claude_runtime_session(
        self,
        client: ClaudeSDKClient,
        base_session_id: str,
        composite_key: str,
        native_session_id: Optional[str] = None,
        *,
        working_path: str,
        fallback_session_key: str,
        agent_session_id: Optional[str],
    ) -> None:
        """Attach the resolved Claude runtime keys to the connected client."""
        setattr(client, "_vibe_runtime_base_session_id", base_session_id)
        setattr(client, "_vibe_runtime_session_key", composite_key)
        setattr(client, "_vibe_runtime_workdir", working_path)
        setattr(client, "_vibe_runtime_fallback_session_key", fallback_session_key)
        setattr(client, "_vibe_agent_session_id", str(agent_session_id or "").strip())
        self._attach_claude_runtime_activation(client, composite_key)
        if native_session_id:
            setattr(client, "_vibe_native_session_id", native_session_id)
        register_claude_owned_process(
            client,
            native_session_id=native_session_id,
            owner=AVIBE_CLAUDE_SESSION_OWNER,
        )

    def _runtime_activation_registry(self):
        return getattr(self.controller, "runtime_activation", None)

    @staticmethod
    def _claude_runtime_activation_identity(
        client: ClaudeSDKClient | None,
    ) -> RuntimeActivationIdentity | None:
        identity = getattr(client, "_vibe_runtime_activation_identity", None)
        return identity if isinstance(identity, RuntimeActivationIdentity) else None

    def _attach_claude_runtime_activation(
        self,
        client: ClaudeSDKClient,
        composite_key: str,
    ) -> RuntimeActivationIdentity | None:
        registry = self._runtime_activation_registry()
        if registry is None:
            return None
        existing = self._claude_runtime_activation_identity(client)
        if existing is not None and registry.is_current(existing):
            return existing
        identity = registry.attach("claude", composite_key)
        setattr(client, "_vibe_runtime_activation_identity", identity)
        return identity

    def _retire_claude_runtime_activation(
        self,
        composite_key: str,
        client: ClaudeSDKClient,
        final_predicate,
    ) -> bool:
        registry = self._runtime_activation_registry()
        if registry is None:
            return bool(final_predicate())
        identity = self._claude_runtime_activation_identity(client)
        if identity is None:
            identity = self._attach_claude_runtime_activation(client, composite_key)
        if identity is None:
            return False
        return bool(registry.retire_if_current(identity, final_predicate))

    async def _set_claude_model_if_needed(self, client: ClaudeSDKClient, desired_model: Optional[str]) -> None:
        unknown = object()
        current_model = getattr(client, "_vibe_current_model", unknown)
        if current_model is not unknown and current_model == desired_model:
            return

        if current_model is unknown and desired_model is None:
            setattr(client, "_vibe_current_model", None)
            return

        set_model = getattr(client, "set_model", None)
        if not callable(set_model):
            logger.warning("Claude SDK client does not support model switching")
            return

        await set_model(desired_model)
        setattr(client, "_vibe_current_model", desired_model)

    @staticmethod
    def _claude_git_path_state(working_path: str) -> str:
        from core.agent_path import prepend_managed_tools_to_path

        env: dict[str, str] = {}
        prepend_managed_tools_to_path(
            env,
            base_env=os.environ,
            working_dir=working_path,
        )
        return env["PATH"] if "PATH" in env else os.environ.get("PATH", "")

    async def _evict_terminated_cached_claude_session(
        self,
        composite_key: str,
        client: ClaudeSDKClient,
    ) -> bool:
        returncode = get_claude_client_returncode(client)
        if returncode is None:
            return False

        reason = claude_process_exit_reason(returncode)
        diagnostic = claude_stderr_tail_section(client)
        logger.warning(
            "Recreating cached Claude SDK client for %s because its process terminated (%s)%s",
            composite_key,
            reason,
            diagnostic,
        )
        receiver_task = self.receiver_tasks.get(composite_key)
        if (
            receiver_task is not None
            and receiver_task is not asyncio.current_task()
            and not receiver_task.done()
        ):
            # This method runs under the generation lock. Let the receiver
            # release that lock through its normal error cleanup before waiting
            # for the task, otherwise both sides wait on one another.
            raise _ClaudeReceiverCleanupRequired(composite_key)
        await self._wait_for_claude_receiver_cleanup(composite_key)
        await self._wait_for_claude_session_idle(composite_key)
        await self._cleanup_session_locked(
            composite_key,
            # A dead cached client may have been launched through Model Hub even
            # when the current turn resolves to a different channel. Retire the
            # cached generation's process credential before recreating it.
            retire_model_hub_scope=True,
            reason="cached_process_terminated",
        )
        return True

    def renew_runtime(self) -> None:
        """Move every session to a new client at its next turn, interrupting nothing."""
        self.controller.claude_runtime_epoch = getattr(self.controller, "claude_runtime_epoch", 0) + 1

    def _idle_eviction_after(self, client: Any, idle_timeout: float) -> float | None:
        """Seconds a client may stay idle before eviction; None keeps it."""
        if getattr(client, "_vibe_runtime_epoch", 0) != getattr(self.controller, "claude_runtime_epoch", 0):
            return 0.0
        return idle_timeout if idle_timeout > 0 else None

    async def _replace_stale_cached_claude_client(
        self,
        composite_key: str,
        client: ClaudeSDKClient,
        *,
        context: MessageContext,
        working_path: str,
        effective_effort: Optional[str],
        system_prompt: Any,
        model_hub_launch: "ModelHubLaunch",
        launch_inputs: "_ClaudeLaunchInputs | None" = None,
    ) -> bool:
        """Retire a cached client whose launch inputs changed; True once it is gone.

        An idle session moves to a new client at once. While the session's own
        background work still runs, the turn stays on the current client, and the
        session moves at its next idle turn. The exceptions are a turn that needs
        a Model Hub launch this client cannot carry and a turn from a different
        caller: then the client is replaced and that work interrupted.
        """
        launch_changed = getattr(client, "_vibe_model_hub_fingerprint", "direct") != model_hub_launch.fingerprint
        # The caller's identity carries its resource authority, so a different
        # caller can never run in a process that holds the previous one's.
        caller_changed = getattr(client, "_vibe_caller_env", {}) != self._caller_env_for_context(context)
        changes = (
            ("model_hub_channel_changed", launch_changed),
            ("caller_env_changed", caller_changed),
            ("reasoning_effort_changed", getattr(client, "_vibe_reasoning_effort", None) != effective_effort),
            (
                "runtime_renewed",
                getattr(client, "_vibe_runtime_epoch", 0)
                != (
                    launch_inputs.epoch
                    if launch_inputs is not None
                    else getattr(self.controller, "claude_runtime_epoch", 0)
                ),
            ),
            ("system_prompt_changed", self.claude_system_prompts.get(composite_key) != system_prompt),
            (
                "managed_skills_changed",
                getattr(client, "_vibe_managed_skills_env", {})
                != managed_skill_environment(
                    working_path,
                    project_base=managed_skill_project_base(context),
                ),
            ),
            ("git_path_changed", getattr(client, "_vibe_git_path_state", None) != self._claude_git_path_state(working_path)),
        )
        reason = next((name for name, changed in changes if changed), None)
        if reason is None:
            return False
        if composite_key in self.active_sessions:
            if not (launch_changed or caller_changed):
                logger.info(
                    "Keeping the busy Claude SDK client for %s until its session is idle: %s",
                    composite_key,
                    reason,
                )
                return False
            self._interrupt_claude_session_work(composite_key)
        logger.info("Recreating cached Claude SDK client for %s: %s", composite_key, reason)
        await self._cleanup_session_locked(
            composite_key,
            retire_model_hub_scope=model_hub_launch.channel == "direct",
            reason=reason,
        )
        return True

    def _interrupt_claude_session_work(self, composite_key: str, *, reason: str | None = None) -> None:
        """Settle a replaced or stopped client's background work.

        ``reason`` is the settlement; the default is a runtime update.
        """
        service = getattr(self.controller, "agent_service", None)
        end_runtime = getattr(service, "force_end_runtime_activities", None)
        if callable(end_runtime):
            if reason is None:
                end_runtime("claude", composite_key)
            else:
                end_runtime("claude", composite_key, reason=reason)

    async def _connect_claude_client(self, client) -> None:
        """Connect a client so that no exit leaves its CLI running unowned.

        The client is not in ``claude_sessions`` yet, so no disable capture
        can reach it. The connect runs shielded: a cancelled turn, such as one
        a disable interrupts, reads the CLI's process off the client while the
        connect is still in flight, cancels the connect once so the SDK's own
        cleanup runs undisturbed, and then stops that process whatever the
        cleanup achieved.
        """
        connect = asyncio.ensure_future(client.connect())
        try:
            await asyncio.shield(connect)
        except asyncio.CancelledError:
            process = get_claude_client_process(client)
            connect.cancel()
            await asyncio.shield(self._stop_abandoned_connect(client, connect, process))
            raise

    async def _stop_abandoned_connect(self, client, connect: asyncio.Future, process: Any) -> None:
        try:
            await asyncio.wait_for(connect, timeout=CLAUDE_ABANDONED_CONNECT_TIMEOUT_SECONDS)
        except BaseException:
            # Cancelled or failed: the SDK's connect already ran its cleanup.
            pass
        else:
            # It connected as the turn was cancelled.
            try:
                await client.disconnect()
            except Exception:
                logger.warning("Failed to disconnect an abandoned Claude client", exc_info=True)
        if not await stop_claude_process(process, logger=logger):
            logger.warning(
                "Claude CLI pid=%s of an abandoned connect survived its stop",
                getattr(process, "pid", None),
            )

    def _claude_disabled(self) -> bool:
        return getattr(getattr(self.config, "claude", None), "enabled", True) is False

    def capture_claude_clients(self) -> tuple[tuple[str, Any, Any], ...]:
        """Every live client, by key, identity, and CLI process, for a stop that must close exactly these.

        The process is read now: a disconnect drops it from the client.
        """
        return tuple(
            (composite_key, client, get_claude_client_process(client))
            for composite_key, client in self.claude_sessions.items()
        )

    async def close_captured_claude_clients(
        self, captured: tuple[tuple[str, Any, Any], ...], *, reason: str
    ) -> None:
        """Close exactly the captured clients, busy or idle, settling their work.

        A client created after the capture, such as one of a re-enabled
        backend, is never touched; one still connecting refuses its turn once
        connected, because Claude is disabled by then. A captured client
        counts as closed only once its CLI process has exited: a failed
        disconnect leaves it running after it left ``claude_sessions``, so its
        process is stopped directly, on a retry too. Raises while a captured
        client survives, so a caller can retry.
        """
        for composite_key, client, _process in captured:
            if self.claude_sessions.get(composite_key) is not client:
                continue
            async with self._claude_runtime_generation_lock(composite_key):
                if self.claude_sessions.get(composite_key) is not client:
                    continue
                self._interrupt_claude_session_work(composite_key, reason=reason)
                await self._cleanup_session_locked(composite_key, expected_client=client, reason=reason)
        survivors = [
            key
            for key, client, process in captured
            if self.claude_sessions.get(key) is client
            or not await stop_claude_process(process, logger=logger)
        ]
        if survivors:
            raise RuntimeError(f"{len(survivors)} Claude client(s) survived their close")

    async def _reuse_cached_claude_session_if_available(
        self,
        *,
        composite_key: str,
        base_session_id: str,
        working_path: str,
        context: MessageContext,
        session_key: str,
        stored_claude_session_id: Optional[str],
        current_model: Optional[str],
        effective_effort: Optional[str],
        agent_system_prompt: Optional[str],
        model_hub_launch: "ModelHubLaunch",
        launch_inputs: "_ClaudeLaunchInputs | None" = None,
    ) -> ClaudeSDKClient | None:
        client = self.claude_sessions.get(composite_key)
        if client is None:
            return None
        if await self._evict_terminated_cached_claude_session(
            composite_key,
            client,
        ):
            return None
        next_system_prompt = await self._build_claude_system_prompt(
            context=context,
            session_key=session_key,
            agent_name="claude",
            session_anchor=base_session_id,
            agent_system_prompt=agent_system_prompt,
            working_path=working_path,
            claude_config=launch_inputs.config if launch_inputs is not None else None,
            agent_allowed_tools=None,
        )
        if await self._replace_stale_cached_claude_client(
            composite_key,
            client,
            context=context,
            working_path=working_path,
            effective_effort=effective_effort,
            system_prompt=next_system_prompt,
            model_hub_launch=model_hub_launch,
            launch_inputs=launch_inputs,
        ):
            return None

        try:
            await self._set_claude_model_if_needed(client, current_model)
        except Exception as e:
            logger.warning(f"Failed to update model on cached Claude session: {e}")
        logger.info(
            f"Using existing Claude SDK client for {base_session_id} at {working_path} (model={current_model})"
        )
        self.bind_claude_runtime_session(
            client,
            base_session_id,
            composite_key,
            stored_claude_session_id,
            working_path=working_path,
            fallback_session_key=session_key,
            agent_session_id=self.ensure_agent_session_id(
                context,
                session_key=session_key,
                agent_name="claude",
                session_anchor=base_session_id,
                working_path=working_path,
            ),
        )
        return client

    async def _reuse_cached_claude_subagent_session_if_available(
        self,
        *,
        composite_key: str,
        base_session_id: str,
        working_path: str,
        context: MessageContext,
        session_key: str,
        native_session_id: Optional[str],
        desired_model: Optional[str],
        effective_effort: Optional[str],
        effective_agent: str,
        resolved_agent: _ResolvedClaudeAgentInputs,
        model_hub_launch: "ModelHubLaunch",
        launch_inputs: "_ClaudeLaunchInputs | None" = None,
    ) -> ClaudeSDKClient | None:
        client = self.claude_sessions.get(composite_key)
        if client is None:
            return None
        if await self._evict_terminated_cached_claude_session(
            composite_key,
            client,
        ):
            return None
        self.ensure_agent_session_id(
            context,
            session_key=session_key,
            agent_name="claude",
            session_anchor=base_session_id,
        )
        next_system_prompt = await self._build_claude_system_prompt(
            context=context,
            session_key=session_key,
            agent_name="claude",
            session_anchor=base_session_id,
            agent_system_prompt=resolved_agent.system_prompt,
            working_path=working_path,
            claude_config=launch_inputs.config if launch_inputs is not None else None,
            agent_allowed_tools=resolved_agent.allowed_tools,
        )
        if await self._replace_stale_cached_claude_client(
            composite_key,
            client,
            context=context,
            working_path=working_path,
            effective_effort=effective_effort,
            system_prompt=next_system_prompt,
            model_hub_launch=model_hub_launch,
            launch_inputs=launch_inputs,
        ):
            return None
        if desired_model:
            try:
                await self._set_claude_model_if_needed(client, desired_model)
            except Exception as e:
                logger.warning(f"Failed to update model on cached Claude subagent session: {e}")
        logger.info(
            "Using Claude subagent session for %s at %s (model_override=%s)",
            base_session_id,
            working_path,
            desired_model,
        )
        self.bind_claude_runtime_session(
            client,
            base_session_id,
            composite_key,
            native_session_id,
            working_path=working_path,
            fallback_session_key=session_key,
            agent_session_id=self.ensure_agent_session_id(
                context,
                session_key=session_key,
                agent_name="claude",
                session_anchor=base_session_id,
                working_path=working_path,
            ),
        )
        return client

    async def _wait_for_claude_session_create(self, composite_key: str) -> ClaudeSDKClient | None:
        while True:
            future = self.claude_session_creates.get(composite_key)
            if future is None:
                return None
            logger.info("Waiting for in-flight Claude SDK client create for %s", composite_key)
            client = await asyncio.shield(future)
            if client is not None:
                return client
            client = self.claude_sessions.get(composite_key)
            if client is not None:
                return client
            if self.claude_session_creates.get(composite_key) is future:
                return None

    def _track_claude_session_create(self, composite_key: str) -> asyncio.Future:
        future = asyncio.get_running_loop().create_future()
        self.claude_session_creates[composite_key] = future
        # Retire the key-level teardown record as soon as a replacement starts
        # being built, not once it registers. A new generation that dies with
        # ``-9`` inside ``connect()`` never reaches registration, so the caller
        # reports it with ``client=None`` — and a marker still standing from the
        # previous teardown would classify that genuine crash as our own
        # cleanup, suppressing both the IM notification and the durable Web Chat
        # error row. The old generation keeps its own coverage through the
        # per-client ``_vibe_intentional_teardown`` attribute.
        self._clear_claude_teardown_intent(composite_key)
        return future

    def _untrack_claude_session_create(self, composite_key: str, future: asyncio.Future) -> None:
        if self.claude_session_creates.get(composite_key) is future:
            self.claude_session_creates.pop(composite_key, None)

    def get_base_session_id(self, context: MessageContext, source: str = "human") -> str:
        """Get base session ID based on platform and context (without path)"""
        platform = self._get_context_platform(context)
        session_target = resolve_context_agent_session_target(context)
        if session_target:
            reserved_anchor = str(session_target.get("session_anchor") or "").strip()
            if reserved_anchor:
                return reserved_anchor
        is_dm = bool((context.platform_specific or {}).get("is_dm", False))
        if self.should_allocate_scheduled_anchor(context, source=source):
            return f"{platform}_scheduled-{uuid4().hex}"
        if is_dm:
            use_dm_threads = self._supports_threaded_session(context, is_dm=True)

            if use_dm_threads:
                base_id = context.thread_id or context.message_id or context.channel_id or context.user_id
            else:
                base_id = context.channel_id or context.user_id
        else:
            resolved_thread_id = resolve_context_thread_id(context)
            base_id = resolved_thread_id or context.thread_id
            if platform == "telegram" and base_id:
                return build_thread_session_anchor(platform, context.channel_id, base_id)
            if not base_id:
                use_message_id = True
                getter = getattr(self.controller, "get_im_client_for_context", None)
                if callable(getter):
                    try:
                        im_client = getter(context)
                    except AttributeError:
                        im_client = getattr(self.controller, "im_client", None)
                else:
                    im_client = getattr(self.controller, "im_client", None)
                if im_client and hasattr(im_client, "should_use_message_id_for_channel_session"):
                    use_message_id = bool(im_client.should_use_message_id_for_channel_session(context))
                base_id = context.message_id if use_message_id and context.message_id else context.channel_id
        return f"{platform}_{base_id}"

    @staticmethod
    def _reserved_native_session_id(context: MessageContext) -> Optional[str]:
        """Native session id bound to the selected persisted row (by PK).

        This includes explicit Workbench targets and rows selected for IM turns.
        Only returns the native when the row's backend is Claude; after a backend
        switch, the previous backend's native id must not be resumed."""
        target = resolve_context_agent_session_target(context)
        if not target:
            return None
        native = str(target.get("native_session_id") or "").strip()
        if not native:
            return None
        target_backend = str(target.get("agent_backend") or "").strip()
        if target_backend and target_backend != "claude":
            return None
        return native

    def _get_context_platform(self, context: MessageContext) -> str:
        return (
            context.platform
            or (context.platform_specific or {}).get("platform")
            or getattr(self.config, "platform", "slack")
        )

    def _caller_env_for_context(self, context: MessageContext) -> dict[str, str]:
        """Caller identity AND creation origin for the Agent subprocess env.

        The typed context is passed alongside the platform payload because an
        IM-created Harness definition is created by an Agent run executing
        ``vibe task add`` — this env is the only channel between the conversation that
        asked for it and the ``created_by.caller`` row that records where it came from.
        Dropping the ids here is what left the failure ladder's owner-DM rung dormant
        and the notice unable to name its origin.

        The platform is resolved through ``_get_context_platform`` rather than off the
        context alone, so the captured origin agrees with the platform every other
        session-scoped decision in this handler is made with (the Slack adapter sets
        neither ``context.platform`` nor a payload ``platform``).

        SESSION-STABLE ONLY, and that is not a shortcut. This env is baked into a Claude
        SDK client at spawn and is also the value compared to decide whether a cached
        client may be reused, so the Turn identity and ordinary IM author/message
        fields are dropped. The Controller resolves the active Turn from its own
        in-process registry when ``vibe computer`` reaches it. A trusted remote
        Workbench ACL snapshot is retained:
        changing remote identity or revision must recreate the client rather than let
        one user's resource authority leak into another user's turn.
        ``CallerContext.session_stable`` documents both cases.
        """

        return caller_env_for_platform_payload(
            getattr(context, "platform_specific", None),
            message=context,
            fallback_platform=self._get_context_platform(context),
            session_stable_only=True,
        )

    def should_allocate_scheduled_anchor(self, context: MessageContext, source: str = "human") -> bool:
        if source != "scheduled" or context.thread_id:
            return False
        is_dm = bool((context.platform_specific or {}).get("is_dm", False))
        if not self._supports_threaded_session(context, is_dm=is_dm):
            return False
        if is_dm:
            return True

        im_client = self._get_im_client(context)
        use_message_id = getattr(im_client, "should_use_message_id_for_channel_session", lambda _context=None: True)
        return bool(use_message_id(context))

    def build_message_anchor_base(self, context: MessageContext, message_id: str) -> str:
        return f"{self._get_context_platform(context)}_{message_id}"

    def alias_session_base(
        self,
        context: MessageContext,
        *,
        source_base_session_id: str,
        alias_base_session_id: str,
        target_session_key: Optional[str] = None,
        source_session_key: Optional[str] = None,
        clear_source: bool = False,
    ) -> bool:
        if not source_base_session_id or not alias_base_session_id:
            return False
        resolved_source_key = source_session_key or self._get_session_key(context)
        resolved_target_key = target_session_key or resolved_source_key
        if resolved_target_key == resolved_source_key:
            changed = self.sessions.alias_session_base(
                resolved_target_key,
                source_base_session_id,
                alias_base_session_id,
            )
        else:
            changed = self.sessions.alias_session_base_across_scopes(
                resolved_source_key,
                resolved_target_key,
                source_base_session_id,
                alias_base_session_id,
            )
        cleared = 0
        if clear_source and source_base_session_id != alias_base_session_id:
            cleared = self.sessions.clear_session_base(resolved_source_key, source_base_session_id)
        return bool(changed or cleared)

    @staticmethod
    def _is_reserved_session_anchor(context: MessageContext, base_session_id: str) -> bool:
        """True when this anchor names a reserved, durable Agent Session row.

        ``clear_source`` is decided upstream by ``_build_delivery_alias_strategy`` from
        ``session_target.thread_id is None``. That is a proxy for "this is a throwaway
        channel-level anchor that the delivered message should replace". A durable
        ``--create-session`` definition anchor satisfies the same proxy:
        ``thread_id_from_session_anchor`` splits the anchor at ``:``, so
        ``<platform>_<channel_id>:definition_<uuid>`` reduces to ``<platform>_<channel_id>``
        and the derived thread id equals the channel id, which the function reports as
        ``None``. The proxy therefore cannot tell a provisional anchor from a durable one.

        The clear is a HARD delete of the ``agent_sessions`` row, while the definition keeps
        its now-dangling ``run_definitions.session_id``. Every later fire then dies at
        dispatch with ``agent session id not found``, silently, at ``last_status=failed``
        with no result text, and the definition never recovers on its own.

        Decide from the same authority ``get_base_session_id`` used to mint the anchor: a
        context bound to a reserved Agent Session row is never provisional. Reading the
        reserved row keeps this a fact check rather than a second anchor-format parser that
        would drift from the minting side in ``_session_anchor_with_suffix``.
        """
        reserved = resolve_context_agent_session_target(context)
        if not reserved:
            return False
        reserved_anchor = str(reserved.get("session_anchor") or "").strip()
        return bool(reserved_anchor) and reserved_anchor == str(base_session_id or "").strip()

    def finalize_scheduled_delivery(self, context: MessageContext, sent_message_id: Optional[str]) -> None:
        payload = context.platform_specific or {}
        if payload.get("turn_source") != "scheduled":
            return
        source_base_session_id = payload.get("turn_base_session_id") or ""
        strategy = payload.get("scheduled_delivery_alias") or {}
        mode = strategy.get("mode") or "none"
        if not source_base_session_id or mode == "none":
            return

        alias_base_session_id: Optional[str] = None
        if mode == "sent_message":
            if not sent_message_id:
                return
            alias_base_session_id = self.build_message_anchor_base(context, sent_message_id)
        elif mode == "fixed_base":
            alias_base_session_id = strategy.get("base_session_id")
        if not alias_base_session_id:
            return

        target_session_key = strategy.get("session_key") or self._get_session_key(context)
        clear_source = bool(strategy.get("clear_source", False)) and not self._is_reserved_session_anchor(
            context, source_base_session_id
        )
        self.alias_session_base(
            context,
            source_base_session_id=source_base_session_id,
            alias_base_session_id=alias_base_session_id,
            target_session_key=target_session_key,
            clear_source=clear_source,
        )

        if mode == "sent_message" and sent_message_id:
            platform = self._get_context_platform(context)
            if platform in {"slack", "lark"}:
                delivery_channel_id = payload.get("delivery_override", {}).get("channel_id") or context.channel_id
                self.sessions.mark_thread_active("scheduled", delivery_channel_id, sent_message_id)

    def _supports_threaded_session(self, context: MessageContext, *, is_dm: bool) -> bool:
        getter = getattr(self.controller, "get_im_client_for_context", None)
        if callable(getter):
            try:
                im_client = getter(context)
            except AttributeError:
                im_client = getattr(self.controller, "im_client", None)
        else:
            im_client = getattr(self.controller, "im_client", None)

        if im_client is None:
            return False
        if is_dm:
            return bool(getattr(im_client, "should_use_thread_for_dm_session", lambda: False)())
        return bool(getattr(im_client, "should_use_thread_for_reply", lambda: False)())

    def get_working_path(self, context: MessageContext) -> str:
        """Get working directory - delegate to controller's get_cwd"""
        return self.controller.get_cwd(context)

    def _running_as_root(self) -> bool:
        geteuid = getattr(os, "geteuid", None)
        return bool(geteuid and geteuid() == 0)

    def _should_mark_claude_isolated_env(self) -> bool:
        if os.environ.get("IS_SANDBOX"):
            return False
        return self._running_as_root()

    async def _allow_claude_bypass_tool(self, tool_name: str, tool_input: Dict[str, Any], context: Any):
        logger.info("Auto-approving Claude tool permission request in avibe bypass mode: %s", tool_name)
        return PermissionResultAllow()

    async def _guard_session_only_background_tools(
        self,
        input_data: Dict[str, Any],
        tool_use_id: Optional[str],
        context: Any,
    ) -> Dict[str, Any]:
        """PreToolUse hook governing backend-native, session-only background work.

        Runs in-process, so it needs no file in the user's `~/.claude`. The deny
        reason names the durable `vibe ...` equivalent, which lets the agent
        self-correct within the same turn instead of just failing.

        An advisory outcome deliberately omits `permissionDecision`: injecting
        context must not double as an approval, or this hook would override a
        permission hook the user configured for the same tool.
        """
        try:
            tool_name = str(input_data.get("tool_name") or "")
            tool_input = input_data.get("tool_input") or {}
            decision = check_tool_call(tool_name, tool_input)
            if decision.allowed:
                if not decision.advice:
                    return {}
                specific_output: Dict[str, Any] = {
                    "hookEventName": "PreToolUse",
                }
                if decision.advice:
                    specific_output["additionalContext"] = decision.advice
                return {
                    "hookSpecificOutput": {
                        **specific_output,
                    }
                }
            logger.info(
                "Blocking session-only background tool %s; redirecting to the Avibe Harness",
                tool_name,
            )
            return {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": decision.reason,
                }
            }
        except Exception:
            # A guard that raises must never take the turn down with it.
            logger.exception("Session-only background tool guard failed; allowing the call")
            return {}

    def _build_claude_tool_policy_hooks(
        self,
    ) -> Optional[Dict[str, Any]]:
        """Hook config enforcing the shared tool policy, or None when unavailable."""
        if not CLAUDE_SDK_HOOKS_AVAILABLE or HookMatcher is None:
            return None
        matcher = "|".join(session_only_background_tool_names())

        return {
            "PreToolUse": [
                HookMatcher(
                    matcher=matcher,
                    hooks=[self._guard_session_only_background_tools],
                )
            ]
        }

    def _claude_disallowed_tools(self, hooks: Optional[Dict[str, Any]]) -> list:
        """Disallowed tool names for this launch.

        The hook is the precise enforcement path because it can read arguments and
        return an actionable reason. Only when hooks are unavailable does the
        coarse name-level deny list stand in, and then only for the tools that are
        session-only under every input.
        """
        disallowed = list(CLAUDE_REMOTE_DISALLOWED_TOOLS)
        if hooks is None:
            disallowed.extend(
                name for name in ALWAYS_SESSION_ONLY_TOOL_NAMES if name not in disallowed
            )
        return disallowed

    def _get_claude_cli_path_override(self, claude_config: Any = None) -> Optional[str]:
        from vibe.claude_config import normalize_claude_cli_path

        if claude_config is None:
            claude_config = getattr(self.config, "claude", None)
        return normalize_claude_cli_path(getattr(claude_config, "cli_path", None))

    def _load_agent_file(self, agent_name: str, working_path: str) -> Optional[Dict[str, Any]]:
        """Load an agent file and return its parsed content.

        Searches for agent file in:
        1. Project agents: <working_path>/.claude/agents/<agent_name>.md
        2. Global agents: ~/.claude/agents/<agent_name>.md

        Returns:
            Dict with keys: name, description, prompt, tools, model
            or None if not found/parse error.
        """
        from pathlib import Path
        from vibe.api import parse_claude_agent_file

        # Search paths (project first, then global)
        search_paths = [
            Path(working_path) / ".claude" / "agents" / f"{agent_name}.md",
            Path.home() / ".claude" / "agents" / f"{agent_name}.md",
        ]

        for agent_path in search_paths:
            if agent_path.exists() and agent_path.is_file():
                parsed = parse_claude_agent_file(str(agent_path))
                if parsed:
                    return parsed
                else:
                    logger.warning(f"Failed to parse agent file: {agent_path}")

        logger.warning(f"Agent file not found for '{agent_name}' in {search_paths}")
        return None

    def _resolve_claude_agent_inputs(
        self,
        effective_agent: str | None,
        working_path: str,
        agent_system_prompt: str | None,
    ) -> _ResolvedClaudeAgentInputs:
        """Resolve selected-agent authority independently from prompt injection."""

        agent_data = (
            self._load_agent_file(effective_agent, working_path)
            if effective_agent
            else None
        )
        system_prompt = agent_system_prompt
        if system_prompt is None and agent_data is not None:
            system_prompt = agent_data.get("prompt")
        return _ResolvedClaudeAgentInputs(
            system_prompt=system_prompt,
            allowed_tools=agent_data.get("tools") if agent_data is not None else None,
            model=agent_data.get("model") if agent_data is not None else None,
        )

    def get_session_info(self, context: MessageContext, source: str = "human") -> Tuple[str, str, str]:
        """Get session info: base_session_id, working_path, and composite_key"""
        base_session_id = self.get_base_session_id(context, source=source)
        resolve_target = getattr(self.controller, "resolve_agent_run_target", None)
        if callable(resolve_target):
            target = resolve_target(context, base_session_id=base_session_id, source=source)
            working_path = target.workdir
        else:
            working_path = self.get_working_path(context)
        # Create composite key for internal storage
        composite_key = f"{base_session_id}:{working_path}"
        return base_session_id, working_path, composite_key

    async def _prepare_resume_context(
        self,
        context: MessageContext,
        host_message_ts: Optional[str],
        is_dm: bool,
    ) -> MessageContext:
        im_client = self._get_im_client(context)
        prepare = getattr(im_client, "prepare_resume_context", None)
        if not callable(prepare):
            return context
        try:
            prepared = await prepare(context, host_message_ts=host_message_ts, is_dm=is_dm)
        except Exception as exc:
            logger.warning("Failed to prepare resume context for %s: %s", context.platform, exc)
            return context
        return prepared if isinstance(prepared, MessageContext) else context

    def _supports_resume_threading(self, context: MessageContext, *, is_dm: bool) -> bool:
        im_client = self._get_im_client(context)
        if is_dm:
            return bool(getattr(im_client, "should_use_thread_for_dm_session", lambda: False)())
        uses_thread_replies = bool(getattr(im_client, "should_use_thread_for_reply", lambda: False)())
        if not uses_thread_replies:
            return False
        if context.thread_id:
            return True
        uses_message_anchor = bool(
            getattr(im_client, "should_use_message_id_for_channel_session", lambda _context=None: True)(context)
        )
        return uses_message_anchor

    def _build_resume_confirmation(
        self,
        *,
        agent_label: str,
        session_id: str,
        preview: str = "",
    ) -> str:
        lines = [f"✅ {self._t('success.sessionResumed', agent=agent_label, sessionId=session_id)}"]
        if preview:
            lines.extend(["", preview])
        return "\n".join(lines)

    def _build_resume_followup(
        self,
        context: MessageContext,
        *,
        is_dm: bool,
    ) -> str:
        lines: list[str] = []
        platform = context.platform or self.config.platform
        if context.thread_id:
            if platform == "discord":
                lines.append(self._t("success.sessionResumedContinueDiscordThread"))
            elif platform == "lark":
                lines.append(self._t("success.sessionResumedContinueFeishuThread"))
            else:
                lines.append(self._t("success.sessionResumedContinueThread"))
            if not is_dm:
                lines.append(self._t("success.sessionResumedThreadFreshTip"))
        else:
            lines.append(self._t("success.sessionResumedContinueDirect"))
        return "\n".join(line for line in lines if line)

    def _get_resume_preview(
        self,
        context: MessageContext,
        *,
        agent: str,
        session_id: str,
    ) -> str:
        service_getter = getattr(self.controller, "get_native_session_service", None)
        if callable(service_getter):
            native_session_service = service_getter()
        else:
            native_session_service = getattr(self.controller, "native_session_service", None)
        if native_session_service is None:
            return ""
        try:
            working_path = self.get_working_path(context)
            item = native_session_service.get_session(working_path, agent, session_id)
        except Exception as exc:
            logger.warning("Failed to resolve resume preview for %s session %s: %s", agent, session_id, exc)
            return ""
        if item is None:
            return ""
        return build_resume_preview(item.last_agent_message or item.last_agent_tail)

    def _claude_runtime_generation_lock(self, composite_key: str) -> asyncio.Lock:
        return self.claude_runtime_generation_locks.setdefault(
            composite_key,
            asyncio.Lock(),
        )

    def _claude_runtime_generation_key(
        self,
        context: MessageContext,
        subagent_name: Optional[str],
    ) -> str:
        payload = context.platform_specific or {}
        turn_source = str(payload.get("turn_source") or "human")
        base_session_id = str(payload.get("turn_base_session_id") or "").strip()
        working_path = self.get_working_path(context)
        if not base_session_id:
            base_session_id, working_path, _ = self.get_session_info(
                context,
                source=turn_source,
            )
        settings_key = self._get_settings_key(context)
        routing = self._get_settings_manager(context).get_channel_routing(settings_key)
        effective_agent = subagent_name or (routing.claude_agent if routing else None)
        if effective_agent:
            base_session_id = f"{base_session_id}:{effective_agent}"
        return f"{base_session_id}:{working_path}"

    async def get_or_create_claude_session(
        self,
        context: MessageContext,
        subagent_name: Optional[str] = None,
        subagent_model: Optional[str] = None,
        subagent_reasoning_effort: Optional[str] = None,
        agent_system_prompt: Optional[str] = None,
    ) -> ClaudeSDKClient:
        """Resolve or create one Claude runtime generation under its exact lock."""

        composite_key = self._claude_runtime_generation_key(context, subagent_name)
        while True:
            try:
                async with self._claude_runtime_generation_lock(composite_key):
                    return await self._get_or_create_claude_session_locked(
                        context,
                        subagent_name=subagent_name,
                        subagent_model=subagent_model,
                        subagent_reasoning_effort=subagent_reasoning_effort,
                        agent_system_prompt=agent_system_prompt,
                    )
            except _ClaudeReceiverCleanupRequired as retry:
                # Receiver error handling may need the same generation lock. Wait
                # only after the lock has been released, then retry resolution.
                await self._wait_for_claude_receiver_cleanup(retry.composite_key)

    async def _get_or_create_claude_session_locked(
        self,
        context: MessageContext,
        subagent_name: Optional[str] = None,
        subagent_model: Optional[str] = None,
        subagent_reasoning_effort: Optional[str] = None,
        agent_system_prompt: Optional[str] = None,
    ) -> ClaudeSDKClient:
        """Get existing Claude session or create a new one"""
        payload = context.platform_specific or {}
        turn_source = str(payload.get("turn_source") or "human")
        base_session_id = str(payload.get("turn_base_session_id") or "").strip()
        working_path = self.get_working_path(context)
        if base_session_id:
            composite_key = f"{base_session_id}:{working_path}"
        else:
            base_session_id, working_path, composite_key = self.get_session_info(context, source=turn_source)

        router = getattr(self.controller, "model_hub_runtime", None)
        hub_snapshot = getattr(router, "snapshot", None)
        launch_inputs = _ClaudeLaunchInputs(
            epoch=getattr(self.controller, "claude_runtime_epoch", 0),
            config=getattr(self.config, "claude", None),
            hub_config=hub_snapshot() if callable(hub_snapshot) else None,
        )
        settings_key = self._get_settings_key(context)
        session_key = self._get_session_key(context)
        # Resume the native session bound to the RESERVED workbench row (by PK).
        # The bind WRITE (_bind_reserved_workbench_session) records the native on
        # that row by id; the resume READ must read it back from there, because the
        # (session_key, anchor) projection drifts for avibe (its scope/anchor differ
        # from where the native was bound) and a restart would otherwise fork a fresh
        # session and lose context. Skip it for ANY subagent — explicit (its own
        # session resolved below) OR a routing-default subagent (its namespaced base
        # has its own session) — else the first subagent turn after the subagent is
        # enabled would resume the MAIN transcript under the subagent. IM/CLI turns
        # carry no reserved target, so this is a no-op for them.
        routing_subagent = (getattr(context, "platform_specific", None) or {}).get("routing_subagent")
        stored_claude_session_id = self.sessions.get_claude_session_id(session_key, base_session_id)
        if not subagent_name and not routing_subagent:
            stored_claude_session_id = self._reserved_native_session_id(context) or stored_claude_session_id
        fork_source_claude_session_id: Optional[str] = None
        if not stored_claude_session_id and not subagent_name and not routing_subagent:
            fork_source_claude_session_id = pending_native_fork_source(context, "claude")

        # Read routing overrides via get_channel_routing which correctly
        # resolves DM users from the users store (not the stale channels store).
        routing = self._get_settings_manager(context).get_channel_routing(settings_key)

        # Priority: subagent params > channel config > Agent model.
        # Note: agent frontmatter model is applied later after loading agent file
        effective_agent = subagent_name or (routing.claude_agent if routing else None)
        resolved_agent = self._resolve_claude_agent_inputs(
            effective_agent,
            working_path,
            agent_system_prompt,
        )
        # Store explicit model override (not including default yet)
        from config.v2_settings import routing_model_for_backend, routing_reasoning_effort_for_backend

        explicit_model = subagent_model or routing_model_for_backend(routing, "claude")
        explicit_effort = subagent_reasoning_effort or routing_reasoning_effort_for_backend(routing, "claude")
        session_target = resolve_context_agent_session_target(context)
        if session_target:
            explicit_model = subagent_model or session_target.get("model") or explicit_model
            explicit_effort = subagent_reasoning_effort or session_target.get("reasoning_effort") or explicit_effort

        launch_model = explicit_model
        if not launch_model:
            configured_agent_model = resolved_agent.model
            if configured_agent_model and configured_agent_model.lower() not in ("inherit", ""):
                launch_model = configured_agent_model
        cached_base = (
            f"{base_session_id}:{effective_agent}"
            if effective_agent
            else None
        )
        cached_key = (
            f"{cached_base}:{working_path}"
            if cached_base is not None
            else None
        )
        from modules.agents.model_hub import bind_launch, resolve_model_hub_launch

        model_hub_launch = await resolve_model_hub_launch(
            self.controller,
            "claude",
            launch_model or "",
            process_scope=cached_key or composite_key,
            context=context,
            config=launch_inputs.hub_config,
        )
        bind_launch(context, model_hub_launch)
        runtime_model = model_hub_launch.runtime_model or launch_model
        cached_subagent_model = self._cached_claude_subagent_model(explicit_model, model_hub_launch)
        from modules.agents.opencode.utils import normalize_claude_reasoning_effort

        # Reasoning is a process-creation option, unlike set_model. Resolve it
        # once for both reuse and creation, including the in-flight create path.
        catalog_efforts = (
            model_hub_launch.reasoning_efforts
            if model_hub_launch.channel in {"hub", "native_cli"}
            else backend_model_catalog.catalog_reasoning_efforts_for_model("claude", launch_model)
        )
        effective_effort = normalize_claude_reasoning_effort(
            launch_model, explicit_effort, catalog_efforts,
        )

        if not effective_agent:
            # Claude SDK model changes are control requests; only send one when
            # the effective model actually changes.
            current_model = runtime_model
            client = await self._reuse_cached_claude_session_if_available(
                composite_key=composite_key,
                base_session_id=base_session_id,
                working_path=working_path,
                context=context,
                session_key=session_key,
                stored_claude_session_id=stored_claude_session_id,
                current_model=current_model,
                effective_effort=effective_effort,
                agent_system_prompt=None,
                model_hub_launch=model_hub_launch,
                launch_inputs=launch_inputs,
            )
            if client is not None:
                return client

        if effective_agent:
            assert cached_base is not None and cached_key is not None
            cached_session_id = self.sessions.get_agent_session_id(
                session_key,
                cached_base,
                agent_name="claude",
            )
            client = await self._reuse_cached_claude_subagent_session_if_available(
                composite_key=cached_key,
                base_session_id=cached_base,
                working_path=working_path,
                context=context,
                session_key=session_key,
                native_session_id=cached_session_id,
                desired_model=cached_subagent_model,
                effective_effort=effective_effort,
                effective_agent=effective_agent,
                resolved_agent=resolved_agent,
                model_hub_launch=model_hub_launch,
                launch_inputs=launch_inputs,
            )
            if client is not None:
                return client
            # Always use agent-specific key when effective_agent is set
            # This ensures session continuity even on first use
            composite_key = cached_key
            base_session_id = cached_base
            if cached_session_id:
                stored_claude_session_id = cached_session_id
            else:
                stored_claude_session_id = None

        waiting_client = await self._wait_for_claude_session_create(composite_key)
        if waiting_client is not None:
            if effective_agent:
                client = await self._reuse_cached_claude_subagent_session_if_available(
                    composite_key=composite_key,
                    base_session_id=base_session_id,
                    working_path=working_path,
                    context=context,
                    session_key=session_key,
                    native_session_id=stored_claude_session_id,
                    desired_model=cached_subagent_model,
                    effective_effort=effective_effort,
                    effective_agent=effective_agent,
                    resolved_agent=resolved_agent,
                    model_hub_launch=model_hub_launch,
                    launch_inputs=launch_inputs,
                )
            else:
                client = await self._reuse_cached_claude_session_if_available(
                    composite_key=composite_key,
                    base_session_id=base_session_id,
                    working_path=working_path,
                    context=context,
                    session_key=session_key,
                    stored_claude_session_id=stored_claude_session_id,
                    current_model=runtime_model,
                    effective_effort=effective_effort,
                    agent_system_prompt=None,
                    model_hub_launch=model_hub_launch,
                    launch_inputs=launch_inputs,
                )
            if client is not None:
                return client

        create_future = self._track_claude_session_create(composite_key)
        try:
            client = await self._create_claude_session(
                context=context,
                composite_key=composite_key,
                base_session_id=base_session_id,
                working_path=working_path,
                session_key=session_key,
                stored_claude_session_id=fork_source_claude_session_id or stored_claude_session_id,
                effective_agent=effective_agent,
                explicit_model=explicit_model,
                effective_effort=effective_effort,
                resolved_agent=resolved_agent,
                fork_session=bool(fork_source_claude_session_id),
                launch_inputs=launch_inputs,
            )
            if not create_future.done():
                create_future.set_result(client)
            return client
        except asyncio.CancelledError:
            if not create_future.done():
                create_future.set_result(None)
            raise
        except Exception:
            if not create_future.done():
                create_future.set_result(None)
            raise
        finally:
            self._untrack_claude_session_create(composite_key, create_future)

    async def _create_claude_session(
        self,
        *,
        context: MessageContext,
        composite_key: str,
        base_session_id: str,
        working_path: str,
        session_key: str,
        stored_claude_session_id: Optional[str],
        effective_agent: Optional[str],
        explicit_model: Optional[str],
        effective_effort: Optional[str],
        resolved_agent: _ResolvedClaudeAgentInputs,
        fork_session: bool = False,
        launch_inputs: "_ClaudeLaunchInputs | None" = None,
    ) -> ClaudeSDKClient:
        # One coherent config for the whole launch, taken at the turn's
        # admission: a renewal while this turn resolves or creates its client
        # leaves it on the epoch and config it started with, and its next turn
        # moves it.
        if launch_inputs is None:
            launch_inputs = _ClaudeLaunchInputs(
                epoch=getattr(self.controller, "claude_runtime_epoch", 0),
                config=getattr(self.config, "claude", None),
                hub_config=None,
            )
        runtime_epoch = launch_inputs.epoch
        claude_config = launch_inputs.config
        launch_config = SimpleNamespace(claude=claude_config)

        # Ensure working directory exists
        if not os.path.exists(working_path):
            try:
                os.makedirs(working_path, exist_ok=True)
                logger.info(f"Created working directory: {working_path}")
            except Exception as e:
                logger.error(f"Failed to create working directory {working_path}: {e}")
                working_path = os.getcwd()

        # Claude Code does not auto-discover every selected agent file. The
        # turn-boundary resolver supplies one prompt, allowlist, and model to
        # both cached and cold launch paths.
        agent_system_prompt = resolved_agent.system_prompt
        agent_allowed_tools = resolved_agent.allowed_tools
        agent_model = resolved_agent.model

        # Filter out special values that aren't actual model names
        if agent_model and agent_model.lower() in ("inherit", ""):
            agent_model = None

        # The routed Vibe Agent model is materialized into ``explicit_model``.
        effective_model = explicit_model or agent_model
        from modules.agents.model_hub import (
            build_claude_hub_env,
            claude_settings_for_launch,
            launch_for_context,
        )

        model_hub_launch = launch_for_context(context)
        runtime_model = (
            model_hub_launch.runtime_model
            if model_hub_launch is not None and model_hub_launch.backend == "claude"
            else effective_model
        )
        from modules.agents.opencode.utils import NO_REASONING_EFFORT

        # Determine final system prompt: agent prompt takes precedence over config.
        # Always append avibe system prompt injection so transport
        # capabilities remain available; reply_enhancements only controls
        # quick-reply button instructions.
        skill_catalog_sink: list[dict] = []
        final_system_prompt = await self._build_claude_system_prompt(
            context,
            session_key=session_key,
            agent_name="claude",
            session_anchor=base_session_id,
            agent_system_prompt=agent_system_prompt,
            skill_catalog_sink=skill_catalog_sink,
            working_path=working_path,
            claude_config=claude_config,
            agent_allowed_tools=agent_allowed_tools,
        )

        # Echo native input frames so the long-lived receiver can correlate
        # accepted steering with Claude's actual input consumption.
        extra_args: Dict[str, str | None] = {"replay-user-messages": None}
        if runtime_model:
            extra_args["model"] = runtime_model

        claude_stderr_lines: list[str] = []

        def _capture_claude_stderr(line: str) -> None:
            text = (line or "").strip()
            if not text:
                return
            claude_stderr_lines.append(text)
            if len(claude_stderr_lines) > 40:
                del claude_stderr_lines[:-40]
            logger.warning("Claude CLI stderr for %s: %s", composite_key, text)

        # V2Config-driven Anthropic env composition, centralised so the
        # control-channel client (``agent_auth_service``) cannot drift
        # away from this site's auth_mode handling.
        from vibe.claude_config import (
            CLAUDE_MEMORY_DISABLED_SETTINGS,
            CLAUDE_NATIVE_MCP_DISABLED,
            CLAUDE_SETTING_SOURCES,
            build_claude_subprocess_env,
        )
        from core.agent_path import prepend_managed_tools_to_path

        claude_env = build_claude_subprocess_env(claude_config)
        if model_hub_launch is not None:
            claude_env = build_claude_hub_env(claude_env, model_hub_launch)
        claude_env.update(self._caller_env_for_context(context))
        claude_env.update(
            managed_skill_environment(
                working_path,
                project_base=managed_skill_project_base(context),
            )
        )
        prepend_managed_tools_to_path(
            claude_env,
            base_env=os.environ,
            working_dir=working_path,
        )
        git_path_state = claude_env["PATH"] if "PATH" in claude_env else os.environ.get("PATH", "")
        claude_env[AVIBE_CLAUDE_PROCESS_OWNER_ENV] = AVIBE_CLAUDE_SESSION_OWNER
        if self._should_mark_claude_isolated_env():
            claude_env["IS_SANDBOX"] = "1"
            logger.info("Detected Claude bypassPermissions running as root; marking Claude subprocess as isolated")

        tool_policy_hooks = self._build_claude_tool_policy_hooks()

        option_kwargs: Dict[str, Any] = {
            "permission_mode": CLAUDE_REMOTE_PERMISSION_MODE,
            "cwd": working_path,
            "system_prompt": final_system_prompt,
            "resume": stored_claude_session_id if stored_claude_session_id else None,
            "fork_session": bool(fork_session and stored_claude_session_id),
            "extra_args": extra_args,
            "settings": claude_settings_for_launch(CLAUDE_MEMORY_DISABLED_SETTINGS, model_hub_launch),
            "setting_sources": CLAUDE_SETTING_SOURCES,
            **CLAUDE_NATIVE_MCP_DISABLED,
            "skills": [],
            "sandbox": CLAUDE_REMOTE_SANDBOX,
            # Disable interactive-only Claude Code tools that remote IM sessions
            # cannot answer programmatically, plus any session-only background
            # tool the hook path cannot cover.
            "disallowed_tools": self._claude_disallowed_tools(tool_policy_hooks),
            "env": claude_env,  # Pass Anthropic/Claude env vars
            "stderr": _capture_claude_stderr,
            "max_buffer_size": CLAUDE_SDK_MAX_BUFFER_SIZE,
            "can_use_tool": self._allow_claude_bypass_tool,
        }
        if tool_policy_hooks:
            option_kwargs["hooks"] = tool_policy_hooks
        cli_path_override = self._get_claude_cli_path_override(claude_config)
        if cli_path_override:
            option_kwargs["cli_path"] = cli_path_override
        if effective_effort == NO_REASONING_EFFORT:
            # The exact model declaration admitted Off. Claude expresses that
            # choice through the thinking switch, not an `effort="none"` tier.
            option_kwargs["thinking"] = {"type": "disabled"}
        elif effective_effort:
            option_kwargs["effort"] = effective_effort
        # Only set allowed_tools if agent file specifies tools.
        # Omitting the field keeps SDK default tool behavior.
        if agent_allowed_tools is not None:
            option_kwargs["allowed_tools"] = agent_allowed_tools

        options = ClaudeAgentOptions(**option_kwargs)

        # Log session creation details
        logger.info(f"Creating Claude client for {base_session_id} at {working_path}")
        logger.info(f"  Working directory: {working_path}")
        logger.info(f"  Resume session ID: {stored_claude_session_id}")
        logger.info(f"  Options.resume: {options.resume}")
        logger.info(f"  Options.fork_session: {getattr(options, 'fork_session', False)}")
        if effective_agent:
            logger.info(f"  Subagent: {effective_agent}")
        if effective_model:
            logger.info(f"  Model: {effective_model}")
        if effective_effort == NO_REASONING_EFFORT:
            logger.info("  Thinking: disabled")
        elif effective_effort:
            logger.info(f"  Effort: {effective_effort}")

        # Log if we're resuming a session
        if stored_claude_session_id:
            logger.info(f"Attempting to resume Claude session {stored_claude_session_id}")
        else:
            logger.info(f"Creating new Claude session")

        if self._claude_disabled():
            # Turned off after this turn was admitted: start nothing.
            raise ClaudeBackendDisabledError("claude backend disabled")

        # Create new Claude client
        client = ClaudeSDKClient(options=options)
        setattr(client, "_vibe_pending_skill_catalog", skill_catalog_sink[0] if skill_catalog_sink else None)
        setattr(client, "_vibe_stderr_lines", claude_stderr_lines)
        setattr(client, "_vibe_caller_env", self._caller_env_for_context(context))
        setattr(
            client,
            "_vibe_managed_skills_env",
            managed_skill_environment(
                working_path,
                project_base=managed_skill_project_base(context),
            ),
        )
        setattr(client, "_vibe_git_path_state", git_path_state)
        setattr(client, "_vibe_reasoning_effort", effective_effort)
        setattr(client, "_vibe_runtime_epoch", runtime_epoch)
        setattr(
            client,
            "_vibe_model_hub_fingerprint",
            model_hub_launch.fingerprint if model_hub_launch is not None else "direct",
        )

        # Log the actual options being used
        logger.info("ClaudeAgentOptions details:")
        logger.info(f"  - permission_mode: {options.permission_mode}")
        logger.info(f"  - cwd: {options.cwd}")
        logger.info(f"  - system_prompt: {options.system_prompt}")
        logger.info(f"  - resume: {options.resume}")
        logger.info(f"  - continue_conversation: {options.continue_conversation}")
        logger.info(f"  - cli_path: {options.cli_path}")
        if effective_agent:
            logger.info(f"  - subagent: {effective_agent}")

        # Connect the client
        try:
            await self._connect_claude_client(client)
            governor_from_controller(self.controller).apply_to_pid(
                get_claude_client_pid(client),
                label="claude",
            )
        except Exception as exc:
            router = getattr(self.controller, "model_hub_runtime", None)
            record_failure = getattr(router, "record_native_failure", None)
            if callable(record_failure):
                try:
                    await record_failure(context, str(exc))
                except Exception:
                    logger.warning(
                        "Failed to record Model Hub Claude startup failure",
                        exc_info=True,
                    )
            terminal_turn_id = str(
                (getattr(context, "platform_specific", None) or {}).get(
                    "turn_token"
                )
                or ""
            ).strip()
            self._retire_model_hub_process_scope(
                composite_key,
                terminal_turn_id=terminal_turn_id or None,
            )
            stderr_text = "\n".join(claude_stderr_lines)
            match = CLAUDE_NO_CONVERSATION_RE.search(stderr_text) or CLAUDE_NO_CONVERSATION_RE.search(str(exc))
            if match:
                # FAIL LOUD: a session bound to a native id that no longer resumes
                # (cwd changed, expired, or gone) surfaces the error rather than
                # silently starting a fresh session — silent recovery hides the
                # context loss and strands the user in an empty conversation
                # (product decision: no silent fallbacks). The persisted mapping is
                # kept so resuming in the correct cwd still works.
                raise ClaudeSessionNotFoundError(
                    session_id=match.group(1),
                    working_path=str(working_path),
                    stderr=stderr_text,
                ) from exc
            raise

        if self._claude_disabled():
            # Turned off while this client connected, possibly after the
            # disable captured the live clients, so nothing else would close it.
            process = get_claude_client_process(client)
            try:
                await client.disconnect()
            except Exception:
                logger.warning("Failed to disconnect a Claude client of a disabled backend", exc_info=True)
            await stop_claude_process(process, logger=logger)
            self._retire_model_hub_process_scope(composite_key)
            raise ClaudeBackendDisabledError("claude backend disabled")

        self.claude_system_prompts[composite_key] = final_system_prompt
        setattr(client, "_vibe_current_model", effective_model)
        self.bind_claude_runtime_session(
            client,
            base_session_id,
            composite_key,
            None if fork_session else stored_claude_session_id,
            working_path=working_path,
            fallback_session_key=session_key,
            agent_session_id=self.ensure_agent_session_id(
                context,
                session_key=session_key,
                agent_name="claude",
                session_anchor=base_session_id,
                working_path=working_path,
            ),
        )
        self.claude_sessions[composite_key] = client
        # Normally already cleared when the create was tracked; kept as the
        # backstop for any path that builds a client without going through
        # ``_track_claude_session_create``.
        self._clear_claude_teardown_intent(composite_key)
        logger.info(f"Created new Claude SDK client for {base_session_id} at {working_path}")

        return client

    async def _build_claude_system_prompt(
        self,
        context: MessageContext,
        *,
        session_key: str,
        agent_name: str,
        session_anchor: str,
        agent_system_prompt: Optional[str],
        working_path: Optional[str] = None,
        skill_catalog_sink: list[dict] | None = None,
        claude_config: Any = None,
        agent_allowed_tools: list[str] | None = None,
    ) -> str | Dict[str, str]:
        if claude_config is None:
            claude_config = self.config.claude
        base_prompt = agent_system_prompt or claude_config.system_prompt
        quick_replies_on = getattr(self.config, "reply_enhancements", True)
        platform = context.platform or (context.platform_specific or {}).get("platform") or self.config.platform

        self.ensure_agent_session_id(
            context,
            session_key=session_key,
            agent_name=agent_name,
            session_anchor=session_anchor,
        )

        system_prompt_injection = await asyncio.to_thread(
            build_system_prompt_injection,
            agent_instructions=base_prompt or "",
            include_quick_replies=quick_replies_on and platform != "wechat",
            context=context,
            fallback_platform=platform,
            enabled_agents=get_enabled_agents_for_prompt(self.controller),
            skills_cwd=working_path,
            skills_project_base=managed_skill_project_base(context),
            skill_catalog_sink=skill_catalog_sink,
        )

        if base_prompt:
            return system_prompt_injection
        return {
            "type": "preset",
            "preset": "claude_code",
            "append": system_prompt_injection,
        }

    async def _prepare_backend_for_resume(
        self,
        agent: str,
        *,
        base_session_id: str,
        session_key: str,
        working_path: str,
    ) -> None:
        """Let the backend prepare scoped runtime state before a resume bind."""
        agent_service = getattr(self.controller, "agent_service", None)
        backend = getattr(agent_service, "agents", {}).get(agent) if agent_service else None
        prepare = getattr(backend, "prepare_resume_binding", None)
        if callable(prepare):
            logger.info("Preparing %s runtime before resuming session %s", agent, base_session_id)
            await prepare(
                base_session_id=base_session_id,
                session_key=session_key,
                working_path=working_path,
            )

    async def handle_resume_session_submission(
        self,
        user_id: str,
        channel_id: Optional[str],
        thread_id: Optional[str],
        agent: Optional[str],
        session_id: Optional[str],
        host_message_ts: Optional[str] = None,
        is_dm: bool = False,
        platform: Optional[str] = None,
    ) -> None:
        """Bind a provided session_id to the current thread for the chosen agent."""
        from modules.settings_manager import ChannelRouting

        try:
            if not agent or not session_id:
                raise ValueError("Agent and session ID are required to resume.")

            if getattr(self.controller, "agent_service", None):
                available_agents = set(self.controller.agent_service.agents.keys())
                if agent not in available_agents:
                    raise ValueError(f"Agent '{agent}' is not enabled.")

            reuse_thread = True
            if host_message_ts and thread_id and thread_id == host_message_ts:
                reuse_thread = False

            target_thread = thread_id if reuse_thread else None

            context = MessageContext(
                user_id=user_id,
                channel_id=channel_id or user_id,
                platform=platform or self.config.platform,
                thread_id=target_thread or None,
                message_id=host_message_ts or None,
                platform_specific={"is_dm": is_dm},
            )
            thread_capable = self._supports_resume_threading(context, is_dm=is_dm)

            settings_key = self._get_settings_key(context)
            session_key = self._get_session_key(context)
            settings_manager = self._get_settings_manager(context)
            current_routing = settings_manager.get_channel_routing(settings_key)
            preserve_scope_overrides = bool(
                current_routing and self._routing_matches_backend(current_routing, agent)
            )

            routing = ChannelRouting(
                agent_name=agent,
                model=current_routing.model if preserve_scope_overrides else None,
                reasoning_effort=current_routing.reasoning_effort if preserve_scope_overrides else None,
                opencode_agent=current_routing.opencode_agent if current_routing else None,
                claude_agent=current_routing.claude_agent if current_routing else None,
                codex_agent=current_routing.codex_agent if current_routing else None,
            )
            await asyncio.to_thread(settings_manager.set_channel_routing, settings_key, routing)

            agent_label = agent.capitalize()
            preview = self._get_resume_preview(context, agent=agent, session_id=session_id)
            confirmation = self._build_resume_confirmation(
                agent_label=agent_label,
                session_id=session_id,
                preview=preview,
            )

            initial_context = context
            if thread_capable and not target_thread:
                initial_context = MessageContext(
                    user_id=context.user_id,
                    channel_id=context.channel_id,
                    platform=context.platform,
                    thread_id=None,
                    message_id=context.message_id,
                    platform_specific=context.platform_specific,
                    files=context.files,
                )

            confirmation_ts = await self._get_im_client(initial_context).send_message(
                initial_context, confirmation, parse_mode="markdown"
            )

            followup_context = context
            if thread_capable and not target_thread:
                anchor_context = MessageContext(
                    user_id=context.user_id,
                    channel_id=context.channel_id,
                    platform=context.platform,
                    thread_id=None,
                    message_id=confirmation_ts,
                    platform_specific=context.platform_specific,
                    files=context.files,
                )
                followup_context = await self._prepare_resume_context(anchor_context, confirmation_ts, is_dm)

            followup = self._build_resume_followup(followup_context, is_dm=is_dm)
            if followup:
                await self._get_im_client(followup_context).send_message(
                    followup_context,
                    followup,
                    parse_mode="markdown",
                )

            mapped_thread = followup_context.thread_id or confirmation_ts
            if thread_capable:
                mapping_context = MessageContext(
                    user_id=user_id,
                    channel_id=followup_context.channel_id,
                    platform=followup_context.platform,
                    thread_id=mapped_thread,
                    message_id=confirmation_ts,
                    platform_specific={"is_dm": is_dm},
                )
            else:
                mapping_context = MessageContext(
                    user_id=user_id,
                    channel_id=followup_context.channel_id,
                    platform=followup_context.platform,
                    thread_id=None,
                    message_id=None,
                    platform_specific={"is_dm": is_dm},
                )
            base_session_id = self.get_base_session_id(mapping_context)
            working_path = self.get_working_path(mapping_context)

            await self._prepare_backend_for_resume(
                agent,
                base_session_id=base_session_id,
                session_key=session_key,
                working_path=working_path,
            )

            # The anchor is the bare base for every backend. OpenCode no longer
            # folds working_path into the key (the cwd is a per-request param that
            # lives on the ``workdir`` column, not part of the thread identity), so
            # this writer must match the bare-anchor read path in
            # OpenCodeSessionManager.get_or_create_session_id — otherwise a resumed
            # OpenCode session is written under ``base:/cwd`` but the next message
            # looks up ``base`` and forks a different session.
            mapping_key = base_session_id

            # Resume creates a FRESH session record, never mutates an existing one:
            # clear any prior binding at this anchor first so the bind below INSERTs
            # a new row (new PK) bound to the user-selected native, instead of
            # UPDATE-ing the current row's native_session_id — which the write-once
            # guard would (correctly) drop, silently leaving the thread on its old
            # conversation (Codex P2). A no-op when the anchor is a brand-new
            # confirmation message (channel/DM resume).
            #
            # A thread is ONE session per (scope, anchor). If this anchor already
            # holds a row pinned to a DIFFERENT backend (e.g. a Feishu resume button
            # fired inside an existing thread, which bypasses the scope-only command
            # guard), clear that row too — otherwise the bind below collides with the
            # (scope_id, session_anchor) unique invariant and resume fails after
            # channel routing was already updated (Codex P2).
            finder = getattr(self.sessions, "find_session_for_anchor", None)
            if callable(finder):
                try:
                    prior = finder(session_key, mapping_key)
                except Exception:
                    prior = None
                prior_agent = str((prior or {}).get("agent_variant") or (prior or {}).get("agent_backend") or "")
                if prior_agent and prior_agent != agent:
                    self.sessions.remove_agent_session(session_key, prior_agent, mapping_key)
            self.sessions.remove_agent_session(session_key, agent, mapping_key)
            self.sessions.set_agent_session_mapping(session_key, agent, mapping_key, session_id)
            self.sessions.mark_thread_active(user_id, context.channel_id, mapped_thread)
        except Exception as e:
            logger.error(f"Error resuming session: {e}", exc_info=True)
            context = MessageContext(
                user_id=user_id,
                channel_id=channel_id or user_id,
                platform=platform or self.config.platform,
                thread_id=thread_id or None,
                platform_specific={"is_dm": is_dm},
            )
            await self._get_im_client(context).send_message(
                context,
                f"❌ {self._t('error.resumeSubmitFailed', error=self._settings_error_text(e))}",
            )

    def _routing_matches_backend(self, routing, backend: str) -> bool:
        agent_name = getattr(routing, "agent_name", None)
        if not agent_name:
            return False
        if str(agent_name) == str(backend):
            return True
        store = getattr(self.controller, "vibe_agent_store", None)
        if store is None:
            return False
        try:
            agent = store.get(str(agent_name))
        except Exception:
            return False
        return bool(agent and getattr(agent, "backend", None) == backend)

    def _retire_model_hub_process_scope(
        self,
        composite_key: str,
        *,
        terminal_turn_id: Optional[str] = None,
    ) -> None:
        router = getattr(self.controller, "model_hub_runtime", None)
        retire = getattr(router, "retire_process_scope", None)
        if callable(retire):
            if terminal_turn_id is None:
                retire("claude", composite_key)
            else:
                retire(
                    "claude",
                    composite_key,
                    terminal_turn_id=terminal_turn_id,
                )

    async def cleanup_session(
        self,
        composite_key: str,
        *,
        current_receiver_task=None,
        retire_model_hub_scope: bool = True,
        activation_retired: bool = False,
        expected_client=None,
        reason: str = "unspecified",
    ):
        """Clean up one Claude generation under the same lock used by creation.

        ``expected_client`` names the generation the caller means to retire.
        Cleanup resolves the composite key again under the lock, so a caller
        acting on a client that has since been replaced would otherwise tear
        down the healthy replacement instead.
        """

        async with self._claude_runtime_generation_lock(composite_key):
            await self._cleanup_session_locked(
                composite_key,
                current_receiver_task=current_receiver_task,
                retire_model_hub_scope=retire_model_hub_scope,
                activation_retired=activation_retired,
                expected_client=expected_client,
                reason=reason,
            )

    async def _cleanup_session_locked(
        self,
        composite_key: str,
        *,
        current_receiver_task=None,
        retire_model_hub_scope: bool = True,
        activation_retired: bool = False,
        expected_client=None,
        reason: str = "unspecified",
    ):
        """Clean up a specific session by composite key"""
        client = self.claude_sessions.get(composite_key)
        if expected_client is not None and client is not expected_client:
            # The named generation is gone: either already retired, or replaced
            # by a client that owns the key now. Containing a stale teardown
            # must not become a second teardown.
            logger.info(
                "Skipping Claude cleanup for session %s: reason=%s named generation no longer owns the key",
                composite_key,
                reason,
            )
            return
        activation_retired = activation_retired or bool(
            getattr(client, "_vibe_runtime_activation_retired", False)
        )
        if client is not None and not activation_retired:
            if not self._retire_claude_runtime_activation(
                composite_key,
                client,
                lambda: self.claude_sessions.get(composite_key) is client,
            ):
                return
        receiver_task = self.receiver_tasks.get(composite_key)
        if client is not None or receiver_task is not None:
            identity = self._claude_runtime_activation_identity(client)
            logger.info(
                "Retiring Claude runtime session=%s reason=%s busy=%s "
                "runtime_generation=%s client_identity=%s receiver_identity=%s "
                "receiver_done=%s pid=%s",
                composite_key,
                reason,
                composite_key in self.active_sessions,
                identity.generation if identity is not None else None,
                id(client) if client is not None else None,
                id(receiver_task) if receiver_task is not None else None,
                receiver_task.done() if receiver_task is not None else None,
                get_claude_client_pid(client),
            )
        receiver_task = self.receiver_tasks.pop(composite_key, None)
        client = self.claude_sessions.pop(composite_key, None)
        if client is not None and retire_model_hub_scope:
            self._retire_model_hub_process_scope(composite_key)
        cleanup_from_receiver = receiver_task is not None and receiver_task is current_receiver_task
        native_session_id = getattr(client, "_vibe_native_session_id", None)
        keep_pid = get_claude_client_pid(client)
        self.clear_session_tracking(composite_key)
        if client is not None or receiver_task is not None:
            # Only a generation that actually existed can produce the signal the
            # marker explains. Recording one for an already-empty key leaves a
            # 120s window in which the NEXT client's genuine ``-9`` — say, dying
            # inside ``connect()`` before registration can clear the record — is
            # suppressed as though the service had killed it.
            self._mark_claude_teardown_intentional(composite_key, client)

        try:
            # Close the SDK client first so its receive stream can finish normally.
            # Cancelling the receiver first can leave the SDK's anyio cancel scope
            # retrying cancellation on every event-loop tick.
            if client is not None:
                if cleanup_from_receiver:
                    self._disconnect_client_after_receiver(
                        client,
                        composite_key,
                        receiver_task,
                        reason=reason,
                    )
                else:
                    await self._disconnect_client(
                        client,
                        composite_key,
                        reason=reason,
                    )
        finally:
            if not cleanup_from_receiver:
                await self._stop_receiver_task(receiver_task, composite_key)
            # ``disconnect()`` on a hung client can block for seconds, so the
            # owner set is re-read here rather than before it: by now another
            # client may legitimately own a process resuming the same native
            # session id, and it must not be reaped as a duplicate.
            await self._reap_duplicate_resume_processes(
                composite_key,
                native_session_id,
                keep_pid=keep_pid if cleanup_from_receiver else None,
            )

    async def _reap_duplicate_resume_processes(
        self,
        composite_key: str,
        native_session_id: Optional[str],
        *,
        keep_pid: Optional[int],
    ) -> None:
        """Reap leftover processes for one native session id, ownership-first.

        Generation locks are per composite key, so another key can be starting
        a client for the same native session id right now. Between
        ``connect()`` and registration that client owns a live subprocess that
        ``claude_sessions`` cannot yet report, and ``keep_pid`` is ``None`` on
        every cleanup that does not run from the receiver task — so the reap is
        deferred rather than run against an incomplete owner set. The same
        applies when a registered client's pid cannot be resolved. The periodic
        orphan reaper, which reconciles against the persisted ownership
        registry, remains the backstop for anything left behind.
        """
        if not native_session_id:
            return
        creates_in_flight = [key for key in self.claude_session_creates if key != composite_key]
        if creates_in_flight:
            logger.info(
                "Deferring duplicate Claude reap for session %s: %d client create(s) in flight",
                composite_key,
                len(creates_in_flight),
            )
            return
        owned_pids, owner_set_complete = self._live_claude_client_pids()
        if not owner_set_complete:
            logger.info(
                "Deferring duplicate Claude reap for session %s: a registered client's pid is unresolved",
                composite_key,
            )
            return
        await reap_duplicate_claude_resume_processes(
            native_session_id,
            keep_pid=keep_pid,
            exclude_pids=owned_pids,
            cli_path=self._get_claude_cli_path_override(),
            logger=logger,
        )

    async def _disconnect_client(
        self,
        client,
        composite_key: str,
        *,
        reason: str,
    ) -> None:
        try:
            await client.disconnect()
        except Exception as e:
            logger.error(f"Error disconnecting Claude session {composite_key}: {e}")
        logger.info(
            "Cleaned up Claude session %s reason=%s client_identity=%s",
            composite_key,
            reason,
            id(client),
        )

    def _disconnect_client_after_receiver(
        self,
        client,
        composite_key: str,
        receiver_task,
        *,
        reason: str,
    ) -> None:
        async def _run() -> None:
            if receiver_task is not None:
                try:
                    await receiver_task
                except asyncio.CancelledError:
                    pass
                except Exception as e:
                    logger.warning("Claude receiver ended with error before deferred disconnect: %s", e)
            await self._disconnect_client(client, composite_key, reason=reason)

        asyncio.create_task(_run())

    async def _stop_receiver_task(self, receiver_task, composite_key: str) -> None:
        if receiver_task is None:
            return
        receiver_result_retrieved = False
        if not receiver_task.done():
            try:
                await asyncio.wait_for(asyncio.shield(receiver_task), timeout=0.1)
            except asyncio.TimeoutError:
                pass
            except asyncio.CancelledError:
                pass
            except Exception as e:
                receiver_result_retrieved = True
                logger.warning("Claude receiver ended with error during cleanup: %s", e)
        if receiver_task.done() and not receiver_result_retrieved:
            self._drain_receiver_task_exception(receiver_task)
        if not receiver_task.done():
            receiver_task.cancel()
            try:
                await receiver_task
            except asyncio.CancelledError:
                pass
            except Exception:
                pass
        logger.info(f"Cancelled receiver task for session {composite_key}")

    @staticmethod
    def _drain_receiver_task_exception(receiver_task) -> None:
        try:
            exc = receiver_task.exception()
        except asyncio.CancelledError:
            return
        except Exception as e:
            logger.warning("Error reading Claude receiver cleanup result: %s", e)
            return
        if exc is not None:
            logger.warning("Claude receiver ended with error during cleanup: %s", exc)

    def _claude_runtime_ownership_target(
        self,
        composite_key: str,
        client: ClaudeSDKClient,
        *,
        known_activity_keys: tuple[str, ...] | None = None,
        known_route_keys: tuple[str, ...] | None = None,
    ) -> "RuntimeResourceTarget | None":
        from core.runtime_ownership import (
            RuntimeResourceTarget,
            RuntimeSessionBinding,
        )

        base_session_id = str(
            getattr(client, "_vibe_runtime_base_session_id", "") or ""
        ).strip()
        workdir = str(getattr(client, "_vibe_runtime_workdir", "") or "").strip()
        fallback_session_key = str(
            getattr(client, "_vibe_runtime_fallback_session_key", "") or ""
        ).strip()
        agent_session_id = str(
            getattr(client, "_vibe_agent_session_id", "") or ""
        ).strip()
        runtime_key = str(
            getattr(client, "_vibe_runtime_session_key", "") or ""
        ).strip()
        if (
            not base_session_id
            or not agent_session_id
            or not workdir
            or not fallback_session_key
            or runtime_key != composite_key
        ):
            logger.error(
                "Claude runtime ownership mapping is incomplete for resource=%s",
                composite_key,
            )
            return None
        if known_activity_keys is None or known_route_keys is None:
            known_activity_keys, known_route_keys = (
                self._claude_runtime_ownership_known_keys()
            )
        return RuntimeResourceTarget(
            backend="claude",
            resource_key=composite_key,
            bindings=(
                RuntimeSessionBinding(
                    session_id=agent_session_id,
                    session_anchor=base_session_id,
                    workdir=workdir,
                    activity_runtime_keys=(runtime_key,),
                    fallback_route_keys=(fallback_session_key,),
                ),
            ),
            known_activity_runtime_keys=known_activity_keys,
            known_fallback_route_keys=known_route_keys,
        )

    def _claude_runtime_ownership_known_keys(
        self,
    ) -> tuple[tuple[str, ...], tuple[str, ...]]:
        clients = tuple(self.claude_sessions.values())
        return (
            tuple(
                sorted(
                    {
                        str(
                            getattr(
                                candidate,
                                "_vibe_runtime_session_key",
                                "",
                            )
                            or ""
                        )
                        for candidate in clients
                        if getattr(candidate, "_vibe_runtime_session_key", None)
                    }
                )
            ),
            tuple(
                sorted(
                    {
                        str(
                            getattr(
                                candidate,
                                "_vibe_runtime_fallback_session_key",
                                "",
                            )
                            or ""
                        )
                        for candidate in clients
                        if getattr(
                            candidate,
                            "_vibe_runtime_fallback_session_key",
                            None,
                        )
                    }
                )
            ),
        )

    def _claude_runtime_ownership_targets(
        self,
        items: tuple[tuple[str, ClaudeSDKClient], ...] | None = None,
    ) -> dict[str, "RuntimeResourceTarget"]:
        selected = items if items is not None else tuple(self.claude_sessions.items())
        known_activity_keys, known_route_keys = (
            self._claude_runtime_ownership_known_keys()
        )
        targets = {}
        for composite_key, client in selected:
            target = self._claude_runtime_ownership_target(
                composite_key,
                client,
                known_activity_keys=known_activity_keys,
                known_route_keys=known_route_keys,
            )
            if target is not None:
                targets[composite_key] = target
        return targets

    def _claude_runtime_ownership_snapshot(
        self,
        composite_key: str,
        client: ClaudeSDKClient,
    ):
        from core.runtime_ownership import wake_runtime_ownership

        target = self._claude_runtime_ownership_target(composite_key, client)
        provider = getattr(self.controller, "runtime_ownership", None)
        snapshot = getattr(provider, "snapshot", None)
        if target is None or not callable(snapshot):
            logger.error(
                "Claude runtime ownership provider unavailable for resource=%s",
                composite_key,
            )
            return None
        result = snapshot(target)
        wake_runtime_ownership(self.controller, result)
        return result

    def runtime_ownership_snapshots(self) -> tuple[Any, ...] | None:
        from core.runtime_ownership import wake_runtime_ownership

        items = tuple(self.claude_sessions.items())
        targets_by_key = self._claude_runtime_ownership_targets(items)
        if len(targets_by_key) != len(items):
            return None
        provider = getattr(self.controller, "runtime_ownership", None)
        snapshot_many = getattr(provider, "snapshot_many", None)
        if not callable(snapshot_many):
            logger.error("Claude runtime ownership batch provider unavailable")
            return None
        results = tuple(snapshot_many(tuple(targets_by_key.values())))
        if len(results) != len(targets_by_key):
            logger.error("Claude runtime ownership batch returned incomplete results")
            return None
        for result in results:
            wake_runtime_ownership(self.controller, result)
        return results

    async def evict_idle_sessions(
        self,
        idle_timeout: float,
        stuck_active_multiplier: float = DEFAULT_STUCK_ACTIVE_IDLE_EVICTION_MULTIPLIER,
        stuck_active_floor_seconds: float = DEFAULT_STUCK_ACTIVE_IDLE_EVICTION_FLOOR_SECONDS,
    ) -> int:
        """Disconnect Claude sessions that have been idle beyond the timeout.

        A client from before the latest runtime renewal can never serve another
        turn, so it is disconnected as soon as it is idle, even when
        ``idle_timeout <= 0`` turns idle eviction off.

        Durable Turn and Activity ownership always vetoes reclamation, even
        during silent inference or tools. The age backstop repairs an
        adapter-local active flag only after durable ownership independently
        allows reclamation. Pass ``stuck_active_multiplier <= 0`` to disable
        that stale-flag repair.
        """
        stuck_threshold = None
        if idle_timeout > 0 and stuck_active_multiplier > 0:
            stuck_threshold = max(
                idle_timeout * stuck_active_multiplier,
                max(0.0, stuck_active_floor_seconds),
            )

        now = time.monotonic()
        expired: list[tuple[str, float]] = []

        ownership_items = tuple(
            (composite_key, client)
            for composite_key in self.session_last_activity
            if (client := self.claude_sessions.get(composite_key)) is not None
            and (
                self._idle_eviction_after(client, idle_timeout) is not None
                or (stuck_threshold is not None and composite_key in self.active_sessions)
            )
        )
        targets_by_key = self._claude_runtime_ownership_targets(ownership_items)
        provider = getattr(self.controller, "runtime_ownership", None)
        snapshot_many = getattr(provider, "snapshot_many", None)
        ownership_by_key = {}
        if targets_by_key and callable(snapshot_many):
            from core.runtime_ownership import wake_runtime_ownership

            results = await asyncio.to_thread(
                snapshot_many,
                tuple(targets_by_key.values()),
            )
            ownership_by_key = {
                result.resource_key: result for result in results
            }
            if len(ownership_by_key) != len(targets_by_key):
                logger.error(
                    "Claude runtime ownership batch returned incomplete results"
                )
                ownership_by_key = {}
            else:
                for result in results:
                    wake_runtime_ownership(self.controller, result)
        elif targets_by_key:
            logger.error("Claude runtime ownership batch provider unavailable")

        for composite_key, last_activity in list(self.session_last_activity.items()):
            client = self.claude_sessions.get(composite_key)
            if client is None:
                self.session_last_activity.pop(composite_key, None)
                self.session_turn_started.pop(composite_key, None)
                self.active_sessions.discard(composite_key)
                continue
            ownership = ownership_by_key.get(composite_key)
            if ownership is None:
                continue
            idle_for = now - last_activity
            if composite_key in self.active_sessions:
                if (
                    not ownership.blocks_reclamation
                    and stuck_threshold is not None
                    and idle_for >= stuck_threshold
                ):
                    expired.append((composite_key, idle_for))
                continue
            evict_after = self._idle_eviction_after(client, idle_timeout)
            if not ownership.blocks_reclamation and evict_after is not None and idle_for >= evict_after:
                expired.append((composite_key, idle_for))

        evicted = 0
        for composite_key, idle_for in expired:
            lock = self._claude_runtime_generation_lock(composite_key)
            async with lock:
                client = self.claude_sessions.get(composite_key)
                if client is None:
                    self.session_last_activity.pop(composite_key, None)
                    self.session_turn_started.pop(composite_key, None)
                    self.active_sessions.discard(composite_key)
                    continue
                target = self._claude_runtime_ownership_targets(
                    ((composite_key, client),)
                ).get(composite_key)
                snapshot = getattr(provider, "snapshot", None)
                if target is None or not callable(snapshot):
                    continue
                registry = self._runtime_activation_registry()
                reservation = None
                if registry is not None:
                    identity = self._claude_runtime_activation_identity(client)
                    if identity is None:
                        identity = self._attach_claude_runtime_activation(
                            client,
                            composite_key,
                        )
                    if identity is None:
                        continue
                    reservation = registry.reserve_retirement(identity)
                    if reservation is None:
                        continue
                retired = False
                final: dict[str, Any] = {}
                try:
                    ownership = await asyncio.to_thread(snapshot, target)
                    from core.runtime_ownership import wake_runtime_ownership

                    wake_runtime_ownership(self.controller, ownership)
                    current_last_activity = self.session_last_activity.get(
                        composite_key
                    )
                    if (
                        self.claude_sessions.get(composite_key) is client
                        and current_last_activity is not None
                    ):
                        recheck_idle = time.monotonic() - current_last_activity
                        final["idle_for"] = recheck_idle
                        is_active = composite_key in self.active_sessions
                        final["active"] = is_active
                        if is_active:
                            allowed = bool(
                                stuck_threshold is not None
                                and recheck_idle >= stuck_threshold
                                and not ownership.blocks_reclamation
                            )
                        else:
                            evict_after = self._idle_eviction_after(client, idle_timeout)
                            allowed = bool(
                                not ownership.blocks_reclamation
                                and evict_after is not None
                                and recheck_idle >= evict_after
                            )
                    else:
                        allowed = False
                    if reservation is None:
                        retired = allowed
                    else:
                        retired = bool(
                            registry.finish_retirement(
                                reservation,
                                retire=allowed,
                            )
                            and allowed
                        )
                        reservation = None
                finally:
                    if reservation is not None:
                        registry.finish_retirement(reservation, retire=False)
                if not retired:
                    continue
                setattr(client, "_vibe_runtime_activation_retired", True)
                recheck_idle = float(final.get("idle_for", idle_for))
                if final.get("active"):
                    logger.warning(
                        "Force-evicting stuck-active Claude session %s after %.1fs idle "
                        "(>= stuck-active threshold %.1fs; multiplier=%s idle_timeout=%ss); "
                        "receiver never released the active flag",
                        composite_key,
                        recheck_idle,
                        stuck_threshold,
                        stuck_active_multiplier,
                        idle_timeout,
                    )
                    agent_service = getattr(self.controller, "agent_service", None)
                    claude_agent = (
                        getattr(agent_service, "agents", {}).get("claude")
                        if agent_service
                        else None
                    )
                    force_cleanup = getattr(
                        claude_agent,
                        "force_cleanup_stuck_active_session",
                        None,
                    )
                    if callable(force_cleanup):
                        await force_cleanup(
                            composite_key,
                            runtime_lock_held=True,
                        )
                    else:
                        await self._cleanup_session_locked(
                            composite_key,
                            activation_retired=True,
                            reason="stuck_active_eviction",
                        )
                else:
                    logger.info(
                        "Evicting idle Claude session %s after %.1fs idle",
                        composite_key,
                        recheck_idle,
                    )
                    await self._cleanup_session_locked(
                        composite_key,
                        activation_retired=True,
                        reason="idle_eviction",
                    )
                evicted += 1

        return evicted

    async def reap_orphaned_claude_sessions(self) -> int:
        """Reap leaked ``claude`` subprocesses not owned by any tracked session.

        Defense-in-depth backstop for the idle-eviction path: even if a session
        slips out of tracking (or a previous service instance left a child
        reparented to init), the resident ``claude`` subprocess is reconciled
        against the set of currently-tracked sessions and terminated when it has
        no owner. See ``reap_orphaned_claude_processes`` for the safety guards.
        """
        owned_pids: set[int] = set()
        tracked_resume_ids: dict[str, int] = {}
        owner_set_complete = True
        for client in list(self.claude_sessions.values()):
            pid = get_claude_client_pid(client)
            if not pid:
                # A tracked client whose pid we cannot resolve means the owner
                # set is incomplete: its live process would look ownerless to
                # the in-tree sweep. Disable that sweep this round.
                owner_set_complete = False
                continue
            owned_pids.add(pid)
            native_session_id = getattr(client, "_vibe_native_session_id", None)
            if native_session_id:
                tracked_resume_ids[str(native_session_id)] = pid
        # A session create in flight has spawned a subprocess (connect()) that is
        # not yet in claude_sessions; the in-tree sweep must not touch it.
        creates_in_flight = bool(self.claude_session_creates)
        exclude_pids: set[int] = set()
        watch_service = getattr(self.controller, "watch_service", None)
        active_watch_pids = getattr(watch_service, "active_process_pids", None)
        if callable(active_watch_pids):
            exclude_pids.update(active_watch_pids())
        auth_service = getattr(self.controller, "agent_auth_service", None)
        active_auth_pids = getattr(auth_service, "active_claude_auth_client_pids", None)
        if callable(active_auth_pids):
            exclude_pids.update(active_auth_pids())
        auth_pid_unknown = getattr(auth_service, "has_active_claude_auth_client_with_unknown_pid", None)
        auth_client_pid_unknown = bool(auth_pid_unknown()) if callable(auth_pid_unknown) else False
        # Let unexpected errors surface to the caller (``periodic_cleanup``
        # logs them at error level); ``reap_orphaned_claude_processes`` already
        # absorbs the expected ``ps``-read failure internally.
        return await reap_orphaned_claude_processes(
            owned_pids=owned_pids,
            tracked_resume_ids=tracked_resume_ids,
            cli_path=self._get_claude_cli_path_override(),
            logger=logger,
            reap_in_tree=owner_set_complete and not creates_in_flight and not auth_client_pid_unknown,
            exclude_pids=exclude_pids,
        )

    async def handle_session_error(
        self,
        composite_key: str,
        context: MessageContext,
        error: Exception,
        *,
        client=None,
    ) -> bool:
        """Handle session-related errors.

        Returns ``True`` when the failure was contained (already explained to
        the user, or deliberately silenced), so callers can skip persisting a
        durable failure notification for it.

        ``client`` is the exact client whose failure the caller observed. It
        matters when a replacement has already registered under the same
        composite key: the torn-down client was popped from ``claude_sessions``
        and only it carries the teardown marker, so re-reading the map here
        would classify a delayed old-generation ``-9`` against the healthy
        replacement and report it as a genuine failure.
        """
        error_msg = str(error)

        # Check for specific error types
        if isinstance(error, ClaudeInputNotSentError):
            # This input never reached Claude. Keep existing background work,
            # persisted mappings and any replacement client intact.
            await self._get_im_client(context).send_message(
                context,
                self._get_formatter(context).format_error(self._t(error.message_key)),
            )
            return False
        if isinstance(error, ClaudeSessionNotFoundError):
            logger.warning(
                "Claude session %s not found for current working directory %s; keeping persisted mapping unchanged",
                error.session_id,
                error.working_path,
            )
            await self._get_im_client(context).send_message(
                context,
                self._get_formatter(context).format_error(
                    self._t(
                        "error.claudeSessionNotFound",
                        sessionId=error.session_id,
                        path=error.working_path,
                    )
                ),
            )
            return False
        from modules.agents.model_hub import launch_refusal_copy

        refusal = launch_refusal_copy(self.controller, error)
        if refusal is not None:
            # The Hub refused this launch before any Claude process existed.
            await self._get_im_client(context).send_message(
                context,
                self._get_formatter(context).format_error(refusal),
            )
            return False

        if client is None:
            client = self.claude_sessions.get(composite_key)
        returncode = get_claude_client_returncode(client)
        if self._is_intentional_teardown_signal(composite_key, error, returncode, client):
            # The service killed this process itself (idle eviction, duplicate
            # reap, shutdown). Surfacing it would report a deliberate teardown
            # as an unexplained backend failure.
            logger.warning(
                "Claude session %s ended on a service-initiated teardown signal: %s",
                composite_key,
                error_msg,
            )
            await self.cleanup_session(
                composite_key,
                current_receiver_task=asyncio.current_task(),
                # This failure may belong to a generation a replacement has
                # already taken over from; retire that exact client or nothing.
                expected_client=client,
                reason="intentional_teardown_signal",
            )
            return True
        if returncode is not None:
            reason_key, reason_values = claude_process_exit_reason_i18n(returncode)
            reason = self._t(reason_key, **reason_values)
            diagnostic = self.claude_error_diagnostic(
                composite_key,
                error,
                client=client,
            )
            logger.error(
                "Claude process for session %s terminated (%s): %s",
                composite_key,
                reason,
                diagnostic,
            )
            # Same generation guard as the contained branch above: this branch is
            # reached off the CALLER's client, which a replacement may already
            # have superseded. Reporting a stale crash is right; retiring the
            # live client that replaced it is not.
            await self.cleanup_session(
                composite_key,
                current_receiver_task=asyncio.current_task(),
                expected_client=client,
                reason="process_terminated",
            )
            message = self._t("error.claudeProcessTerminated", reason=reason)
            resource_failure = getattr(client, "_vibe_resource_failure", None)
            if resource_failure is not None:
                if resource_failure.kind == "pids":
                    language = str(getattr(self.controller.config, "language", "en") or "en")
                    message = (
                        f"{message} "
                        f"{self._t('error.agentPidsLimit', **pids_failure_labels(resource_failure, language))}"
                    )
                elif resource_failure.kind == "memory":
                    message = f"{message} {self._t('error.agentMemoryLimit')}"
            await self._get_im_client(context).send_message(
                context,
                self._get_formatter(context).format_error(message),
            )
            return False
        if "read() called while another coroutine" in error_msg:
            logger.error(f"Session {composite_key} has concurrent read error - cleaning up")
            await self.cleanup_session(
                composite_key,
                current_receiver_task=asyncio.current_task(),
                reason="concurrent_read",
            )

            # Notify user and suggest retry
            await self._get_im_client(context).send_message(
                context,
                self._get_formatter(context).format_error(self._t("error.sessionReset")),
            )
        elif (
            "Session is broken" in error_msg
            or "Connection closed" in error_msg
            or "Connection lost" in error_msg
            # Claude Agent SDK raises this when one stdio JSON message exceeds
            # its line buffer; keep the match scoped to that transport fatal.
            or is_claude_sdk_buffer_error(error)
        ):
            logger.error(f"Session {composite_key} is broken - cleaning up")
            await self.cleanup_session(
                composite_key,
                current_receiver_task=asyncio.current_task(),
                reason="connection_broken",
            )

            # Notify user
            await self._get_im_client(context).send_message(
                context,
                self._get_formatter(context).format_error(self._t("error.sessionConnectionLost")),
            )
        else:
            # Generic error handling
            logger.error(f"Error in session {composite_key}: {error}")
            await self._get_im_client(context).send_message(
                context,
                self._get_formatter(context).format_error(self._t("error.sessionGeneric", error=error_msg)),
            )
        return False

    def claude_error_diagnostic(
        self,
        composite_key: str,
        error: Exception,
        *,
        client=None,
    ) -> str:
        """Add process state and captured stderr to a Claude failure diagnostic."""
        diagnostic = str(error)
        # Callers that observe a concrete failed generation pass it through so a
        # replacement registered under the same composite key cannot steal the
        # diagnosis. The optional fallback preserves older direct callers.
        if client is None:
            client = self.claude_sessions.get(composite_key)
        returncode = get_claude_client_returncode(client)
        if returncode is not None:
            diagnostic = f"{diagnostic}\nClaude process terminated: {claude_process_exit_reason(returncode)}"
            resource_failure = getattr(client, "_vibe_resource_failure", None)
            if not getattr(client, "_vibe_resource_failure_checked", False):
                if resource_failure is None and not self.claude_teardown_is_intentional(
                    composite_key, error, client=client
                ):
                    resource_failure = observe_agent_resource_pressure(self.controller)
                    if resource_failure is not None:
                        setattr(client, "_vibe_resource_failure", resource_failure)
                setattr(client, "_vibe_resource_failure_checked", True)
            if resource_failure is not None:
                diagnostic = f"{diagnostic}\nResource diagnosis: {resource_failure.message}"
        # Last, so auth classification can leave the CLI's stderr out.
        return f"{diagnostic}{claude_stderr_tail_section(client)}"

    def capture_session_id(
        self,
        base_session_id: str,
        claude_session_id: str,
        session_key: str,
        *,
        working_path: Optional[str] = None,
    ):
        """Capture and store Claude session ID mapping"""
        agent_session_id = self.bind_agent_session_id(
            session_key=session_key,
            agent_name="claude",
            session_anchor=base_session_id,
            native_session_id=claude_session_id,
            working_path=working_path,
        )
        logger.info(f"Captured Claude session_id: {claude_session_id} for {base_session_id}")
        composite_key = f"{base_session_id}:{working_path}" if working_path else None
        if composite_key:
            client = self.claude_sessions.get(composite_key)
            if client is not None:
                setattr(client, "_vibe_native_session_id", claude_session_id)
                setattr(client, "_vibe_agent_session_id", str(agent_session_id or ""))
        return agent_session_id

    def ensure_agent_session_id(
        self,
        context: MessageContext,
        *,
        session_key: str,
        agent_name: str,
        session_anchor: str,
        working_path: Optional[str] = None,
        vibe_agent_id: Optional[str] = None,
        vibe_agent_name: Optional[str] = None,
    ) -> Optional[str]:
        # avibe: pin the reserved workbench row id before any hidden-row creation
        # (mirrors BaseAgent.ensure_agent_session_id) so a pre-bind setup/query
        # failure persists the terminal notify under the OPEN Chat session rather
        # than a freshly-minted hidden row the page never sees (Codex P2).
        target = resolve_context_agent_session_target(context)
        if target and target.get("id"):
            reserved_id = str(target["id"]).strip()
            if reserved_id:
                payload = dict(context.platform_specific or {})
                payload["agent_session_id"] = reserved_id
                context.platform_specific = payload
                return reserved_id
        ensure = getattr(self.sessions, "ensure_agent_session_id", None)
        if callable(ensure):
            ensure_kwargs: dict[str, Any] = {}
            if working_path is not None:
                ensure_kwargs["workdir"] = working_path
            if vibe_agent_id is not None:
                ensure_kwargs["vibe_agent_id"] = vibe_agent_id
            if vibe_agent_name is not None:
                ensure_kwargs["vibe_agent_name"] = vibe_agent_name
            agent_session_id = ensure(
                session_key,
                agent_name,
                session_anchor,
                **ensure_kwargs,
            )
        else:
            getter = getattr(self.sessions, "get_agent_session_row_id", None)
            agent_session_id = getter(session_key, session_anchor, agent_name) if callable(getter) else None
        if not agent_session_id:
            return None
        payload = dict(context.platform_specific or {})
        payload["agent_session_id"] = agent_session_id
        context.platform_specific = payload
        return agent_session_id

    def bind_agent_session_id(
        self,
        *,
        session_key: str,
        agent_name: str,
        session_anchor: str,
        native_session_id: str,
        working_path: Optional[str] = None,
    ) -> Optional[str]:
        binder = getattr(self.sessions, "bind_agent_session", None)
        if callable(binder):
            return binder(
                session_key,
                agent_name,
                session_anchor,
                native_session_id,
                workdir=working_path,
            )
        self.sessions.set_agent_session_mapping(session_key, agent_name, session_anchor, native_session_id)
        getter = getattr(self.sessions, "get_agent_session_row_id", None)
        return getter(session_key, session_anchor, agent_name) if callable(getter) else None

    def attach_agent_session_id(
        self,
        context: MessageContext,
        *,
        session_key: str,
        agent_name: str,
        session_anchor: str,
    ) -> Optional[str]:
        return self.ensure_agent_session_id(
            context,
            session_key=session_key,
            agent_name=agent_name,
            session_anchor=session_anchor,
        )

    def restore_session_mappings(self):
        """Restore session mappings from settings on startup"""
        logger.info("Initializing session mappings from saved settings...")

        session_state = self.sessions.get_all_session_mappings()

        restored_count = 0
        for user_id, agent_map in session_state.items():
            claude_map = agent_map.get("claude", {}) if isinstance(agent_map, dict) else {}
            for thread_id, claude_session_id in claude_map.items():
                if isinstance(claude_session_id, str):
                    logger.info(f"  - {thread_id} -> {claude_session_id} (user {user_id})")
                    restored_count += 1

        logger.info(f"Session restoration complete. Restored {restored_count} session mappings.")