Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

63.3 KB
Raw Blame
"""The society runtime — one lazily built object wiring store, roster, rooms,
scheduler and the mission bridge together.

Built on the first REST call (``app.state.society_factory``), never at boot
(AP-26). Every collaborator is reached through a getter so the runtime can
be constructed in a test with fakes and in the server with the live
mission manager, budget tracker, brain tool registry and skill registry.

Dispatch: an ``ASSIGN`` becomes, by default, one turn in the target's
canonical chat — Jarvis' brain runner with the roster row's provider, model,
tools and briefing, so per-agent customization applies in full; the turn's
end is written back as a RESULT on the board. ``payload.runner == "mission"``
(or no chat service at all) routes to the mission stack instead: worktree
isolation for heavy coding work, the agent's identity carried by the prompt,
the ownership map letting the bridge attribute every mission event back.
"""

from __future__ import annotations

import asyncio
import inspect
import logging
from collections.abc import Callable, Iterable, Mapping
from contextlib import AsyncExitStack
from contextvars import ContextVar
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Final
from uuid import uuid4

from dodaios.missions.events import MISSION_LANGUAGES

from .approvals import Approvals
from .bridge import MissionBridge
from .browser.session import BrowserJobs
from .capabilities import CapabilityKind, CapabilityRow, build_catalog
from .checkpoints import CheckpointEngine
from .communication import reply_policy, should_report
from .conversation import ConversationArchive
from .delivery import IncomingMessage, incoming_context
from .display_name import display_name, lead_display_name
from .events import MsgType, QuestState, RoomState, SocietyEnvelope, Tier, now_ms
from .focus import derive_approval_rules, derive_focus
from .learning import AgentSkills, LearningPass, TurnDigest, default_creator_factory
from .memory import SocietyMemory
from .quests import Quests
from .rooms import Rooms
from .roster import (
    LEAD_AGENT_ID,
    LEAD_AGENT_ROW_NAME,
    AgentRecord,
    Roster,
    conversation_session_id,
)
from .scheduler import DeliverHook, SocietyScheduler
from .seeds import seed_first_run
from .store import SocietyStore
from .world_feed import WorldFeed

log = logging.getLogger(__name__)

__all__ = ["SocietyRuntime", "current_runtime", "set_current_runtime"]

_DB_NAME = "society.db"
_CLOSE_TASK_TIMEOUT_S = 2.0
_USABLE_TTL_S = 30.0


@dataclass(frozen=True, slots=True)
class _UsablePlugins:
    catalog_ids: frozenset[str]
    ids: frozenset[str]
    read_at: float


#: Set by a caller that waits for the reply to the message it is about to send
#: and says that reply itself (``dodaios.plugins.tool.ask_agent``).
#: The value is an empty list that receives the id of the ONE question it
#: marks; a task that inherits the context finds the list already used.
#: How many answers said inside a call are remembered until their delivery runs.
_ANSWERED_INLINE_MAX: Final[int] = 256
reply_awaited_inline: ContextVar[list[str] | None] = ContextVar(
    "reply_awaited_inline", default=None
)


class SocietyRuntimeClosed(RuntimeError):
    """This runtime owner has entered terminal shutdown."""


# An agent reporting back to the lead is SHOWN, never spoken: a notice in the
# newest front-page chat carries the full text. The spoken readback (a flash
# model phrasing the report, billed on an API key) was removed by maintainer
# decision 2026-09-30 — nobody asked to hear background results read out.

#: Board types that are somebody TALKING to the lead. RESULT stays out: chat
#: runs post it via report_to_lead and mission runs via the mission stack —
#: posting it here as well would show every completion twice.
_LEAD_INCOMING_TYPES: Final[frozenset[MsgType]] = frozenset(
    {MsgType.SAY, MsgType.QUERY, MsgType.ANSWER, MsgType.PROPOSE}
)
_WATCH_EVENT_POLL_SECONDS: Final[float] = 2.0
#: Quiet polls in a row, each after a durable read, that the chat must report no
#: running turn before the watcher stops waiting for a terminal event. Two, so a
#: turn that ends between the read and the check is still read on the next poll.
_WATCH_GONE_POLLS: Final[int] = 2
#: The drill switch: a file in the data dir that injects a named fault.
_DRILL_FILE: Final[str] = "society_drill.json"
_DRILL_MAX_S: Final[float] = 30.0

_current: SocietyRuntime | None = None


def current_runtime() -> SocietyRuntime | None:
    """The runtime the app built (the society surface reaches it through here)."""
    return _current


def set_current_runtime(runtime: SocietyRuntime | None) -> None:
    global _current  # noqa: PLW0603 - one process, one society
    _current = runtime


def _turn_alive(svc: Any, session_id: str) -> bool:
    """Whether the chat still runs a turn here; unknown counts as alive."""
    is_running = getattr(svc, "is_running", None)
    if not callable(is_running):
        return True
    try:
        return bool(is_running(session_id))
    except Exception:  # noqa: BLE001 - an unanswerable probe must not end a live turn
        log.debug("society: turn liveness probe failed for %s", session_id, exc_info=True)
        return True


def _pause_self_build() -> bool:
    """The society kill switch also pauses the self-building loop.

    Stopping every agent while the loop keeps building new ones would make the
    switch a half stop. Releasing the kill switch does not resume the loop:
    the person resumes it in "Built for you" (docs/self-build.md).
    """
    try:
        from dodaios.self_build import current as current_self_build

        service = current_self_build()
        if service is None:
            return False
        service.set_paused(True)
        return True
    except Exception:  # noqa: BLE001 — the kill switch itself must never fail on this
        log.warning("society kill switch: pausing the self-build loop failed", exc_info=True)
        return False


def _agent_frame(agent: AgentRecord, task: str, config: Any = None) -> str:
    """The mission prompt that carries the agent's identity to a worker."""
    name = display_name(agent, config)
    lines = [
        f"You are {name}" + (f", {agent.title}" if agent.title else "") + ",",
        f"a {agent.tier} agent in the user's agent society led by {lead_display_name(config)}.",
    ]
    if agent.description.strip():
        lines += ["", "Standing instructions:", agent.description.strip()]
    if agent.focus:
        lines += ["", "Reach for these capabilities first: " + ", ".join(agent.focus)]
    lines += ["", "Task:", task.strip()]
    return "\n".join(lines)


class SocietyRuntime:
    def __init__(
        self,
        data_dir: Path,
        *,
        mission_manager: Callable[[], Any | None] | None = None,
        mission_bus: Callable[[], Any | None] | None = None,
        budget_tracker: Callable[[], Any | None] | None = None,
        brain_tools: Callable[[], Mapping[str, Any] | None] | None = None,
        skills: Callable[[], Iterable[Any] | None] | None = None,
        deliver: DeliverHook | None = None,
        chat_service: Callable[[], Any | None] | None = None,
        cfg: Callable[[], Any] | None = None,
        # Only Jarvis is on the roster by default (maintainer, 2026-09-02); the
        # starter team is offered as seed proposals instead.
        seed_starter_team: bool = False,
        event_publish: Callable[[Any], Any] | None = None,
        app_bus: Any = None,
        task_services: Callable[[], tuple[Any, Any]] | None = None,
        # ``(catalog plugin ids, usable plugin ids)``; ``None`` treats every
        # loaded plugin as connected (tests, headless boxes without keyring).
        plugin_state: Callable[[], tuple[Iterable[str], Iterable[str]]] | None = None,
    ) -> None:
        self._data_dir = Path(data_dir)
        self._plugin_state = plugin_state
        self._usable_cache: _UsablePlugins | None = None
        from .coding_threads import CodingThreads

        self.coding_threads = CodingThreads(self)
        from .chat_runs import ChatRunLedger

        self.chat_runs = ChatRunLedger(self)
        self._get_manager = mission_manager or (lambda: None)
        self._get_mission_bus = mission_bus or (lambda: None)
        self._get_budget = budget_tracker or (lambda: None)
        self._get_tools = brain_tools or (lambda: None)
        self._get_skills = skills or (lambda: None)
        self._deliver = deliver
        self._get_chat = chat_service or (lambda: None)
        self._get_cfg = cfg or (lambda: None)
        self.task_services = task_services or (lambda: (None, None))
        self._seed_starter_team = seed_starter_team
        self._watchers: set[asyncio.Task[None]] = set()
        self.store = SocietyStore(self._data_dir / _DB_NAME)
        self.roster = Roster(self.store)
        self.rooms = Rooms(self.store)
        from .meetings import Meetings

        self.meetings = Meetings(self)
        self.approvals = Approvals(self.store)
        self.browser = BrowserJobs(self._data_dir)
        self.scheduler = SocietyScheduler(
            self.store,
            self.roster,
            dispatch=self._dispatch,
            deliver=deliver,
            budget_tracker=None,
        )
        self.bridge = MissionBridge(
            self.store, owner_of=self.owner_of, on_run_ended=self.scheduler.note_run_ended
        )
        self._owners: dict[str, str] = {}
        #: Where an agent is on the island, derived from the board (memory-house.md §3.4).
        # ``event_publish`` is the app bus the WebSocket forwards (server.py hands
        # it in); without it the engine falls back to the process default bus.
        self.checkpoints = CheckpointEngine(self, publish=event_publish)
        self._publish_event = event_publish
        #: The society's one memory service; every touch moves the figure to the Memory House.
        self.memory = SocietyMemory(self, on_activity=self.checkpoints.note_memory_activity)
        self.conversations = ConversationArchive(
            self._data_dir / "society-conversations.db", defer_open=True
        )
        self._review_lock = asyncio.Lock()
        #: Requests whose reply a caller is waiting for and will speak itself;
        #: their answer is not announced a second time (``reply_awaited_inline``).
        self._awaited_inline: set[str] = set()
        #: Requests whose answer a caller already received and said. The runtime
        #: may deliver that answer only after the caller stopped waiting; this
        #: keeps that late delivery quiet (in insertion order, bounded).
        self._answered_inline: dict[str, None] = {}
        #: The Quest Board: the person's jobs, routed to one taker, read back off the board.
        self.quests = Quests(self)
        from .team_lead import TeamLeads

        #: Team leads: a member that manages its team toward the person's goals.
        self.team_leads = TeamLeads(self, publish=event_publish)
        #: Speech on the board, projected onto the island: two agents talking
        #: turn to each other, two agents apart call across the map.
        self.world_feed = WorldFeed(self, publish=event_publish)
        #: Roster rows the society surface read for a turn - the sync tool
        #: filter reads them here (the briefing fills the cache first).
        self._agent_cache: dict[str, AgentRecord] = {}
        self._skills: dict[str, AgentSkills] = {}
        self.learning = LearningPass(
            self,
            creator_factory=default_creator_factory(self._get_cfg),
            notify=self._notify_chat,
        )
        self._start_lock = asyncio.Lock()
        self._delivery_task: asyncio.Task[None] | None = None
        # Runs for the whole session, so it is not one of ``_watchers``
        # (finite background work that callers may wait for).
        self._runtime_updates_task: asyncio.Task[None] | None = None
        self._delivery_unsubscribe: Callable[[], None] | None = None
        self._lead_incoming_unsubscribe: Callable[[], None] | None = None
        self._started = False
        self._closing = False
        self._starting_task: asyncio.Task[Any] | None = None
        self._context_start_task: asyncio.Task[bool] | None = None

    # ------------------------------------------------------------ lifecycle

    async def prepare_context(self, *, timeout_s: float = 0.3) -> bool:
        """Bound first-turn team hydration without canceling partial startup.

        Voice/chat may continue while storage is slow. One owned task does the
        work; close cancels and reaps it before dismantling runtime components.
        """
        if self._closing:
            return False
        if self._started:
            return True
        task = self._context_start_task
        if task is None or task.done():
            task = asyncio.create_task(self._start_for_context(), name="society-context")
            self._context_start_task = task
        try:
            return await asyncio.wait_for(asyncio.shield(task), timeout=timeout_s)
        except TimeoutError:  # A bounded wait reports that the task is still running.
            return False

    async def _start_for_context(self) -> bool:
        try:
            await self.ensure_started()
        except Exception:  # noqa: BLE001 - optional team must not prevent conversation
            log.warning("society context startup failed", exc_info=True)
            return False
        return True

    async def ensure_started(self) -> SocietyRuntime:
        self._require_open_owner()
        async with self._start_lock:
            self._require_open_owner()
            if self._started:
                return self
            self._starting_task = asyncio.current_task()
            try:
                return await self._start_runtime()
            finally:
                # A slow startup that outlives the shutdown deadline still owns
                # its provisional store until it unwinds; never orphan it.
                try:
                    if self._closing:
                        await self.store.close()
                finally:
                    self._starting_task = None

    def _require_open_owner(self) -> None:
        if self._closing:
            raise SocietyRuntimeClosed("society runtime stopped")

    async def _start_runtime(self) -> SocietyRuntime:
        await self.store.open()
        self._require_open_owner()
        # FTS backfill can take seconds on a busy disk. It must never stall
        # HTTP, microphone controls or the first response from the desktop.
        await asyncio.to_thread(self.conversations.open)
        self._require_open_owner()
        self.scheduler._budget = self._get_budget()  # noqa: SLF001 — the runtime owns its scheduler
        self.scheduler.attach()
        self._delivery_unsubscribe = self.store.bus.subscribe_all(self._delivery_failed)
        self._lead_incoming_unsubscribe = self.store.bus.subscribe_all(self._on_lead_incoming)
        bus = self._get_mission_bus()
        if bus is not None:
            self.bridge.attach(bus)
        self.checkpoints.attach()
        self.quests.attach()
        self.world_feed.attach()
        await self.seed_lead()
        self._require_open_owner()
        if self._seed_starter_team:
            created = await seed_first_run(self.roster, self.store)
            if created:
                log.info("society: starter team seeded: %s", ", ".join(created))
        # Warm the roster snapshot so the lead card (lead_card.py) — a
        # synchronous reader on the brain's prompt build — sees the team from
        # the first turn, not from the first REST listing.
        await self.roster.refresh()
        # After the roster: the lead prompts read names off its snapshot.
        await self.team_leads.start()
        self._require_open_owner()
        self._started = True
        self._delivery_task = asyncio.create_task(self._deliver_pending())
        set_current_runtime(self)
        await self.coding_threads.start()
        await self.chat_runs.start()
        self._require_open_owner()
        self.background(self.recover_reviews())
        self._runtime_updates_task = asyncio.create_task(self._keep_agent_runtimes_current())
        log.info("society runtime started (%s)", self.store.path)
        return self

    async def _keep_agent_runtimes_current(self) -> None:
        """Daily Hermes / OpenClaw updates for the runtimes agents use
        (``agent_runtimes.manager.keep_current``; first round after 10 min)."""
        from dodaios.agent_runtimes import manager

        async def in_use() -> set[str]:
            agents = await self.roster.list()
            return {str(agent.runtime) for agent in agents} - {"", "jarvis"}

        await manager.keep_current(in_use)

    async def _delivery_failed(self, env: SocietyEnvelope) -> None:
        """Project a terminal scheduler veto onto an already-visible chat receipt."""
        if env.msg_type is not MsgType.VETO or not env.parent_event_id:
            return
        svc = self._get_chat()
        if svc is None:
            return
        for original in await self.store.events_for_trace(env.trace_id):
            if original.event_id != env.parent_event_id or not original.to_agent:
                continue
            session_id = conversation_session_id(original.to_agent, original.from_agent)
            if svc.store.incoming_message(session_id, original.event_id) is not None:
                await svc.message_status(session_id, original.event_id, "failed", error=env.text)
            break

    async def _on_lead_incoming(self, env: SocietyEnvelope) -> None:
        """Post replies to a specific request from Jarvis into the lead chat.

        Direct agent chats and unsolicited board messages stay on the board. A
        past assignment to the same agent is not permission to surface a new
        chat. Assignment completions keep their report_to_lead notice.
        """
        try:
            if env.to_agent != LEAD_AGENT_ID or env.msg_type not in _LEAD_INCOMING_TYPES:
                return
            if env.from_agent in (LEAD_AGENT_ID, "user", "scheduler"):
                return
            sender = await self.roster.get(env.from_agent)
            if sender is None:
                return
            requests = await self.store.events_for_trace(env.trace_id)
            request = next(
                (
                    item
                    for item in requests
                    if item.from_agent == LEAD_AGENT_ID
                    and item.to_agent == env.from_agent
                    and item.msg_type
                    in (MsgType.SAY, MsgType.QUERY, MsgType.PROPOSE, MsgType.ASSIGN)
                    and item.event_id == env.parent_event_id
                ),
                None,
            )
            if request is None:
                return
            if (
                request.msg_type is MsgType.ASSIGN and "reply_policy" in request.payload
                and env.msg_type is MsgType.ANSWER
            ):
                # The turn watcher owns this completion, including semantic blockers.
                return
            status = (
                "needs_input" if env.msg_type in (MsgType.QUERY, MsgType.PROPOSE)
                else str(env.payload.get("reply_status") or "done")
            )
            if not should_report(request, status):
                return
            await self.announce_lead_message(sender, env, request=request)
        except Exception:  # noqa: BLE001 - a silent message is a lost courtesy, not a lost result
            log.warning("society: lead incoming announcement failed", exc_info=True)

    async def announce_lead_message(
        self, sender: AgentRecord, env: SocietyEnvelope, *, request: SocietyEnvelope,
    ) -> None:
        """Return a correlated answer or clarification to its requesting conversation."""
        status = (
            "needs_input" if env.msg_type in (MsgType.QUERY, MsgType.PROPOSE)
            else str(env.payload.get("reply_status") or "done")
        )
        await self._deliver_lead_result(
            sender, request, status=status, summary=env.text,
            kind="society_message", message_type=str(env.msg_type).lower(),
        )

    async def _deliver_lead_result(
        self, target: AgentRecord, request: SocietyEnvelope, *, status: str,
        summary: str, kind: str, message_type: str = "",
    ) -> None:
        from dodaios.core.delegation import result_announcement

        # Read before the first await: the asker may stop waiting meanwhile.
        said_inline = request.event_id in self._awaited_inline or (
            self._answered_inline.pop(request.event_id, False) is None
        )
        event = result_announcement(
            source="society.lead", request_id=request.event_id,
            name=self.display_name(target),
            request=request.text, status=status, report=summary,
            language=str(request.payload.get("lang") or ""),
        )
        svc = self._get_chat()
        post = getattr(svc, "post_notice", None)
        if post is not None:
            try:
                session_id = str(request.payload.get("reply_session_id") or "")
                if not session_id:
                    sessions = svc.store.list_sessions(limit=1, surface="jarvis")
                    session_id = sessions[0].session_id if sessions else ""
                # Never redirect a result from a deleted chat into an unrelated one.
                session = svc.store.get_session(session_id) if session_id else None
                if session is not None and session.surface == "jarvis":
                    await post(session_id, {
                        "kind": kind, "agent_id": target.agent_id,
                        "agent_name": self.display_name(target),
                        "msg_type": message_type, "status": status, "text": summary[:1000],
                        "session_id": target.session_id, "trace_id": request.trace_id,
                        "assignment_id": request.event_id, "report": event.report,
                    })
            except Exception:  # A chat failure must not suppress the voice result.
                log.warning("society: result notice delivery failed", exc_info=True)
        if said_inline or request.event_id in self._awaited_inline:
            # The asker is waiting on this very answer, or already has it, and
            # says it itself; the chat notice above keeps the durable copy.
            return
        surface = request.payload.get("reply_surface")
        if surface == "voice" or (surface is None and request.trace_id.startswith("voice:")):
            if self._publish_event is not None:
                try:
                    value = self._publish_event(event)
                    if inspect.isawaitable(value):
                        await value
                except Exception:  # The durable board and chat still retain the report.
                    log.warning("society: result announcement failed", exc_info=True)

    def stop_awaiting_inline(self, request_id: str, *, answered: bool = False) -> None:
        """The caller stopped waiting.

        ``answered``: it has the answer and said it, so that answer's delivery
        stays quiet even when it runs later. Otherwise a later reply is
        announced as usual.
        """
        self._awaited_inline.discard(request_id)
        if answered:
            self._answered_inline[request_id] = None
            while len(self._answered_inline) > _ANSWERED_INLINE_MAX:
                self._answered_inline.pop(next(iter(self._answered_inline)))

    async def _deliver_pending(self) -> None:
        """Recover committed messages and retry busy chats without opening sockets."""
        while True:
            try:
                await self.scheduler.drain_deliveries()
            except Exception:  # noqa: BLE001 — one failed pass must not lose the queue
                log.warning("society: delivery recovery failed", exc_info=True)
            await asyncio.sleep(1.0)

    @property
    def data_dir(self) -> Path:
        return self._data_dir

    @property
    def started(self) -> bool:
        """True between ensure_started() and close(): the store is open.

        The runtime is built lazily before it starts, so a reader that does
        not start it itself must check this before touching the store.
        """
        return self._started and not self._closing

    def chat_service(self) -> Any | None:
        """The agent-chat service, when the app has one (None in the bare runtime)."""
        return self._get_chat()

    def config(self) -> Any:
        """The live app config the chat binding reads provider defaults from."""
        return self._get_cfg()

    def display_name(self, agent: AgentRecord) -> str:
        """The name to show, speak or send for ``agent`` (``display_name`` module)."""
        return display_name(agent, self._get_cfg())

    async def close(self) -> None:
        # HTTP serving continues during independent server cleanup. Fence this
        # owner synchronously so a late roster/context request cannot reopen it.
        self._closing = True

        def clear_runtime() -> None:
            self._started = False
            if current_runtime() is self:
                set_current_runtime(None)

        # Register every release before the first await. A failing or cancelled
        # browser/supervisor cleanup must still close SQLite's non-daemon worker.
        # Exit-stack callbacks run in reverse order, keeping storage alive until
        # tasks and subscriptions have relinquished it; failures still propagate.
        async with AsyncExitStack() as cleanup:
            cleanup.callback(clear_runtime)
            cleanup.push_async_callback(self.store.close)
            cleanup.push_async_callback(asyncio.to_thread, self.conversations.close)
            for release in (
                self.world_feed.detach,
                self.team_leads.detach,
                self.quests.detach,
                self.checkpoints.detach,
                self.bridge.detach,
                self.scheduler.detach,
            ):
                cleanup.callback(release)
            cleanup.push_async_callback(self.browser.close)
            cleanup.push_async_callback(self.meetings.close)
            for attribute in ("_delivery_unsubscribe", "_lead_incoming_unsubscribe"):
                unsubscribe = getattr(self, attribute)
                if unsubscribe is not None:
                    cleanup.callback(unsubscribe)
                    setattr(self, attribute, None)
            cleanup.push_async_callback(self.coding_threads.close)
            cleanup.push_async_callback(self.chat_runs.close)
            # Hermes / OpenClaw agents: their Gateways must not outlive the app.
            from dodaios.agent_runtimes import stop_all as stop_agent_runtimes

            cleanup.push_async_callback(stop_agent_runtimes)

            tasks: set[asyncio.Task[Any]] = set(self._watchers)
            for task in (
                self._starting_task,
                self._context_start_task,
                self._delivery_task,
                self._runtime_updates_task,
            ):
                if task is not None:
                    tasks.add(task)
            for task in tasks:
                task.cancel()
            try:
                if tasks:
                    done, pending = await asyncio.wait(tasks, timeout=_CLOSE_TASK_TIMEOUT_S)
                    for task in done:
                        if not task.cancelled() and (error := task.exception()) is not None:
                            log.warning("society shutdown task failed: %s", type(error).__name__)
                    if pending:
                        raise TimeoutError("society task shutdown incomplete")
            finally:
                if self._context_start_task is not None and self._context_start_task.done():
                    self._context_start_task = None
                if self._delivery_task is not None and self._delivery_task.done():
                    self._delivery_task = None
                if self._runtime_updates_task is not None and self._runtime_updates_task.done():
                    self._runtime_updates_task = None
                self._watchers.difference_update(task for task in tasks if task.done())

    def skills_for(self, agent_id: str) -> AgentSkills:
        """The agent's private skill namespace (lazy registry)."""
        skills = self._skills.get(agent_id)
        if skills is None:
            skills = AgentSkills(self._data_dir, agent_id)
            self._skills[agent_id] = skills
        return skills

    async def turn_completed(self, session: Any, completion: Any) -> None:
        import json

        events = json.loads(completion.events_json)
        await asyncio.to_thread(self.conversations.ingest, session.session_id, events)
        await self._complete_message_reply(session, completion, events)
        terminal = [e for e in events if e.get("kind") == "turn_finished"]
        finished = bool(terminal) and terminal[-1].get("payload", {}).get("status") in {
            "done",
            "ok",
            "completed",
        }
        if completion.turn.direct_user:
            from .surface import agent_id_of

            owner = agent_id_of(session.session_id)
            if owner and self.team_leads.group_led_by(owner) is not None:
                # The person's own turn in a team lead's chat: a goal the lead
                # acted on in it is followed up like a managing turn.
                final = next(
                    (
                        str(e.get("payload", {}).get("text") or "")
                        for e in reversed(events)
                        if e.get("kind") == "assistant_text"
                    ),
                    "",
                )
                self.background(
                    self.team_leads.person_turn_ended(owner, ok=finished, final=final)
                )
        if not finished:
            return
        names = {
            str(e.get("payload", {}).get("name") or "")
            for e in events
            if e.get("kind") == "tool_call"
        }
        from .memory_intent import has_write_receipt

        if (
            names
            and names <= {"society_propose_change", "society_wiki_note"}
            and has_write_receipt(events)
        ):
            # These turns already have a successful durable-write receipt.
            # Reviewing them again wastes a model call and can
            # duplicate a standing instruction as a conflicting memory.
            return
        if self.meetings.is_contributing(session.session_id):
            # A meeting contribution is a read-only reply in a shared round,
            # often a silent pass; reviewing each one would add a model call
            # per member to every message the person sends.
            return
        if self.team_leads.is_managing(session.session_id):
            # A lead's managing turn hands out and checks work; a review after
            # each one would add a model call to every step of every goal.
            return
        window_key = ""
        if completion.turn.direct_user:
            # The person's turns are reviewed per window, not per answer.
            windowed = await self._review_window(session, events)
            if windowed is None:
                return
            events, window_key = windowed
        queued = await asyncio.to_thread(
            self.conversations.queue_review,
            session.session_id,
            completion.turn.turn_id,
            events,
            direct_user=completion.turn.direct_user,
        )
        if window_key:
            # Cleared only once the review holds the window's evidence durably.
            await self.store.set_meta(window_key, "")
        if queued:
            self.background(self.recover_reviews())

    async def _review_window(
        self, session: Any, events: list[dict[str, Any]]
    ) -> tuple[list[dict[str, Any]], str] | None:
        """Add a person's turn to its chat's review window (``review_cadence``).

        Returns the whole window's events and its meta key when it is due for
        review, else ``None``. Without a chat store to read the window back,
        every turn is reviewed on its own, as before.
        """
        from .review_cadence import ReviewWindow, window_events

        svc = self._get_chat()
        store = getattr(svc, "store", None)
        if store is None or not callable(getattr(store, "list_events", None)):
            return events, ""
        key = ReviewWindow.key(session.session_id)
        window = ReviewWindow.parse(await self.store.get_meta(key, ""))
        now = now_ms()
        window.add_turn(events, now)
        users = [
            str((e.get("payload") or {}).get("text") or "")
            for e in window_events(events)
            if e.get("kind") == "user_message"
        ]
        if not window.due(users, now):
            await self.store.set_meta(key, window.dump())
            return None
        history = await asyncio.to_thread(
            store.list_events, session.session_id, after_seq=max(0, window.since_seq - 1)
        )
        return (window_events(history) or events), key

    async def _complete_message_reply(
        self, session: Any, completion: Any, events: list[dict[str, Any]]
    ) -> None:
        """Return a requested answer even when the receiver only writes its final text."""
        incoming = incoming_context.get()
        if incoming is None or completion.turn.direct_user:
            return
        request = await self.store.get_event(incoming.message_id)
        if (
            request is None
            or request.to_agent is None
            or request.msg_type not in (MsgType.QUERY, MsgType.SAY, MsgType.PROPOSE)
            or session.session_id != conversation_session_id(request.to_agent, request.from_agent)
            or reply_policy(request) == "none"
            or await self.store.kill_switch()
        ):
            return
        replies = await self.store.events_for_trace(request.trace_id)
        if any(
            item.msg_type is MsgType.ANSWER
            and item.parent_event_id == request.event_id
            and item.from_agent == request.to_agent
            and item.to_agent == request.from_agent
            for item in replies
        ):
            return
        final = next(
            (
                str(item.get("payload", {}).get("text") or "").strip()
                for item in reversed(events)
                if item.get("kind") == "assistant_text"
            ),
            "",
        )
        terminal: dict[str, Any] = next(
            (
                item.get("payload", {})
                for item in reversed(events)
                if item.get("kind") == "turn_finished"
            ),
            {},
        )
        status = (
            "done" if final and terminal.get("status") in ("done", "ok", "completed") else "blocked"
        )
        if not should_report(request, status):
            return
        await self.say(
            from_agent=request.to_agent,
            to_agent=request.from_agent,
            text=final
            or "The receiving turn ended without an answer; the request remains unresolved.",
            trace_id=request.trace_id,
            parent_event_id=request.event_id,
            msg_type=MsgType.ANSWER,
            payload={
                "reply_policy": "none",
                "reply_status": status,
                "from_session": session.session_id,
            },
        )

    async def recover_reviews(self) -> None:
        from .review_queue import drain_reviews

        await drain_reviews(self)

    def background(self, coro: Any) -> asyncio.Task[Any]:
        """Run a coroutine as a tracked task (cancelled on close, AP-30: its
        own body reports failures — nothing here swallows them)."""
        task = asyncio.create_task(coro)
        self._watchers.add(task)
        task.add_done_callback(self._watchers.discard)
        return task

    async def post_chat_notice(self, agent: AgentRecord, payload: dict[str, Any]) -> None:
        """A society notice in the agent's own chat — proposals, routine results,
        learned skills. A no-op without a chat service or a bound session."""
        await self._notify_chat(agent, payload)

    async def _notify_chat(self, agent: AgentRecord, payload: dict[str, Any]) -> None:
        """A society notice in the agent's own chat (learned skill, login needed).

        The LEAD is the one agent whose card shows the app's own Jarvis chat
        rather than a ``society:`` session, so its notices go to the newest
        session of that surface — otherwise they would land where nobody looks.
        """
        svc = self._get_chat()
        post = getattr(svc, "post_notice", None)
        if svc is None or post is None:
            return
        session_id = agent.session_id
        if agent.agent_id == LEAD_AGENT_ID:
            try:
                seen = svc.store.list_sessions(limit=1, surface="jarvis")
            except Exception:  # noqa: BLE001 — falls back to the society session below
                log.warning("society: could not read the Dodaios chat sessions", exc_info=True)
                seen = []
            if seen:
                session_id = seen[0].session_id
        if svc.store.get_session(session_id) is None:
            return
        await post(session_id, payload)

    def cache_agent(self, agent: AgentRecord) -> None:
        self._agent_cache[agent.agent_id] = agent

    def cached_agent(self, agent_id: str) -> AgentRecord | None:
        return self._agent_cache.get(agent_id)

    def set_deliver(self, deliver: DeliverHook | None) -> None:
        """The chat binding (M2) installs the canonical-chat deliverer here."""
        self._deliver = deliver
        self.scheduler._deliver = deliver  # noqa: SLF001 — the runtime owns its scheduler

    async def seed_lead(self) -> AgentRecord:
        """The assistant is always on the roster as the one lead."""
        lead, _ = await self.roster.create(
            name=LEAD_AGENT_ROW_NAME,
            title="Lead",
            description=(
                "The voice-steered lead of the society. Delegates, never does the work itself."
            ),
            tier=Tier.LEAD,
            # The lead is Gigi, the app's own mascot (character-pipeline.md, spirit archetype).
            avatar={"contract": 1, "archetype": "spirit", "base": "gigi", "parts": {}},
        )
        return lead

    # ------------------------------------------------------------ catalog

    def catalog(self) -> list[CapabilityRow]:
        from .browser.tool import BrowserTool
        from .coding_threads import CodingThreadTool

        tools = dict(self._get_tools() or {})
        tools[BrowserTool.name] = BrowserTool(self, "", self.browser)
        tools[CodingThreadTool.name] = CodingThreadTool(self, "")
        try:
            skills = list(self._get_skills() or [])
        except Exception:  # noqa: BLE001 — a broken skill registry costs the skill rows only
            log.warning("society: skill registry unavailable for the catalog", exc_info=True)
            skills = []
        usable = self._usable_plugins()

        def connected(tool_name: str, kind: CapabilityKind) -> bool:
            # Only marketplace plugins carry a credential; everything else the
            # brain loaded is usable as-is.
            if kind is not CapabilityKind.PLUGIN or usable is None:
                return True
            return tool_name not in usable.catalog_ids or tool_name in usable.ids

        return build_catalog(tools, skills, connected=connected)

    def _usable_plugins(self) -> _UsablePlugins | None:
        """Credential state of the marketplace plugins, cached briefly: the
        catalog is read on every agent turn and each id is a keyring read."""
        import time

        now = time.monotonic()
        cached = self._usable_cache
        if cached is not None and now - cached.read_at < _USABLE_TTL_S:
            return cached
        if self._plugin_state is None:
            return None
        try:
            catalog_ids, usable_ids = self._plugin_state()
            fresh = _UsablePlugins(
                catalog_ids=frozenset(catalog_ids), ids=frozenset(usable_ids), read_at=now
            )
        except Exception:  # noqa: BLE001 — unknown state keeps every plugin connected
            log.warning("society: plugin connection state unavailable", exc_info=True)
            return None
        self._usable_cache = fresh
        return fresh

    def derive(self, title: str, description: str) -> tuple[list[str], dict[str, list[str]]]:
        """``(focus, approval_rules)`` for a title/description pair."""
        focus = derive_focus(title, description, self.catalog())
        return focus, derive_approval_rules(description, focus)

    # ------------------------------------------------------------ dispatch

    def owner_of(self, mission_id: str) -> str | None:
        return self._owners.get(mission_id)

    async def _dispatch(self, target: AgentRecord, env: SocietyEnvelope) -> str:
        """Start work under ``target``'s identity.

        Default runner is the agent's canonical chat: one turn on Jarvis' brain
        runner with the roster row's provider, model, tools and briefing, so
        per-agent customization applies in full. ``payload.runner == "mission"``
        routes to the mission stack instead (worktree isolation for heavy
        coding work; the worker then inherits the global worker configuration
        and only the prompt carries the agent's identity).
        """
        runner = str(env.payload.get("runner") or "")
        if not runner:
            runner = "chat" if self._get_chat() is not None else "mission"
        if runner == "mission":
            if reply_policy(env) != "always":
                raise RuntimeError("this reply policy requires an available agent chat service")
            return await self._dispatch_mission(target, env)
        from .team_lead import TRACE_PREFIX as TEAM_TRACE_PREFIX

        if (
            self.team_leads.group_led_by(target.agent_id) is not None
            and not env.trace_id.startswith(TEAM_TRACE_PREFIX)
        ):
            # Work handed to a team lead is a goal for its team: the lead
            # plans, assigns and answers this assignment with its report.
            return await self.team_leads.accept_assignment(target, env)
        return await self._dispatch_chat(target, env)

    def _drill_seconds(self, key: str) -> float:
        """A fault the person switched on for a drill, in seconds; ``0`` = off.

        Read from ``<data dir>/society_drill.json`` on every use, so a drill
        starts and ends without a restart and is off whenever the file is
        absent. Capped: a drill delays one start, it never hangs the society.
        """
        path = self._data_dir / _DRILL_FILE
        if not path.is_file():
            return 0.0
        try:
            import json

            value = float(json.loads(path.read_text(encoding="utf-8")).get(key) or 0)
        except (OSError, ValueError, TypeError, AttributeError):
            log.warning("society drill: %s is unreadable; no fault is injected", path)
            return 0.0
        return max(0.0, min(value, _DRILL_MAX_S))

    async def _dispatch_chat(self, target: AgentRecord, env: SocietyEnvelope) -> str:
        svc = self._get_chat()
        if svc is None:
            raise RuntimeError("agent chat service unavailable: the society cannot start work")
        from .chat_binding import ensure_session, frame_assignment

        # Work Jarvis or a teammate hands out runs in the agent's one chat; the
        # chat shows the framed assignment as a delegation card from its sender.
        sender = await self.roster.get(env.from_agent)
        sender_name = self.display_name(sender) if sender is not None else env.from_agent
        session = ensure_session(svc, self._get_cfg(), target)
        if svc.is_running(session.session_id):
            raise RuntimeError(f"target busy: {self.display_name(target)} is running a turn")
        queue = svc.subscribe(session.session_id)
        # Both API and CLI turns inherit the same trusted request provenance.
        token = incoming_context.set(
            IncomingMessage(
                message_id=env.event_id,
                sender_id=env.from_agent,
                sender_name=sender_name,
                sender_kind="jarvis" if env.from_agent == LEAD_AGENT_ID else "agent",
                text=env.text,
                prompt=frame_assignment(env, sender_name),
                trace_id=env.trace_id,
            )
        )
        try:
            turn_id = await svc.send(
                session.session_id,
                frame_assignment(env, sender_name),
                **({"read_only": True} if env.payload.get("read_only") is True else {}),
                **(
                    {"direct_user": False}
                    if getattr(svc, "supports_turn_completion", False)
                    else {}
                ),
            )
        except Exception:
            svc.unsubscribe(session.session_id, queue)
            raise
        finally:
            incoming_context.reset(token)
        hold = self._drill_seconds("slow_start_s")
        if hold:
            # A drill the person switched on (docs/agent-society/team-leads.md):
            # the turn is running, and this start now takes long enough for the
            # board to give up on it, exactly as a slow start does.
            log.warning("society drill: holding the start of %s for %.0f s", target.name, hold)
            try:
                await asyncio.sleep(hold)
            except asyncio.CancelledError:
                svc.unsubscribe(session.session_id, queue)
                raise
        run_id = f"turn:{turn_id}"
        watcher = asyncio.create_task(
            self._watch_turn(svc, session.session_id, queue, turn_id, run_id, target, env)
        )
        self._watchers.add(watcher)
        watcher.add_done_callback(self._watchers.discard)
        return run_id

    async def _watch_turn(
        self,
        svc: Any,
        session_id: str,
        queue: Any,
        turn_id: str,
        run_id: str,
        target: AgentRecord,
        env: SocietyEnvelope,
    ) -> None:
        """Turn the chat turn's end into a RESULT on the board and free the slot."""
        final_text = ""
        status = "done"
        error = ""
        tool_steps: list[str] = []
        used_browser = False
        last_seq = 0
        read_failures = 0
        gone_polls = 0
        polled = False
        quest_trace = env.trace_id.startswith("quest:")
        try:
            while True:
                if polled:
                    # A quiet poll found no terminal event. A turn whose task has
                    # ended without writing one (a runner that returned early, a
                    # failed final write) would otherwise hold this agent's slot
                    # and the lead's report forever.
                    polled = False
                    gone_polls = 0 if _turn_alive(svc, session_id) else gone_polls + 1
                    if gone_polls >= _WATCH_GONE_POLLS:
                        status = "blocked"
                        error = "The agent's turn ended without reporting a result."
                        log.warning("society: %s ended without a terminal event", run_id)
                        break
                try:
                    events = [
                        await asyncio.wait_for(queue.get(), timeout=_WATCH_EVENT_POLL_SECONDS)
                    ]
                    gone_polls = 0
                except TimeoutError:
                    # The service drops a subscriber whose queue overflows. Its
                    # events remain durable, so recover the missing terminal.
                    try:
                        events = await asyncio.to_thread(
                            svc.store.list_events, session_id, after_seq=last_seq
                        )
                        polled = True
                    except Exception:  # noqa: BLE001 - a broken chat store must release the slot
                        read_failures += 1
                        log.warning(
                            "society: durable turn recovery failed for %s (%s/3)",
                            run_id,
                            read_failures,
                            exc_info=True,
                        )
                        if read_failures < 3:
                            continue
                        status = "blocked"
                        error = "Agent result could not be recovered from chat history."
                        try:
                            await svc.cancel(session_id, expected_turn_id=turn_id)
                        except Exception:  # noqa: BLE001 - still release the board slot
                            log.warning(
                                "society: turn %s could not be cancelled after recovery failure",
                                run_id,
                                exc_info=True,
                            )
                        break
                    read_failures = 0
                else:
                    read_failures = 0
                finished = False
                for event in events:
                    seq = int(event.get("seq") or 0)
                    if seq and seq <= last_seq:
                        continue
                    last_seq = max(last_seq, seq)
                    kind = event.get("kind")
                    payload = event.get("payload") or {}
                    if payload.get("turn_id") not in (None, turn_id):
                        continue
                    if kind == "assistant_text":
                        if payload.get("media_only"):
                            continue  # A picture row does not replace the result report.
                        final_text = str(payload.get("text") or final_text)
                        if quest_trace:
                            await self.quests.note_progress(env.trace_id, "", live=final_text)
                    elif kind == "tool_call":
                        name = str(payload.get("name") or payload.get("tool") or "tool")
                        summary = str(payload.get("summary") or "")[:120]
                        step = f"{name}: {summary}" if summary else name
                        tool_steps.append(step)
                        if quest_trace:
                            await self.quests.note_progress(env.trace_id, step)
                        if name == "society_browser":
                            used_browser = True
                    elif kind == "error":
                        if payload.get("display_only"):
                            # A picture that could not be shown does not undo
                            # the work (live 2026-10-02: a finished research
                            # turn was reported as blocked over two missing
                            # screenshots).
                            log.info(
                                "society: %s turn had a display-only error: %s",
                                target.name, str(payload.get("message") or "")[:200],
                            )
                            continue
                        status, error = "blocked", str(payload.get("message") or "error")
                    elif kind == "turn_finished":
                        if payload.get("status") not in (None, "ok", "done", "completed"):
                            status = "blocked"
                            error = str(payload.get("error") or payload.get("status") or "")
                        finished = True
                        break
                if finished:
                    break
        except asyncio.CancelledError:  # Session cancellation is normal shutdown.
            return
        finally:
            svc.unsubscribe(session_id, queue)
        self.scheduler.note_run_ended(run_id)
        summary = (final_text or error or "turn finished").strip()
        # A successful model turn can still report an unfinished task. Use the
        # correlated, typed report, never a keyword guess over the final prose.
        correlated = [
            item
            for item in await self.store.events_for_trace(env.trace_id)
            if item.parent_event_id == env.event_id
            and item.from_agent == target.agent_id
            and item.to_agent == env.from_agent
        ]
        reports = [item for item in correlated if item.msg_type is MsgType.ANSWER
                   and item.payload.get("reply_status") == "blocked"]
        questions = [
            item for item in correlated if item.msg_type in (MsgType.QUERY, MsgType.PROPOSE)
        ]
        if reports:
            status = "blocked"
            error = summary = reports[-1].text
        elif questions:
            status = "blocked"
            error = summary = questions[-1].text
        elif status == "done" and not final_text.strip():
            status = "blocked"
            error = summary = "Agent finished without a result report."
        try:
            await self.store.append_and_publish(
                SocietyEnvelope(
                    msg_type=MsgType.RESULT,
                    from_agent=target.agent_id,
                    to_agent=env.from_agent if env.from_agent != "user" else None,
                    trace_id=env.trace_id,
                    parent_event_id=env.event_id,
                    payload={
                        "run_id": run_id,
                        "status": status,
                        "done": summary[:2000],
                        "output": [f"chat:{session_id}"],
                        "evidence": [],
                        "open": [] if status == "done" else [error[:500] or "turn failed"],
                        "next_owner": None,
                        "text": summary[:500],
                    },
                )
            )
        except Exception:  # noqa: BLE001 - the slot is free either way; the loss is one RESULT row
            log.warning("society: RESULT for %s could not be written", run_id, exc_info=True)
        if env.from_agent == LEAD_AGENT_ID and (reports or not questions):
            await self.report_to_lead(target, env, status=status, summary=summary)
        digest = TurnDigest(
            task=env.text or str(env.payload.get("task") or ""),
            final_text=final_text,
            tool_steps=tool_steps,
            status=status,
            origin="web" if used_browser else "agent",
        )
        if not getattr(svc, "supports_turn_completion", False):
            learner = asyncio.create_task(self._learn(target, digest))
            self._watchers.add(learner)
            learner.add_done_callback(self._watchers.discard)

    # ------------------------------------------------------------ the lead

    async def report_to_lead(
        self, target: AgentRecord, env: SocietyEnvelope, *, status: str, summary: str
    ) -> None:
        """Close the loop on a task Jarvis handed out: show the person.

        Jarvis delegates by voice or from the front-page chat and acknowledges
        at once ("Scout is on it"); the work then ends on the board, where the
        person only sees it by opening the Agents section. So the RESULT of a
        lead-assigned task returns to its original chat. Voice requests also
        enter the live conversation's floor-aware result queue. No separate
        model is called to phrase the report. A failed notice never fails the run.
        """
        if (
            env.from_agent != LEAD_AGENT_ID or env.to_agent != target.agent_id
            or not should_report(env, status)
        ):
            return
        await self._deliver_lead_result(
            target, env, status=status, summary=summary, kind="society_result",
        )

    def pick_agent(self, task: str) -> AgentRecord | None:
        """The active agent whose hands fit ``task`` best, or ``None``.

        The lead delegating without a name ("give that to the team") — and a
        realtime model that heard "Gmail agent" as "email agent" — need a
        deterministic pick: the capability ids the task points at
        (``derive_focus``) against each agent's own focus, strongest first.
        A task no agent's focus touches picks nobody; the caller then says so
        rather than guessing. Synchronous: the roster snapshot, no IO.
        """
        wanted = derive_focus("", task, self.catalog(), limit=8)
        if not wanted:
            return None
        weight = {cap_id: len(wanted) - i for i, cap_id in enumerate(wanted)}
        best: tuple[int, str, AgentRecord] | None = None
        for agent in self.roster.snapshot():
            if agent.agent_id == LEAD_AGENT_ID or str(agent.state) != "active":
                continue
            score = sum(
                weight.get(cap_id, 0) for cap_id in agent.focus if cap_id not in agent.denies
            )
            if score <= 0:
                continue
            key = (score, agent.name.casefold(), agent)
            if best is None or score > best[0] or (score == best[0] and key[1] < best[1]):
                best = key
        return best[2] if best is not None else None

    async def _learn(self, target: AgentRecord, digest: TurnDigest) -> None:
        try:
            fresh = await self.roster.get(target.agent_id)
            await self.learning.run(fresh or target, digest)
        except asyncio.CancelledError:
            raise
        except Exception:  # noqa: BLE001 - learning never breaks a finished turn
            log.warning("society learning failed for %s", target.agent_id, exc_info=True)

    async def _dispatch_mission(self, target: AgentRecord, env: SocietyEnvelope) -> str:
        manager = self._get_manager()
        if manager is None:
            raise RuntimeError("mission manager unavailable: the society cannot start work")
        task = env.text or str(env.payload.get("task", "")) or "(no task text)"
        language = env.payload.get("lang")
        kwargs: dict[str, Any] = {
            "prompt": _agent_frame(target, task, self._get_cfg()),
            "source_actor": "hauptjarvis",
        }
        if language in MISSION_LANGUAGES:
            kwargs["language"] = language
        mission_id = await manager.dispatch(**kwargs)
        self._owners[str(mission_id)] = target.agent_id
        return str(mission_id)

    # ------------------------------------------------------------ controls

    async def _cancel_active_society_chats(self) -> None:
        service = self.chat_service()
        if service is None or not callable(getattr(service, "cancel", None)):
            return
        # AgentChatService exposes is_running but not a public active-id list.
        # Snapshot its live turns; a store query could miss an older active chat.
        running = tuple(getattr(service, "_running", {}).items())
        targets: list[str] = []
        for session_id, run in running:
            session = service.store.get_session(session_id)
            if (
                session is None
                or session.surface != "society"
                or not session_id.startswith("society:")
            ):
                continue
            signal = getattr(service, "signal_cancel", None)
            if callable(signal):
                signal(session_id)
            # The kill switch can be invoked from an agent's own turn. Signal
            # it, but never await that turn from inside itself.
            if getattr(run, "task", None) is asyncio.current_task():
                continue
            targets.append(session_id)
        if not targets:
            return
        results = await asyncio.gather(
            *(service.cancel(session_id) for session_id in targets),
            return_exceptions=True,
        )
        for session_id, result in zip(targets, results, strict=True):
            if isinstance(result, BaseException):
                log.warning(
                    "society kill switch: chat %s did not stop", session_id, exc_info=result
                )

    async def engage_kill_switch(self) -> dict[str, Any]:
        await self.store.set_kill_switch(True)
        building_paused = _pause_self_build()
        halted = await self.scheduler.halt_all()
        goals_paused = await self.team_leads.halt()
        await self._cancel_active_society_chats()
        await self.browser.close()
        settled = 0
        for room in await self.rooms.list(state=RoomState.RUNNING):
            await self.rooms.settle(room.room_id, reason="kill_switch")
            settled += 1
        manager = self._get_manager()
        killed = 0
        if manager is not None and hasattr(manager, "cancel"):
            for mission_id in list(self._owners):
                try:
                    await manager.cancel(mission_id)
                    killed += 1
                except Exception:  # noqa: BLE001 — a mission already gone is fine
                    log.debug("society kill switch: mission %s not cancellable", mission_id)
        return {
            "engaged": True,
            "runs_halted": halted,
            "rooms_settled": settled,
            "missions_cancelled": killed,
            "team_goals_paused": goals_paused,
            "self_build_paused": building_paused,
        }

    async def release_kill_switch(self) -> dict[str, Any]:
        await self.store.set_kill_switch(False)
        return {"engaged": False}

    async def status(self) -> dict[str, Any]:
        agents = await self.roster.list()
        running = self.scheduler.running
        return {
            "kill_switch": await self.store.kill_switch(),
            "agents": len(agents),
            "active_runs": len(running),
            "running": running,
            "last_seq": await self.store.last_seq(),
            "rooms_running": len(await self.rooms.list(state=RoomState.RUNNING)),
            "quests_open": len(await self.quests.list(state=QuestState.OPEN))
            + len(await self.quests.list(state=QuestState.ASSIGNED))
            + len(await self.quests.list(state=QuestState.RUNNING)),
            "db_path": str(self.store.path),
            # The frontend offers the lead's team card once; this says whether
            # that offer has already been made (seeds.ONBOARDING_KEY).
            "onboarding_done": await self.store.get_meta("onboarding_done", "0") == "1",
        }

    async def say(
        self,
        *,
        from_agent: str,
        to_agent: str,
        text: str,
        trace_id: str | None = None,
        msg_type: MsgType = MsgType.SAY,
        payload: dict[str, Any] | None = None,
        parent_event_id: str | None = None,
    ) -> SocietyEnvelope:
        """Append one envelope on behalf of ``from_agent`` (REST, user, tests)."""
        body = dict(payload or {})
        body["text"] = text
        from dodaios.core.protocols import current_chat_turn

        turn = current_chat_turn.get()
        if turn is not None and turn.direct_user:
            body["reply_session_id"] = turn.session_id
        outgoing = SocietyEnvelope(
            msg_type=msg_type,
            from_agent=from_agent,
            to_agent=to_agent,
            trace_id=trace_id or f"chat:{uuid4().hex}",
            payload=body,
            parent_event_id=parent_event_id,
        )
        marked = reply_awaited_inline.get()
        if (
            marked is not None
            and not marked
            and from_agent == self.lead_id
            and msg_type is MsgType.QUERY
        ):
            # Marked before it is stored: no reply can arrive ahead of the mark.
            marked.append(outgoing.event_id)
            self._awaited_inline.add(outgoing.event_id)
        try:
            envelope = await self.store.append_and_publish(outgoing)
        except BaseException:
            # Never sent: nothing may stay marked for a reply that cannot come.
            self._awaited_inline.discard(outgoing.event_id)
            raise
        from .delegation_wait import track_request

        await track_request(self, envelope)
        return envelope

    @property
    def lead_id(self) -> str:
        return LEAD_AGENT_ID