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.

77.4 KB
Raw Blame
from __future__ import annotations

import asyncio
import sys
import unittest
from pathlib import Path
from unittest import mock

sys.path.insert(0, str(Path(__file__).resolve().parents[1]))

from core.message_dispatcher import ConsolidatedMessageDispatcher
from core.delivery_evidence import DeliveryEvidence
from core.message_output import (
    MessageOutput,
    contained_teardown_output_for,
    stop_output_for,
)
from core.run_settlement import (
    NON_COMPLETING_TURN_SETTLEMENTS,
    SETTLED_BY_BACKEND_REFRESH,
    SETTLED_BY_STOPPED,
    SETTLED_BY_TERMINAL_RESULT,
    SETTLED_BY_TURN_ONLY_RESULT,
    SETTLEMENT_TERMINAL_STATUS,
    SETTLEMENTS_WITHOUT_RESULT,
)
from core.session_turns import SessionTurnManager
from modules.im import MessageContext
from storage.agent_activity_service import _outcome_status


class _StubSettingsManager:
    def _canonicalize_message_type(self, message_type):
        return message_type

    def is_message_type_hidden(self, settings_key, canonical_type):
        return False


class _StubSessionHandler:
    def __init__(self):
        self.calls = []

    def finalize_scheduled_delivery(self, context, sent_message_id):
        self.calls.append((context.channel_id, context.thread_id, sent_message_id))


class _StubIMClient:
    def __init__(self, *, fail_first_send: bool = False, upload_id: str = "file-1"):
        self.sent_messages = []
        self.uploaded_markdowns = []
        self._next_id = 1
        self._fail_first_send = fail_first_send
        self._send_attempts = 0
        self._upload_id = upload_id

    def should_use_thread_for_reply(self):
        return False

    async def send_message(self, context, text, parse_mode=None, reply_to=None):
        self._send_attempts += 1
        if self._fail_first_send and self._send_attempts == 1:
            raise RuntimeError("inline send failed")
        self.sent_messages.append((context.channel_id, text, parse_mode))
        message_id = f"msg-{self._next_id}"
        self._next_id += 1
        return message_id

    async def upload_markdown(self, context, title, content, filetype="markdown"):
        self.uploaded_markdowns.append((context.channel_id, title, content, filetype))
        return self._upload_id


class _DropClient(_StubIMClient):
    async def send_message(self, context, text, parse_mode=None, reply_to=None):
        self.sent_messages.append((context.channel_id, text, parse_mode))
        return None

    async def send_message_with_buttons(self, context, text, keyboard, parse_mode=None):
        self.sent_messages.append((context.channel_id, text, parse_mode))
        return None

    async def upload_markdown(self, context, title, content, filetype="markdown"):
        self.uploaded_markdowns.append((context.channel_id, title, content, filetype))
        return None


class _NativeMarkdownIMClient(_StubIMClient):
    def __init__(self):
        super().__init__()
        self.native_markdown_messages = []

    async def send_markdown_message(self, context, text, keyboard=None, reply_to=None):
        self.native_markdown_messages.append((context.channel_id, text, keyboard, reply_to))
        message_id = f"native-{self._next_id}"
        self._next_id += 1
        return message_id


class _SubtextNativeMarkdownIMClient(_StubIMClient):
    """Native-markdown client that accepts (and records) the ``subtext`` footer,
    modelling a ``supports_status_bubble`` platform (Slack/Discord/Lark)."""

    def __init__(self):
        super().__init__()
        self.native_markdown_messages = []

    async def send_markdown_message(self, context, text, keyboard=None, reply_to=None, subtext=None):
        self.native_markdown_messages.append((context.channel_id, text, keyboard, reply_to, subtext))
        message_id = f"native-{self._next_id}"
        self._next_id += 1
        return message_id


class _StubController:
    def __init__(
        self,
        *,
        platform: str = "lark",
        language: str = "en",
        fail_first_send: bool = False,
        upload_id: str = "file-1",
        im_client=None,
        reply_enhancements: bool = False,
    ):
        self.config = type(
            "Config",
            (),
            {"platform": platform, "language": language, "reply_enhancements": reply_enhancements},
        )()
        self.session_handler = _StubSessionHandler()
        self.im_client = im_client or _StubIMClient(fail_first_send=fail_first_send, upload_id=upload_id)
        self.agent_service = None

    def _get_settings_key(self, context):
        return context.channel_id

    def _get_session_key(self, context):
        return f"{context.platform}::{context.channel_id}"

    def get_settings_manager_for_context(self, context):
        return _StubSettingsManager()

    def get_im_client_for_context(self, context):
        return self.im_client


class MessageDispatcherResultFallbackTests(unittest.IsolatedAsyncioTestCase):
    def test_terminal_snapshot_elects_fallback_after_excluding_canceled_runs(self):
        controller = _StubController(platform="slack")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={
                "turn_token": "turn-fallback",
                "accepted_agent_run_ids": ["run-a", "run-b"],
            },
        )
        output = MessageOutput(
            completes_turn=True,
            completes_run=True,
            metadata={
                "turn_failure_notification": {
                    "failure_id": "turn:turn-fallback",
                    "delivered": False,
                }
            },
        )
        store = mock.Mock()
        store.get_run.side_effect = lambda run_id: {
            "run-a": {"id": "run-a", "status": "canceled"},
            "run-b": {"id": "run-b", "status": "running"},
        }.get(run_id)

        with mock.patch(
            "core.message_dispatcher.SQLiteBackgroundTaskStore",
            return_value=store,
        ):
            enriched = dispatcher._output_with_turn_fallback_owner(context, output)

        self.assertEqual(
            enriched.metadata["turn_failure_notification"]["fallback_run_id"],
            "run-b",
        )
        store.close.assert_called_once_with()

    def test_terminal_recording_delegates_owner_election_to_the_atomic_store_batch(self):
        dispatcher = ConsolidatedMessageDispatcher(_StubController(platform="slack"))
        store = mock.Mock()
        store.get_run.side_effect = AssertionError(
            "the dispatcher must not snapshot participant state outside the batch"
        )
        output = MessageOutput(
            completes_turn=True,
            completes_run=True,
            idempotency_key="terminal-output",
            metadata={
                "turn_failure_notification": {
                    "failure_id": "turn:turn-fallback",
                    "delivered": False,
                    "fallback_run_id": "run-a",
                }
            },
        )

        dispatcher._record_agent_run_terminal_for_ids(
            store=store,
            run_ids=["run-a", "run-b"],
            text="",
            message_id=None,
            terminal_status="failed",
            terminal_error="stream disconnected",
            output_semantics=output,
            provenance=dict(output.metadata),
            blocked_run_ids=frozenset(),
        )

        store.record_turn_run_outputs.assert_called_once_with(
            ["run-a", "run-b"],
            output_id="terminal-output",
            text="",
            message_id=None,
            sequence=None,
            provenance=output.metadata,
            terminal_status="failed",
            error="stream disconnected",
            deferred_run_ids=[],
        )
        store.get_run.assert_not_called()

    async def test_hfr_472_empty_failed_turn_creates_one_shared_fallback_contract(self):
        """HFR-472: empty failed Turn owns one fallback across all accepted Runs."""

        controller = self._terminal_lifecycle_controller()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._collapse_status_bubble = mock.AsyncMock()
        dispatcher._clear_consolidated_state = mock.AsyncMock()
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={
                "agent_runtime_turn_key": "runtime-1",
                "agent_runtime_turn_token": "runtime-turn-1",
                "turn_token": "turn-empty-failure",
                "accepted_agent_run_ids": ["run-b", "run-a"],
            },
        )
        store = mock.Mock()
        store.get_run.side_effect = lambda run_id: {
            "run-a": {"id": "run-a", "status": "running"},
            "run-b": {"id": "run-b", "status": "running"},
        }.get(run_id)

        with mock.patch(
            "core.message_dispatcher.SQLiteBackgroundTaskStore",
            return_value=store,
        ):
            await dispatcher.emit_agent_message(
                context,
                "result",
                "",
                is_error=True,
                output=MessageOutput(completes_turn=True, completes_run=True),
            )

        evidence = controller.session_turns.on_terminal_result.call_args.kwargs[
            "terminal_evidence"
        ]
        notification = evidence["output_provenance"]["turn_failure_notification"]
        self.assertEqual(
            notification,
            {
                "failure_id": "turn:turn-empty-failure",
                "delivered": False,
                "fallback_run_id": "run-a",
            },
        )
        store.record_turn_run_outputs.assert_called_once()
        record_call = store.record_turn_run_outputs.call_args
        self.assertEqual(record_call.args[0], ["run-b", "run-a"])
        self.assertEqual(
            record_call.kwargs["provenance"]["turn_failure_notification"],
            notification,
        )
        self.assertEqual(controller.im_client.sent_messages, [])

    async def test_hfr_472_contract_is_snapshotted_before_the_first_run_arrives(self):
        controller = self._terminal_lifecycle_controller()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._collapse_status_bubble = mock.AsyncMock()
        dispatcher._clear_consolidated_state = mock.AsyncMock()
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={
                "agent_runtime_turn_key": "runtime-1",
                "agent_runtime_turn_token": "runtime-turn-1",
                "turn_token": "turn-before-run",
            },
        )

        await dispatcher.emit_agent_message(
            context,
            "result",
            "",
            is_error=True,
            output=MessageOutput(completes_turn=True, completes_run=True),
        )

        evidence = controller.session_turns.on_terminal_result.call_args.kwargs[
            "terminal_evidence"
        ]
        self.assertEqual(
            evidence["output_provenance"]["turn_failure_notification"],
            {
                "failure_id": "turn:turn-before-run",
                "delivered": False,
            },
        )

    def test_visible_direct_error_does_not_create_a_turn_fallback_contract(self):
        dispatcher = ConsolidatedMessageDispatcher(_StubController(platform="slack"))
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={
                "turn_token": "turn-visible-error",
                "accepted_agent_run_ids": ["run-a", "run-b"],
            },
        )
        output = MessageOutput(completes_turn=True, completes_run=True)

        unchanged = dispatcher._output_with_implicit_turn_failure_notification(
            context,
            output,
            is_error=True,
            has_visible_result=True,
            mutates_turn_lifecycle=True,
        )

        self.assertIs(unchanged, output)
        self.assertNotIn("turn_failure_notification", unchanged.metadata)

    async def test_detached_stale_result_delivers_without_mutating_newer_turn(self):
        controller = _StubController(platform="slack")
        controller.agent_service = type(
            "Service",
            (),
            {
                "emit_matches_runtime_turn": lambda self, context: False,
                "release_runtime_turn": mock.Mock(),
            },
        )()
        controller.session_turns = type(
            "Turns",
            (),
            {"on_terminal_result": mock.Mock()},
        )()
        controller.mark_turn_complete = mock.Mock()
        turn_chunk = mock.AsyncMock()
        controller.get_turn_sink = lambda key: {
            "on_chunk": turn_chunk,
            "done_event": asyncio.Event(),
            "turn_token": "newer-turn",
        }
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={
                "agent_runtime_turn_key": "runtime-1",
                "agent_runtime_turn_token": "old-turn",
                "turn_token": "old-turn",
            },
        )

        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            message_id = await dispatcher.emit_agent_message(
                context,
                "result",
                "late background result",
                output=MessageOutput(
                    completes_turn=False,
                    detached=True,
                    idempotency_key="task-1:completion",
                    activity_id="task-1",
                    sequence=1,
                ),
            )

        self.assertEqual(message_id, "msg-1")
        self.assertEqual(controller.im_client.sent_messages[0][1], "late background result")
        controller.session_turns.on_terminal_result.assert_not_called()
        controller.mark_turn_complete.assert_not_called()
        controller.agent_service.release_runtime_turn.assert_not_called()
        turn_chunk.assert_not_awaited()
        persist.assert_called_once()
        self.assertEqual(persist.call_args.args[1], "result")
        self.assertEqual(persist.call_args.kwargs["metadata"]["activity_id"], "task-1")
        self.assertTrue(persist.call_args.kwargs["metadata"]["detached"])

    async def test_one_turn_can_emit_multiple_outputs_and_complete_once(self):
        controller = _StubController(platform="slack")
        controller.agent_service = type(
            "Service",
            (),
            {
                "emit_matches_runtime_turn": lambda self, context: True,
                "release_runtime_turn": mock.Mock(),
            },
        )()
        controller.session_turns = type(
            "Turns",
            (),
            {"on_terminal_result": mock.Mock()},
        )()
        done = asyncio.Event()
        controller.get_turn_sink = lambda key: {
            "on_chunk": mock.AsyncMock(),
            "done_event": done,
            "turn_token": "turn-1",
        }
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={
                "agent_runtime_turn_key": "runtime-1",
                "agent_runtime_turn_token": "runtime-turn-1",
                "turn_token": "turn-1",
            },
        )

        await dispatcher.emit_agent_message(
            context,
            "result",
            "first output",
            output=MessageOutput(
                completes_turn=False,
                idempotency_key="output-1",
                sequence=1,
            ),
        )
        self.assertFalse(done.is_set())
        controller.session_turns.on_terminal_result.assert_not_called()
        controller.agent_service.release_runtime_turn.assert_not_called()

        await dispatcher.emit_agent_message(
            context,
            "result",
            "final output",
            output=MessageOutput(
                completes_turn=True,
                idempotency_key="output-2",
                sequence=2,
            ),
        )

        self.assertTrue(done.is_set())
        self.assertEqual(
            [item[1] for item in controller.im_client.sent_messages],
            ["first output", "final output"],
        )
        controller.session_turns.on_terminal_result.assert_called_once_with(
            context,
            is_error=False,
            settled_by=SETTLED_BY_TERMINAL_RESULT,
            terminal_evidence={
                "result_text": "final output",
                "terminal_error": None,
                "settles_run": True,
                "output_provenance": {
                    "turn_id": "turn-1",
                    "sequence": 2,
                    "output_id": "output-2",
                    "detached": False,
                },
            },
        )
        controller.agent_service.release_runtime_turn.assert_called_once_with(context)

    async def test_duplicate_terminal_output_still_settles_lifecycle(self):
        controller = _StubController(platform="slack")
        controller.agent_service = type(
            "Service",
            (),
            {
                "emit_matches_runtime_turn": lambda self, context: True,
                "release_runtime_turn": mock.Mock(),
            },
        )()
        controller.session_turns = type(
            "Turns",
            (),
            {"on_terminal_result": mock.Mock()},
        )()
        controller.mark_turn_complete = mock.Mock()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._collapse_status_bubble = mock.AsyncMock()
        dispatcher._clear_consolidated_state = mock.AsyncMock()
        dispatcher._record_agent_run_terminal_result = mock.AsyncMock()
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={
                "agent_runtime_turn_key": "runtime-1",
                "agent_runtime_turn_token": "runtime-turn-1",
                "turn_token": "turn-1",
            },
        )
        output = MessageOutput(
            completes_turn=True,
            completes_run=True,
            idempotency_key="terminal-output",
        )

        with mock.patch(
            "core.message_dispatcher.agent_message_exists",
            return_value=True,
        ):
            message_id = await dispatcher.emit_agent_message(
                context,
                "result",
                "already delivered",
                output=output,
            )

        self.assertEqual(
            message_id,
            "agent-output:unknown:runtime-1:terminal-output",
        )
        self.assertEqual(controller.im_client.sent_messages, [])
        controller.session_turns.on_terminal_result.assert_called_once_with(
            context,
            is_error=False,
            settled_by=SETTLED_BY_TERMINAL_RESULT,
            terminal_evidence={
                "result_text": "already delivered",
                "terminal_error": None,
                "settles_run": True,
                "output_provenance": {
                    "turn_id": "turn-1",
                    "output_id": "terminal-output",
                    "detached": False,
                },
            },
        )
        dispatcher._record_agent_run_terminal_result.assert_called_once_with(
            context,
            "already delivered",
            None,
            is_error=False,
            terminal_error=None,
            output_semantics=output,
        )
        dispatcher._collapse_status_bubble.assert_awaited_once()
        dispatcher._clear_consolidated_state.assert_awaited_once_with(context)
        controller.mark_turn_complete.assert_called_once_with(
            context,
            settled_by=SETTLED_BY_TERMINAL_RESULT,
        )
        controller.agent_service.release_runtime_turn.assert_called_once_with(context)

    def _terminal_lifecycle_controller(self):
        controller = _StubController(platform="slack")
        controller.agent_service = type(
            "Service",
            (),
            {
                "emit_matches_runtime_turn": lambda self, context: True,
                "release_runtime_turn": mock.Mock(),
            },
        )()
        controller.session_turns = type(
            "Turns",
            (),
            {"on_terminal_result": mock.Mock()},
        )()
        controller.mark_turn_complete = mock.Mock()
        return controller

    async def _emit_silent_terminal(
        self, controller, *, completes_run: bool, output=None, close_after: bool = False
    ):
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._collapse_status_bubble = mock.AsyncMock()
        dispatcher._clear_consolidated_state = mock.AsyncMock()
        dispatcher._record_agent_run_terminal_result = mock.AsyncMock()
        platform_specific = {
            "agent_runtime_turn_key": "runtime-1",
            "agent_runtime_turn_token": "runtime-turn-1",
            "turn_token": "turn-1",
        }
        if close_after:
            platform_specific.update({
                "close_after": True,
                "agent_session_id": "session-1",
                "agent_backend": "claude",
                "agent_session_target": {
                    "agent_backend": "claude",
                    "session_anchor": "base-session-1",
                },
            })
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific=platform_specific,
        )
        await dispatcher.emit_agent_message(
            context,
            "result",
            "",
            level="silent",
            output=output
            or MessageOutput(completes_turn=True, completes_run=completes_run),
        )
        return dispatcher, context

    async def test_turn_only_terminal_release_does_not_claim_the_run(self):
        """HFR-030: a terminal result that completes the turn but NOT the run stamps
        ``turn_only_result``, so no settlement lane may terminalize the row.

        This is the Claude Activity delivery-failure emit: the origin turn is closed
        while the REQUEUED Activity keeps the run and retries. Stamping the
        no-dispatch default here failed an Activity-owned run — and fired its
        callback — before the retry ever ran.
        """
        controller = self._terminal_lifecycle_controller()

        with mock.patch(
            "core.services.running_agents.end_running_agent",
            new_callable=mock.AsyncMock,
        ) as end_running_agent:
            dispatcher, context = await self._emit_silent_terminal(
                controller, completes_run=False, close_after=True
            )
            await asyncio.sleep(0.01)
            end_running_agent.assert_not_awaited()

        controller.mark_turn_complete.assert_called_once_with(
            context,
            settled_by=SETTLED_BY_TURN_ONLY_RESULT,
        )
        # The run's terminal state was never written here either — same owner rule.
        dispatcher._record_agent_run_terminal_result.assert_not_called()
        self.assertNotIn(SETTLED_BY_TURN_ONLY_RESULT, SETTLEMENTS_WITHOUT_RESULT)

    async def test_run_settling_terminal_release_stamps_terminal_result(self):
        """HFR-030 (other half): when the same emit DOES own the run, the stamp is
        the honest ``terminal_result`` — otherwise a durable caller would re-settle a
        run its backend already completed."""
        controller = self._terminal_lifecycle_controller()

        dispatcher, context = await self._emit_silent_terminal(controller, completes_run=True)

        controller.mark_turn_complete.assert_called_once_with(
            context,
            settled_by=SETTLED_BY_TERMINAL_RESULT,
        )
        dispatcher._record_agent_run_terminal_result.assert_called_once()

    async def test_silent_im_terminal_records_non_message_turn_evidence(self):
        controller = self._terminal_lifecycle_controller()

        with mock.patch("core.message_dispatcher.persist_silent_terminal") as persist:
            _dispatcher, context = await self._emit_silent_terminal(
                controller,
                completes_run=False,
            )

        persist.assert_called_once_with(
            context,
            is_error=False,
            settled_by=SETTLED_BY_TURN_ONLY_RESULT,
        )

    async def test_stop_output_release_names_the_stop_and_records_no_run_terminal(self):
        """HFR-036: the synthetic result a user stop emits must NOT record the run.

        Every backend answers an acknowledged stop with an empty silent ``result``.
        Sent with the terminal-turn default it recorded that empty body as the run's
        ``succeeded`` terminal — and because that write lands before the stop's own
        guarded write, first-writer-wins reported a user-ended run as a success. The
        stop output must therefore claim no run terminal AND still name ``stopped``,
        so the settlement lanes reach the writer that maps it to ``canceled``.
        Deriving the reason from ``settles_run`` alone would say ``turn_only_result``,
        which no lane may settle, and the row would be left ``running``.
        """
        controller = self._terminal_lifecycle_controller()
        controller.agent_service.reserve_idle_close_after_teardown = mock.AsyncMock(
            return_value=("runtime-1", "close-after:test", None)
        )
        controller.agent_service.release_runtime_turn_key = mock.Mock()

        with mock.patch("core.message_dispatcher.persist_silent_terminal") as persist, mock.patch(
            "core.services.running_agents.end_running_agent",
            new_callable=mock.AsyncMock,
            return_value={"ok": True},
        ) as end_running_agent:
            dispatcher, context = await self._emit_silent_terminal(
                controller,
                completes_run=False,
                output=stop_output_for(None),
                close_after=True,
            )
            await asyncio.sleep(0.01)

        controller.mark_turn_complete.assert_called_once_with(
            context,
            settled_by=SETTLED_BY_STOPPED,
        )
        end_running_agent.assert_awaited_once()
        # A settlement the lanes MAY act on — unlike ``turn_only_result``.
        self.assertIn(SETTLED_BY_STOPPED, SETTLEMENTS_WITHOUT_RESULT)
        self.assertEqual(SETTLEMENT_TERMINAL_STATUS[SETTLED_BY_STOPPED], "canceled")
        dispatcher._record_agent_run_terminal_result.assert_not_called()
        persist.assert_not_called()

    async def test_contained_teardown_release_names_backend_refresh_and_records_no_run_terminal(
        self,
    ):
        """#1204: a teardown the service performed itself is an infrastructure
        interruption, not a backend result.

        #1202 stopped these from being SHOWN as backend errors; the emit that
        followed still terminalized an ``agent_runs`` row from an empty body. Same
        fix shape as the stop above: name the settlement so the lanes reach the
        writer that maps ``backend_refresh`` to ``failed`` with a structured cause
        (invariant 2 of ``docs/plans/harness-run-reliability.md``), and claim no run
        terminal so the empty body never becomes the result.

        The IM boundary is still written, unlike the stop above — an IM turn has no
        durable execution owner, so this row is the ONLY thing that closes it — but
        it is written with the settlement, so it records ``canceled`` rather than
        asserting a backend fault.
        """
        controller = self._terminal_lifecycle_controller()

        with mock.patch("core.message_dispatcher.persist_silent_terminal") as persist:
            dispatcher, context = await self._emit_silent_terminal(
                controller,
                completes_run=False,
                output=contained_teardown_output_for(None),
            )

        controller.mark_turn_complete.assert_called_once_with(
            context,
            settled_by=SETTLED_BY_BACKEND_REFRESH,
        )
        self.assertIn(SETTLED_BY_BACKEND_REFRESH, SETTLEMENTS_WITHOUT_RESULT)
        # Still terminal, still a failed RUN — the cause is what changed.
        self.assertEqual(SETTLEMENT_TERMINAL_STATUS[SETTLED_BY_BACKEND_REFRESH], "failed")
        # The TURN is canceled, not failed: retired, not broken.
        self.assertEqual(
            NON_COMPLETING_TURN_SETTLEMENTS[SETTLED_BY_BACKEND_REFRESH], "canceled"
        )
        dispatcher._record_agent_run_terminal_result.assert_not_called()
        persist.assert_called_once_with(
            context,
            is_error=False,
            settled_by=SETTLED_BY_BACKEND_REFRESH,
        )

    def test_durable_turn_outcome_never_completes_a_result_less_settlement(self):
        """The Turn-level half of #1204, at the mapper both surfaces share.

        ``_durable_terminal_outcome`` special-cased ``stopped`` only, so a
        ``backend_refresh`` release with no error flag recorded the durable Turn as
        ``completed`` — a retired runtime reported as a finished answer, and a
        straight contradiction of what ``release_for_backend_refresh`` writes for
        the very same event.
        """
        outcome = SessionTurnManager._durable_terminal_outcome

        self.assertEqual(
            outcome(is_error=False, settled_by=SETTLED_BY_BACKEND_REFRESH), "canceled"
        )
        # The settlement outranks the flag: how the turn ended is not a function of
        # whether a result was produced, and both agree it was retired.
        self.assertEqual(
            outcome(is_error=True, settled_by=SETTLED_BY_BACKEND_REFRESH), "canceled"
        )
        self.assertEqual(
            outcome(is_error=False, settled_by=SETTLED_BY_STOPPED), "canceled"
        )
        # Unnamed releases are unchanged — this must not become a blanket override.
        self.assertEqual(outcome(is_error=False, settled_by=None), "completed")
        self.assertEqual(outcome(is_error=True, settled_by=None), "failed")
        self.assertEqual(
            outcome(is_error=False, settled_by=SETTLED_BY_TERMINAL_RESULT), "completed"
        )

    def test_activity_group_status_renders_a_canceled_boundary_as_interrupted(self):
        """The IM trace and the durable Turn must not disagree on one settlement.

        ``list_turn_groups`` already rendered a ``canceled`` durable Turn as
        ``interrupted``; the silent marker that stands in for one on IM was mapped
        with a separate two-way test that could only say ``failed`` or ``done``, so
        the same teardown showed a green ``done`` chip there.
        """
        self.assertEqual(_outcome_status("canceled"), "interrupted")
        self.assertEqual(_outcome_status("not_written"), "interrupted")
        self.assertEqual(_outcome_status("failed"), "failed")
        self.assertEqual(_outcome_status("completed"), "done")
        self.assertEqual(_outcome_status(None), "done")

    async def test_slack_result_uses_native_markdown_sender_when_available(self):
        im_client = _NativeMarkdownIMClient()
        controller = _StubController(platform="slack", im_client=im_client)
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="slack")
        text = "| A | B |\n| - | - |\n| 1 | 2 |"

        message_id = await dispatcher.emit_agent_message(context, "result", text)

        self.assertEqual(message_id, "native-1")
        self.assertEqual(im_client.sent_messages, [])
        self.assertEqual(im_client.native_markdown_messages, [("C1", text, None, None)])

    async def test_slack_result_passes_quick_replies_to_native_markdown_sender(self):
        im_client = _NativeMarkdownIMClient()
        controller = _StubController(platform="slack", im_client=im_client, reply_enhancements=True)
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="slack")

        message_id = await dispatcher.emit_agent_message(
            context,
            "result",
            "Body\n\n---\n[Continue] | [Stop]",
        )

        self.assertEqual(message_id, "native-1")
        self.assertEqual(im_client.sent_messages, [])
        channel_id, text, keyboard, reply_to = im_client.native_markdown_messages[0]
        self.assertEqual(channel_id, "C1")
        self.assertEqual(text, "Body")
        self.assertIsNone(reply_to)
        self.assertEqual([button.text for button in keyboard.buttons[0]], ["Continue", "Stop"])

    async def test_wechat_result_preserves_separator_free_button_like_text(self):
        im_client = _StubIMClient()
        controller = _StubController(
            platform="wechat",
            im_client=im_client,
            reply_enhancements=True,
        )
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="wx1", channel_id="wx1", platform="wechat")

        message_id = await dispatcher.emit_agent_message(
            context,
            "result",
            "Compare:\n[A] | [B]",
        )

        self.assertEqual(message_id, "msg-1")
        self.assertEqual(im_client.sent_messages[0][1], "Compare:\n[A] | [B]")

    async def test_separator_free_parsing_uses_delivery_target_capability(self):
        im_client = _StubIMClient()
        controller = _StubController(
            platform="slack",
            im_client=im_client,
            reply_enhancements=True,
        )
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={
                "delivery_override": {
                    "platform": "wechat",
                    "channel_id": "wx1",
                }
            },
        )

        await dispatcher.emit_agent_message(context, "result", "Compare:\n[A] | [B]")

        self.assertEqual(im_client.sent_messages[0][1], "Compare:\n[A] | [B]")

    async def test_result_footer_rides_subtext_on_status_bubble_platform(self):
        """On a ``supports_status_bubble`` platform (Slack) the show_duration
        footnote is delivered as the de-emphasized ``subtext`` footer and the body
        stays clean."""
        im_client = _SubtextNativeMarkdownIMClient()
        controller = _StubController(platform="slack", im_client=im_client)
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="slack")

        message_id = await dispatcher.emit_agent_message(
            context, "result", "Answer body", result_footer="✅ ⏱️ 5s · 🪙 1.2k tok"
        )

        self.assertEqual(message_id, "native-1")
        channel_id, text, _keyboard, _reply_to, subtext = im_client.native_markdown_messages[0]
        self.assertEqual(text, "Answer body")
        self.assertEqual(subtext, "✅ ⏱️ 5s · 🪙 1.2k tok")

    async def test_result_footer_folds_into_body_without_subtext_platform(self):
        """On a platform WITHOUT subtext rendering (Telegram) the footnote folds
        onto the body and no ``subtext`` kwarg is passed — a send_message that
        lacks the kwarg would otherwise raise (the Codex P2 regression)."""
        im_client = _StubIMClient()  # send_message has no ``subtext`` parameter
        controller = _StubController(platform="telegram", im_client=im_client)
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="telegram")

        message_id = await dispatcher.emit_agent_message(
            context, "result", "Answer body", result_footer="✅ ⏱️ 5s · 🪙 1.2k tok"
        )

        self.assertEqual(message_id, "msg-1")
        channel_id, text, _parse_mode = im_client.sent_messages[0]
        self.assertEqual(text, "Answer body\n\n✅ ⏱️ 5s · 🪙 1.2k tok")

    async def test_result_footer_uses_delivery_target_capability_not_source(self):
        """A Slack (subtext) turn redirected via ``delivery_override`` to a
        non-subtext target (Telegram) must FOLD the footnote, not hand ``subtext``
        to the target adapter that ignores it (Codex P2)."""
        im_client = _StubIMClient()  # no ``subtext`` kwarg on send_message
        controller = _StubController(platform="slack", im_client=im_client)
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={"delivery_override": {"platform": "telegram", "channel_id": "T1"}},
        )

        message_id = await dispatcher.emit_agent_message(
            context, "result", "Answer body", result_footer="✅ ⏱️ 5s · 🪙 1.2k tok"
        )

        self.assertEqual(message_id, "msg-1")
        _channel, text, _parse_mode = im_client.sent_messages[0]
        self.assertEqual(text, "Answer body\n\n✅ ⏱️ 5s · 🪙 1.2k tok")

    async def test_result_footer_persisted_on_subtext_platform(self):
        """On a subtext platform (Slack) the footer is delivered out-of-band as
        subtext, but the stored text must still keep it so a reloaded transcript /
        inbox / agent-run record retains the duration/token info (Codex P2)."""
        im_client = _SubtextNativeMarkdownIMClient()
        controller = _StubController(platform="slack", im_client=im_client)
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="slack")

        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            await dispatcher.emit_agent_message(
                context, "result", "Answer body", result_footer="✅ ⏱️ 5s · 🪙 1.2k tok"
            )

        # Delivered: body clean, footer rides subtext.
        _c, text, _k, _r, subtext = im_client.native_markdown_messages[0]
        self.assertEqual(text, "Answer body")
        self.assertEqual(subtext, "✅ ⏱️ 5s · 🪙 1.2k tok")
        # Persisted: footer folded into the stored text.
        persist.assert_called_once()
        _, _ptype, ptext = persist.call_args.args
        self.assertEqual(ptext, "Answer body\n\n✅ ⏱️ 5s · 🪙 1.2k tok")
        self.assertEqual(persist.call_args.kwargs["result_footer"], "✅ ⏱️ 5s · 🪙 1.2k tok")

    async def test_folded_result_footer_is_persisted_for_non_subtext_platform(self):
        """The folded footnote must be persisted too, so a reloaded transcript /
        inbox entry matches the delivered message (result-path invariant)."""
        im_client = _StubIMClient()
        controller = _StubController(platform="telegram", im_client=im_client)
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="telegram")

        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            await dispatcher.emit_agent_message(
                context, "result", "Answer body", result_footer="✅ ⏱️ 5s · 🪙 1.2k tok"
            )

        persist.assert_called_once()
        _, persisted_type, persisted_text = persist.call_args.args
        self.assertEqual(persisted_type, "result")
        self.assertEqual(persisted_text, "Answer body\n\n✅ ⏱️ 5s · 🪙 1.2k tok")
        self.assertEqual(persist.call_args.kwargs["result_footer"], "✅ ⏱️ 5s · 🪙 1.2k tok")

    async def test_avibe_persists_clean_body_with_structured_result_footer(self):
        controller = _StubController(platform="avibe")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="avibe")

        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            await dispatcher.emit_agent_message(
                context, "result", "Answer body", result_footer="✅ ⏱️ 5s · 🪙 1.2k tok"
            )

        _, persisted_type, persisted_text = persist.call_args.args
        self.assertEqual(persisted_type, "result")
        self.assertEqual(persisted_text, "Answer body")
        self.assertEqual(persist.call_args.kwargs["result_footer"], "✅ ⏱️ 5s · 🪙 1.2k tok")

    async def test_result_persists_cleaned_display_text_not_raw(self):
        """The persisted result must match what the user was shown, not the raw
        text with reply-enhancer artifacts. The inbox preview + chat transcript
        reload the persisted row, so the trailing quick-reply button block (and
        file:// links) must already be stripped at persist time."""
        im_client = _NativeMarkdownIMClient()
        controller = _StubController(platform="slack", im_client=im_client, reply_enhancements=True)
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="slack")
        raw = "Body\n\n---\n[Continue] | [Stop]"

        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            await dispatcher.emit_agent_message(context, "result", raw)

        # Delivered text had the quick-reply block stripped to "Body".
        _, delivered_text, _, _ = im_client.native_markdown_messages[0]
        self.assertEqual(delivered_text, "Body")
        # The persisted row must equal the displayed text, not the raw input.
        persist.assert_called_once()
        _, persisted_type, persisted_text = persist.call_args.args
        self.assertEqual(persisted_type, "result")
        self.assertEqual(persisted_text, "Body")
        self.assertNotIn("[Continue]", persisted_text)

    async def test_avibe_result_persists_quick_replies_for_workbench(self):
        """avibe carries the parsed quick-reply labels to ``persist_agent_message``
        (as the ``quick_replies`` kwarg) so the workbench can render the button
        group; the persisted text still has the trailing block stripped."""
        controller = _StubController(platform="avibe", reply_enhancements=True)
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="avibe")
        raw = "Pick one:\n\n---\n[✅ Yes] | [🙅 No]"

        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            await dispatcher.emit_agent_message(context, "result", raw)

        persist.assert_called_once()
        self.assertEqual(persist.call_args.args[1], "result")
        self.assertEqual(persist.call_args.kwargs.get("quick_replies"), ["✅ Yes", "🙅 No"])
        # The block is still stripped from the persisted text itself.
        self.assertNotIn("[✅ Yes]", persist.call_args.args[2])
        self.assertIn("Pick one", persist.call_args.args[2])

    async def test_avibe_result_persists_unseparated_quick_replies_for_workbench(self):
        controller = _StubController(platform="avibe", reply_enhancements=True)
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="avibe")
        raw = "Pick one:\n[✅ Yes] | [🙅 No]"

        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            await dispatcher.emit_agent_message(context, "result", raw)

        persist.assert_called_once()
        self.assertEqual(persist.call_args.kwargs.get("quick_replies"), ["✅ Yes", "🙅 No"])
        self.assertNotIn("[✅ Yes]", persist.call_args.args[2])
        self.assertIn("Pick one", persist.call_args.args[2])

    async def test_visible_workbench_terminal_result_requires_durable_message(self):
        controller = _StubController(platform="avibe")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(
            user_id="U1",
            channel_id="ses-1",
            platform="avibe",
            platform_specific={
                "agent_session_id": "ses-1",
                "turn_token": "turn-1",
            },
        )
        dispatcher._is_current_runtime_turn = mock.Mock(return_value=True)

        with mock.patch(
            "core.message_dispatcher.persist_agent_message",
            return_value=None,
        ):
            with self.assertRaisesRegex(
                RuntimeError,
                "Workbench terminal output was not durably persisted",
            ):
                await dispatcher.emit_agent_message(context, "result", "done")

    async def test_workbench_run_settles_only_after_result_persistence(self):
        """A callback child stays pending until its Workbench receipt exists."""

        controller = _StubController(platform="avibe")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._record_agent_run_terminal_result = mock.AsyncMock()
        context = MessageContext(
            user_id="U1",
            channel_id="ses-1",
            platform="avibe",
            platform_specific={
                "agent_session_id": "ses-1",
                "task_trigger_kind": "agent_run",
                "task_execution_id": "callback-run",
            },
        )

        def _persist(*_args, **_kwargs):
            dispatcher._record_agent_run_terminal_result.assert_not_called()
            return {"id": "persisted-result"}

        with mock.patch("core.message_dispatcher.persist_agent_message", side_effect=_persist):
            await dispatcher.emit_agent_message(
                context,
                "result",
                "callback complete",
                output=MessageOutput(
                    completes_turn=True,
                    completes_run=True,
                    run_id="callback-run",
                ),
            )

        dispatcher._record_agent_run_terminal_result.assert_called_once()

    async def test_workbench_persistence_failure_does_not_settle_the_run(self):
        controller = _StubController(platform="avibe")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._record_agent_run_terminal_result = mock.AsyncMock()
        context = MessageContext(
            user_id="U1",
            channel_id="ses-1",
            platform="avibe",
            platform_specific={
                "agent_session_id": "ses-1",
                "task_trigger_kind": "agent_run",
                "task_execution_id": "callback-run",
            },
        )

        with mock.patch(
            "core.message_dispatcher.persist_agent_message",
            side_effect=RuntimeError("write failed"),
        ):
            with self.assertRaisesRegex(RuntimeError, "write failed"):
                await dispatcher.emit_agent_message(
                    context,
                    "result",
                    "callback complete",
                    output=MessageOutput(
                        completes_turn=True,
                        completes_run=True,
                        run_id="callback-run",
                    ),
                )

        dispatcher._record_agent_run_terminal_result.assert_not_called()

    async def test_workbench_duplicate_persistence_receipt_can_settle_the_run(self):
        controller = _StubController(platform="avibe")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._record_agent_run_terminal_result = mock.AsyncMock()
        context = MessageContext(
            user_id="U1",
            channel_id="ses-1",
            platform="avibe",
            platform_specific={
                "agent_session_id": "ses-1",
                "task_trigger_kind": "agent_run",
                "task_execution_id": "callback-run",
            },
        )

        with (
            mock.patch("core.message_dispatcher.persist_agent_message", return_value=None),
            mock.patch(
                "core.message_dispatcher.agent_message_exists",
                side_effect=[False, True],
            ),
        ):
            await dispatcher.emit_agent_message(
                context,
                "result",
                "callback complete",
                output=MessageOutput(
                    completes_turn=True,
                    completes_run=True,
                    run_id="callback-run",
                    idempotency_key="stable-output",
                ),
            )

        dispatcher._record_agent_run_terminal_result.assert_called_once()

    async def test_suppressed_delivery_is_persisted_without_platform_send(self):
        controller = _StubController(platform="slack")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(
            user_id="U1", channel_id="C1", platform="slack",
            platform_specific={"suppress_delivery": True},
        )
        evidence = DeliveryEvidence()
        with mock.patch(
            "core.message_dispatcher.persist_agent_message",
            return_value={"id": "msg-background"},
        ) as persist:
            message_id = await dispatcher.emit_agent_message(
                context,
                "result",
                "private output",
                delivery=evidence,
            )
        persist.assert_called_once()
        self.assertEqual(message_id, "msg-background")
        self.assertEqual(controller.im_client.sent_messages, [])
        self.assertIsNone(evidence.ack_evidence)

    async def test_suppressed_history_id_is_not_recorded_as_run_delivery(self):
        controller = _StubController(platform="slack")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._record_suppressed_agent_run_terminal_result = mock.AsyncMock()
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={
                "suppress_delivery": True,
                "task_trigger_kind": "scheduled",
                "task_execution_id": "run-background",
            },
        )
        with mock.patch(
            "core.message_dispatcher.persist_agent_message",
            return_value={"id": "msg-local-history"},
        ):
            returned = await dispatcher.emit_agent_message(
                context,
                "result",
                "private output",
                output=MessageOutput(
                    completes_turn=False,
                    completes_run=False,
                    idempotency_key="stable-output",
                ),
            )

        self.assertEqual(returned, "msg-local-history")
        self.assertIsNone(
            dispatcher._record_suppressed_agent_run_terminal_result.call_args.args[2]
        )

    async def test_suppressed_result_records_folded_footer(self):
        """A suppressed Web result keeps structured UI metrics while its run
        record retains the complete folded text."""
        controller = _StubController(platform="avibe")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        captured = {}

        def _capture(context, text, message_id, terminal_status=None):
            captured["text"] = text

        dispatcher._record_suppressed_run_message = _capture
        context = MessageContext(
            user_id="U1", channel_id="C1", platform="avibe",
            platform_specific={"suppress_delivery": True},
        )

        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            await dispatcher.emit_agent_message(
                context, "result", "private output", result_footer="✅ ⏱️ 5s · 🪙 1.2k tok"
            )

        self.assertEqual(captured["text"], "private output\n\n✅ ⏱️ 5s · 🪙 1.2k tok")
        self.assertEqual(persist.call_args.args[2], "private output")
        self.assertEqual(persist.call_args.kwargs["result_footer"], "✅ ⏱️ 5s · 🪙 1.2k tok")

    async def test_notify_persisted_only_on_successful_send(self):
        controller = _StubController(platform="slack")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="slack")
        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            await dispatcher.emit_agent_message(context, "notify", "heads up")
        persist.assert_called_once()
        self.assertEqual(persist.call_args.args[1], "notify")

    async def test_output_is_delivered_and_persisted_without_settling(self):
        controller = _StubController(platform="slack")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="slack")

        with (
            mock.patch(
                "core.message_dispatcher.persist_agent_message",
                return_value={"id": "msg-output"},
            ) as persist,
            mock.patch(
                "core.message_dispatcher._stream_chunk",
                new=mock.AsyncMock(),
            ) as stream,
        ):
            message_id = await dispatcher.emit_agent_message(
                context,
                "output",
                "primary answer",
                output=MessageOutput(completes_turn=False, completes_run=False),
            )

        self.assertEqual(message_id, "msg-1")
        self.assertEqual(controller.im_client.sent_messages, [("C1", "primary answer", "markdown")])
        self.assertEqual(persist.call_args.args[1], "output")
        stream.assert_awaited_once()
        self.assertEqual(stream.call_args.kwargs["kind"], "output")
        self.assertFalse(stream.call_args.kwargs["completes_turn"])

    async def test_output_can_explicitly_skip_agent_run_recording(self):
        controller = _StubController(platform="slack")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={"accepted_agent_run_ids": ["run-steer"]},
        )

        with (
            mock.patch(
                "core.message_dispatcher.persist_agent_message",
                return_value={"id": "msg-output"},
            ),
            mock.patch.object(
                dispatcher,
                "_record_agent_run_terminal_for_ids",
            ) as record,
        ):
            await dispatcher.emit_agent_message(
                context,
                "output",
                "primary answer",
                output=MessageOutput(
                    completes_turn=False,
                    completes_run=False,
                    records_run_output=False,
                ),
            )

        record.assert_not_called()

    async def test_notify_not_persisted_when_send_fails(self):
        class _FailClient(_StubIMClient):
            async def send_message(self, *args, **kwargs):
                raise RuntimeError("platform API down")

        controller = _StubController(platform="slack", im_client=_FailClient())
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="slack")
        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            result = await dispatcher.emit_agent_message(context, "notify", "heads up")
        self.assertIsNone(result)
        persist.assert_not_called()

    async def test_removed_platform_notify_drop_is_not_persisted(self):
        controller = _StubController(platform="discord", im_client=_DropClient())
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="discord")

        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            result = await dispatcher.emit_agent_message(context, "notify", "late notify")

        self.assertIsNone(result)
        persist.assert_not_called()

    async def _emit_split_result(self, *, fail_chunk: int | None, upload_id: str | None):
        """Emit a Discord result long enough to split, optionally failing one chunk."""

        class _FlakyChunkClient(_StubIMClient):
            def __init__(self):
                super().__init__(upload_id=upload_id)
                self.chunk_attempts = 0

            async def send_message(self, context, text, parse_mode=None, reply_to=None):
                if text.startswith("x"):
                    attempt = self.chunk_attempts
                    self.chunk_attempts += 1
                    if attempt == fail_chunk:
                        raise RuntimeError("chunk send failed")
                return await super().send_message(context, text, parse_mode, reply_to)

        controller = _StubController(platform="discord", im_client=_FlakyChunkClient())
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="discord")
        text = "x" * 5000
        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            message_id = await dispatcher.emit_agent_message(context, "result", text)
        return controller.im_client, dispatcher, text, message_id, persist

    async def test_split_result_later_chunk_failure_delivers_complete_document(self):
        client, dispatcher, text, message_id, persist = await self._emit_split_result(fail_chunk=1, upload_id="file-1")

        # The split stops at the failed chunk and the complete result is uploaded once.
        self.assertEqual(client.chunk_attempts, 2)
        self.assertEqual([upload[2] for upload in client.uploaded_markdowns], [text])
        self.assertEqual(message_id, "file-1")
        sent_texts = [sent[1] for sent in client.sent_messages]
        self.assertIn(dispatcher._t("info.resultDeliveredAsAttachment"), sent_texts)
        persist.assert_called_once()

    async def test_split_result_later_chunk_and_upload_failure_reports_failure_without_resending(self):
        client, dispatcher, _text, message_id, persist = await self._emit_split_result(fail_chunk=1, upload_id=None)

        # No second split: chunk 0 is never resent, and the turn reports failure.
        self.assertEqual(client.chunk_attempts, 2)
        self.assertEqual(len(client.uploaded_markdowns), 1)
        self.assertIsNone(message_id)
        sent_texts = [sent[1] for sent in client.sent_messages]
        self.assertEqual(len([sent for sent in sent_texts if sent.startswith("x")]), 1)
        self.assertIn(dispatcher._t("error.resultDeliveryFailed"), sent_texts)
        persist.assert_not_called()

    async def test_split_result_all_chunks_delivered_uploads_nothing(self):
        client, dispatcher, text, message_id, persist = await self._emit_split_result(fail_chunk=None, upload_id="file-1")

        self.assertGreaterEqual(client.chunk_attempts, 3)
        chunks = [sent[1] for sent in client.sent_messages if sent[1].startswith("x")]
        self.assertEqual("".join(chunks), text)
        self.assertEqual(message_id, "msg-1")
        self.assertEqual(client.uploaded_markdowns, [])
        persist.assert_called_once()

    async def test_removed_platform_result_drop_is_not_persisted(self):
        controller = _StubController(platform="discord", im_client=_DropClient())
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="discord")

        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            result = await dispatcher.emit_agent_message(context, "result", "late result")

        self.assertIsNone(result)
        persist.assert_not_called()

    async def test_stale_runtime_result_is_dropped_before_delivery_and_persistence(self):
        controller = _StubController(platform="slack")
        controller.agent_service = type(
            "AgentService",
            (),
            {
                "emit_matches_runtime_turn": staticmethod(lambda _context: False),
                "release_runtime_turn": staticmethod(lambda _context: None),
            },
        )()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={"agent_runtime_turn_key": "s:/repo", "agent_runtime_turn_token": "old"},
        )

        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            message_id = await dispatcher.emit_agent_message(context, "result", "late result")

        self.assertIsNone(message_id)
        self.assertEqual(controller.im_client.sent_messages, [])
        persist.assert_not_called()

    async def test_result_releases_runtime_gate_after_result_cleanup(self):
        controller = _StubController(platform="slack")
        events = []

        class _AgentService:
            @staticmethod
            def emit_matches_runtime_turn(_context):
                return True

            @staticmethod
            def release_runtime_turn(_context):
                events.append("release")

        controller.agent_service = _AgentService()
        dispatcher = ConsolidatedMessageDispatcher(controller)

        async def _clear_consolidated_state(_context):
            events.append("clear")

        dispatcher._clear_consolidated_state = _clear_consolidated_state
        context = MessageContext(
            user_id="U1",
            channel_id="C1",
            platform="slack",
            platform_specific={"agent_runtime_turn_key": "s:/repo", "agent_runtime_turn_token": "tok"},
        )

        with mock.patch("core.message_dispatcher.persist_agent_message"):
            await dispatcher.emit_agent_message(context, "result", "done")

        self.assertEqual(events, ["clear", "release"])

    async def test_muted_log_message_still_persists(self):
        """assistant / tool_call rows persist BEFORE the mute filter, so a muted
        process log still lands in the store (product requirement)."""
        class _HiddenSettings(_StubSettingsManager):
            def is_message_type_hidden(self, settings_key, canonical_type):
                return True

        controller = _StubController(platform="slack")
        controller.get_settings_manager_for_context = lambda ctx: _HiddenSettings()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="slack")
        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            result = await dispatcher.emit_agent_message(context, "assistant", "thinking…")
        # Hidden → not delivered, but still persisted.
        self.assertIsNone(result)
        persist.assert_called_once()
        self.assertEqual(persist.call_args.args[1], "assistant")

    async def test_summary_upload_becomes_primary_anchor_without_duplicate_upload(self):
        controller = _StubController(platform="lark", language="en", fail_first_send=True)
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="lark")
        long_text = "x" * 35000

        message_id = await dispatcher.emit_agent_message(context, "result", long_text)

        self.assertEqual(message_id, "file-1")
        self.assertEqual(
            controller.im_client.uploaded_markdowns,
            [("C1", "result.md", long_text, "markdown")],
        )
        self.assertEqual(
            controller.im_client.sent_messages,
            [("C1", "⚠️ The message could not be sent inline, so I sent it as `result.md` above.", "markdown")],
        )
        self.assertEqual(controller.session_handler.calls, [("C1", None, "file-1")])

    async def test_attachment_only_notice_uses_configured_language(self):
        controller = _StubController(platform="lark", language="zh", fail_first_send=True)
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(user_id="U1", channel_id="C1", platform="lark")
        text = "| A | B |\n| - | - |\n| 1 | 2 |"

        message_id = await dispatcher.emit_agent_message(context, "result", text)

        self.assertEqual(message_id, "file-1")
        self.assertEqual(
            controller.im_client.uploaded_markdowns,
            [("C1", "result.md", text, "markdown")],
        )
        self.assertEqual(
            controller.im_client.sent_messages,
            [("C1", "⚠️ 这条消息无法以内联形式发送,所以我已将完整内容作为 `result.md` 发在上方。", "markdown")],
        )
        self.assertEqual(controller.session_handler.calls, [("C1", None, "file-1")])

    async def test_slack_attachment_only_fallback_does_not_finalize_with_file_id(self):
        controller = _StubController(platform="slack", language="en", fail_first_send=True, upload_id="F123")
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = MessageContext(
            user_id="scheduled",
            channel_id="C1",
            thread_id="171717.123",
            platform="slack",
            platform_specific={
                "turn_source": "scheduled",
                "turn_base_session_id": "slack_171717.123",
                "scheduled_delivery_alias": {
                    "mode": "sent_message",
                    "session_key": "slack::C1",
                    "clear_source": False,
                },
            },
        )
        text = "| A | B |\n| - | - |\n| 1 | 2 |"

        message_id = await dispatcher.emit_agent_message(context, "result", text)

        self.assertEqual(message_id, "F123")
        self.assertEqual(
            controller.im_client.uploaded_markdowns,
            [("C1", "result.md", text, "markdown")],
        )
        self.assertEqual(
            controller.im_client.sent_messages,
            [("C1", "⚠️ The message could not be sent inline, so I sent it as `result.md` above.", "markdown")],
        )
        self.assertEqual(controller.session_handler.calls, [])


class _AvibeStatusController(_StubController):
    """avibe controller stub that records the sidebar-dot writes."""

    def __init__(self):
        super().__init__(platform="avibe")
        self.status_calls = []
        self.active_sink = None  # set to {"turn_token": ...} to simulate a live turn
        from core.session_turns import SessionTurnManager

        # The dot now settles via the turn owner (FSM); wire a real one so its
        # on_terminal_result reaches this stub's set_agent_status recorder.
        self.session_turns = SessionTurnManager(self)

    @staticmethod
    def _session_id_from_context(context):
        return ((context.platform_specific or {}).get("agent_session_id")) or None

    def get_turn_sink(self, session_key):
        return self.active_sink

    def set_agent_status(self, session_id, status):
        self.status_calls.append((session_id, status))


def _avibe_ctx():
    return MessageContext(
        user_id="U1",
        channel_id="ses-1",
        platform="avibe",
        platform_specific={"agent_session_id": "ses-1"},
    )


class MessageDispatcherStatusChokepointTests(unittest.IsolatedAsyncioTestCase):
    """The OUTBOUND status chokepoint: a terminal ``result`` settles the avibe dot
    (idle, or failed when ``is_error``); a ``notify`` is not terminal and leaves it."""

    async def test_terminal_result_settles_dot_idle(self):
        controller = _AvibeStatusController()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = _avibe_ctx()
        with mock.patch("core.message_dispatcher.persist_agent_message"):
            await dispatcher.emit_agent_message(context, "result", "")
        controller.session_turns.on_terminal_delivery_complete(context)
        self.assertEqual(controller.status_calls, [("ses-1", "idle")])

    async def test_terminal_error_result_settles_dot_failed(self):
        controller = _AvibeStatusController()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = _avibe_ctx()
        with mock.patch("core.message_dispatcher.persist_agent_message"):
            await dispatcher.emit_agent_message(context, "result", "", is_error=True)
        controller.session_turns.on_terminal_delivery_complete(context)
        self.assertEqual(controller.status_calls, [("ses-1", "failed")])

    async def test_contained_teardown_does_not_project_a_failed_session(self):
        """The settlement outranks ``is_error`` for the sidebar too.

        No durable Turn owns this session, so this projection IS its terminal
        state. ``is_error`` is honestly ``True`` -- nothing answered -- but the
        service retired the runtime itself, and there is no dot between ``idle``
        and ``failed`` to say so. Without the settlement this read ``failed``,
        contradicting every other surface the same release writes.
        """

        controller = _AvibeStatusController()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._collapse_status_bubble = mock.AsyncMock()
        context = _avibe_ctx()
        with mock.patch("core.message_dispatcher.persist_agent_message"):
            await dispatcher.emit_agent_message(
                context,
                "result",
                "",
                is_error=True,
                level="silent",
                output=contained_teardown_output_for(None),
                terminal_error=None,
            )
        controller.session_turns.on_terminal_delivery_complete(context)
        self.assertEqual(controller.status_calls, [("ses-1", "idle")])

    async def test_unnamed_silent_failure_still_projects_a_failed_session(self):
        """Negative control: only a NAMED non-completing settlement is exempt."""

        controller = _AvibeStatusController()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._collapse_status_bubble = mock.AsyncMock()
        context = _avibe_ctx()
        with mock.patch("core.message_dispatcher.persist_agent_message"):
            await dispatcher.emit_agent_message(
                context,
                "result",
                "",
                is_error=True,
                level="silent",
                terminal_error="provider unavailable",
            )
        controller.session_turns.on_terminal_delivery_complete(context)
        self.assertEqual(controller.status_calls, [("ses-1", "failed")])

    async def test_silent_backend_failure_collapses_status_as_failed(self):
        controller = _AvibeStatusController()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._collapse_status_bubble = mock.AsyncMock()
        context = _avibe_ctx()
        with mock.patch("core.message_dispatcher.persist_agent_message"):
            await dispatcher.emit_agent_message(
                context,
                "result",
                "",
                is_error=True,
                level="silent",
                terminal_error="provider unavailable",
            )
        dispatcher._collapse_status_bubble.assert_awaited_once_with(
            context,
            controller.im_client,
            reason="failed",
        )

    async def test_user_stop_collapses_status_as_stopped(self):
        """A turn the user called off is not a turn that succeeded.

        The footer word was derived from ``is_error`` alone, and a stop emits with
        that flag CLEAR -- correctly, nobody's backend broke. So the last thing the
        user saw after pressing Stop was a green ``✅ done`` on a turn that never
        answered. The settlement is the fact that contradicts it, exactly as it does
        on the Turn-outcome and sidebar surfaces.
        """

        controller = _AvibeStatusController()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._collapse_status_bubble = mock.AsyncMock()
        context = _avibe_ctx()
        with mock.patch("core.message_dispatcher.persist_agent_message"):
            await dispatcher.emit_agent_message(
                context,
                "result",
                "",
                level="silent",
                output=stop_output_for(None),
            )

        dispatcher._collapse_status_bubble.assert_awaited_once_with(
            context,
            controller.im_client,
            reason="stopped",
        )

    async def test_silent_success_still_collapses_as_done(self):
        """The negative control, on the same call site the stop test asserts.

        A silent turn that simply chose not to speak (a ``<silent>`` reply) carries
        no settlement and no error, and must keep the green word. Only membership in
        ``SETTLEMENTS_WITHOUT_RESULT`` takes it away.
        """

        controller = _AvibeStatusController()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        dispatcher._collapse_status_bubble = mock.AsyncMock()
        context = _avibe_ctx()
        with mock.patch("core.message_dispatcher.persist_agent_message"):
            await dispatcher.emit_agent_message(context, "result", "", level="silent")

        dispatcher._collapse_status_bubble.assert_awaited_once_with(
            context,
            controller.im_client,
            reason="done",
        )

    async def test_notify_does_not_settle_dot(self):
        controller = _AvibeStatusController()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        with mock.patch("core.message_dispatcher.persist_agent_message"):
            await dispatcher.emit_agent_message(_avibe_ctx(), "notify", "fyi")
        self.assertEqual(controller.status_calls, [])

    async def test_superseded_turn_result_does_not_settle_dot(self):
        # A late result whose turn_token != the active sink's token (a stopped or
        # superseded turn) must NOT settle the dot for the new active turn.
        controller = _AvibeStatusController()
        controller.active_sink = {"turn_token": "new-turn"}
        dispatcher = ConsolidatedMessageDispatcher(controller)
        ctx = MessageContext(
            user_id="U1",
            channel_id="ses-1",
            platform="avibe",
            platform_specific={"agent_session_id": "ses-1", "turn_token": "old-turn"},
        )
        with mock.patch("core.message_dispatcher.persist_agent_message"):
            await dispatcher.emit_agent_message(ctx, "result", "", is_error=True)
        self.assertEqual(controller.status_calls, [])

    async def test_active_turn_token_match_settles_dot(self):
        # Same token (the live turn) → the dot settles normally.
        controller = _AvibeStatusController()
        controller.active_sink = {"turn_token": "turn-1"}
        dispatcher = ConsolidatedMessageDispatcher(controller)
        ctx = MessageContext(
            user_id="U1",
            channel_id="ses-1",
            platform="avibe",
            platform_specific={"agent_session_id": "ses-1", "turn_token": "turn-1"},
        )
        with mock.patch("core.message_dispatcher.persist_agent_message"):
            await dispatcher.emit_agent_message(ctx, "result", "")
        controller.session_turns.on_terminal_delivery_complete(ctx)
        self.assertEqual(controller.status_calls, [("ses-1", "idle")])

    async def test_tokenless_result_does_not_settle_dot_when_live_turn_exists(self):
        # A live interactive turn registered a sink WITH a token; an older
        # scheduled/watch result arrives tokenless (scheduled runs register no sink).
        # It must NOT settle the live turn's dot — previously the guard fail-opened on
        # the absent token, so the stale result flipped the live turn to idle (Codex P2).
        controller = _AvibeStatusController()
        controller.active_sink = {"turn_token": "live-turn"}
        dispatcher = ConsolidatedMessageDispatcher(controller)
        ctx = MessageContext(
            user_id="U1",
            channel_id="ses-1",
            platform="avibe",
            platform_specific={"agent_session_id": "ses-1"},  # no turn_token (scheduled)
        )
        with mock.patch("core.message_dispatcher.persist_agent_message"):
            await dispatcher.emit_agent_message(ctx, "result", "")
        self.assertEqual(controller.status_calls, [])

    async def test_silent_result_settles_dot_but_suppresses_delivery(self):
        # ``level="silent"`` is the explicit visibility grade (orthogonal to type):
        # a terminal result still settles the dot + releases the stream, but is NOT
        # delivered or persisted — even with NON-EMPTY text. This is what an
        # intentional stop emits: the turn ends cleanly with no user-facing bubble,
        # replacing the old "fake invisibility via empty text" trick.
        controller = _AvibeStatusController()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        context = _avibe_ctx()
        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            message_id = await dispatcher.emit_agent_message(
                context, "result", "🛑 stopped", level="silent"
            )
        controller.session_turns.on_terminal_delivery_complete(context)
        self.assertIsNone(message_id)
        self.assertEqual(controller.status_calls, [("ses-1", "idle")])  # dot still settles
        persist.assert_not_called()  # never recorded in history
        self.assertEqual(controller.im_client.sent_messages, [])  # no user-facing bubble

    async def test_silent_notify_is_not_terminal_and_suppressed(self):
        # A silent NON-result (notify) is not terminal: it neither settles the dot
        # nor is delivered/persisted.
        controller = _AvibeStatusController()
        dispatcher = ConsolidatedMessageDispatcher(controller)
        with mock.patch("core.message_dispatcher.persist_agent_message") as persist:
            message_id = await dispatcher.emit_agent_message(
                _avibe_ctx(), "notify", "fyi", level="silent"
            )
        self.assertIsNone(message_id)
        self.assertEqual(controller.status_calls, [])
        persist.assert_not_called()
        self.assertEqual(controller.im_client.sent_messages, [])


if __name__ == "__main__":
    unittest.main()