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.

82.4 KB
Raw Blame
"""Phase-6 Bootstrap — wires all mission components at app startup.

Called by ``dodaios/ui/web/server.py::start()`` (or a standalone CLI).
Returns a dict with all instantiated components that the caller can store
in ``app.state.<key>``.

Startup order per plan §"Block D":
1. cleanup.startup_sweep
2. MissionManager + start (Recovery)
3. BudgetTracker (with emitter -> store.append_and_publish)
4. WorktreeManager (driven by cfg)
5. CriticRunner
6. MissionDecomposer (optional brain)
7. Kontrollierer (wires everything + safety_enabled)
8. ConnectionManager-Bus-Bridge — already done in Phase-4 server.py
9. MissionVoiceListener (when TTS is available)
10. daily_cleanup_task (when config.daily=true)

Each step is optional via a cfg flag. Default values come from jarvis.toml
[phase6.*] (see the section defaults there).
"""

from __future__ import annotations

import asyncio
import logging
from collections.abc import Awaitable, Callable
from pathlib import Path
from typing import Any

# Speech-bus type for the optional MissionAnnouncer (Wave-4 Y).
# A lazy import via the TYPE_CHECKING pattern would be preferred, but EventBus is
# lightweight and already imported everywhere in the project.
from dodaios.core.bus import EventBus as _SpeechEventBus

from .budget import BudgetTracker
from .capacity import (
    PAID_MISSION_CAP_USD,
    PaidCallGate,
    PaidOffer,
    WorkerCapacityUnavailable,
    estimate_paid_cost_usd,
    pinned_to_subscription,
)
from .cleanup import daily_cleanup_task, startup_sweep
from .critic.runner import CriticRunner
from .event_bus import MissionBus
from .isolation.env import build_worker_env, read_live_claude_oauth_token
from .isolation.worktree import WorktreeManager
from .kontrollierer.decomposer import MissionDecomposer
from .kontrollierer.orchestrator import Kontrollierer
from .manager import MissionManager
from .task_bridge import MissionEventBridge
from .voice.announcer import MissionAnnouncer
from .voice.listener import MissionVoiceListener
from .voice.readback import MissionReadback
from .worker_runtime.provider_map import (
    ANTIGRAVITY_SUBAGENT_SLUGS,
    CODEX_SUBAGENT_SLUGS,
    GROK_BUILD_SUBAGENT_SLUGS,
)
from .workers.api_agent_worker import ApiAgentWorker
from .workers.capabilities import (
    WorkerCapabilityInventory,
    restricted_worker_app_commands,
    restricted_worker_knowledge_tools,
)
from .workers.claude_direct_worker import ClaudeDirectWorker
from .workers.codex_direct_worker import CodexDirectWorker
from .workers.gemini_worker import GeminiWorker
from .workers.google_cli_worker import GoogleCliWorker
from .workers.grok_build_direct_worker import GrokBuildDirectWorker

logger = logging.getLogger(__name__)

# Fire-and-forget boot-time cleanup sweeps keep a strong reference here so the
# event loop does not garbage-collect them mid-run; each self-discards on
# completion. These sweeps are PURE cleanup (git worktree prune + rmtree over
# stale dirs) whose result nothing downstream consumes — awaiting them only
# delayed the desktop boot before the voice pipeline could come up.
_BOOT_BACKGROUND_TASKS: set[asyncio.Task[Any]] = set()


def _spawn_boot_cleanup(coro: Any, *, name: str) -> asyncio.Task[Any]:
    """Schedule *coro* as a tracked fire-and-forget task (no boot-path await)."""
    task = asyncio.create_task(coro, name=name)
    _BOOT_BACKGROUND_TASKS.add(task)
    task.add_done_callback(_BOOT_BACKGROUND_TASKS.discard)
    return task


# Pure-API providers that run on THEIR OWN provider via the in-process
# ApiAgentWorker (OpenAI-compatible chat API + tool-use loop), instead of the
# legacy silent ClaudeDirectWorker fallback. Single source for the routing
# decision so the UI "runs on Claude" badge can never drift from reality.
# ollama/local-openai (2026-07-25): keyless local servers, same in-process
# tool-loop path — a mission can run fully on the user's own hardware.
# vertex: Google Cloud Vertex AI runs the SAME in-process tool loop as the
# other API providers, on the VertexBrain — so picking it as the subagent
# actually runs the mission on Vertex instead of silently falling back to Claude.
_API_AGENT_SLUGS: frozenset[str] = frozenset(
    {"openai", "openrouter", "grok", "nvidia", "ollama", "local-openai", "vertex"}
)


# Type aliases
TTSSpeakFn = Callable[[str, str], Awaitable[None]]
BrainCallerFn = Callable[[str], Awaitable[str]]


def _default_job_factory() -> Any:
    """Per-mission process-containment job, selected by platform.

    Delegates to the ``job_object`` factory so the OS dispatch lives in exactly
    one place: a real Windows Job Object on win32, and a session/process-group
    reaper (SIGTERM->SIGKILL on close) on macOS/Linux. The wiring used to
    hard-code the pure no-op off-Windows, which leaked worker process trees on a
    headless VPS (cross-platform audit C2).
    """
    from .isolation.job_object import WindowsJobObject

    return WindowsJobObject()


def _resolve_readback_mode(*, tts_speak_fn: object | None, speech_bus: object | None) -> str:
    """Decide which mission voice-readback path is active — exactly one.

    Starting BOTH the MissionVoiceListener (direct-TTS callback) and the
    MissionAnnouncer (mission-bus -> speech-bus bridge) makes every
    completion spoken twice (announcer docstring: "gleichzeitig beide
    aktivieren = Doppel-Ansage" — 2026-05-27 finding #6). The announcer wins
    whenever a ``speech_bus`` is available because it feeds the
    ``scrub_for_voice`` UI/pipeline path; the listener is the fallback for
    callers that only supply a direct TTS callback.

    Returns ``"announcer"``, ``"listener"``, or ``"none"``.
    """
    if speech_bus is not None:
        return "announcer"
    if tts_speak_fn is not None:
        return "listener"
    return "none"


def _worker_mcp_relevance_filter_enabled() -> bool:
    """The ``[brain.routing].worker_mcp_relevance_filter`` kill-switch (default ON).

    Reading from the LIVE config (uncached) lets the maintainer flip the filter
    off without a code change. Any read failure degrades to ON — the safe default
    is to gate, exactly like the router's plugin-relevance gate. Never raises.
    """
    try:
        from dodaios.core.config import load_config

        cfg = load_config()
        return bool(getattr(cfg.brain.routing, "worker_mcp_relevance_filter", True))
    except Exception:  # noqa: BLE001 — missing/blip config => keep the gate ON
        return True


def _live_server_tools():  # noqa: ANN202
    """Per-server tool lists (namespaced ``<server_id>/<tool>``) from the LIVE
    MCP registry, for the relevance filter.

    Returns ``{server_id: [{"name": "<sid>/<tool>", "description": ...}, ...]}``.
    The namespace prefix is what lets ``plugin_is_relevant`` mine a server's OWN
    distinctive tool nouns (its ``_derive_tool_nouns`` keys on the ``<id>/`` prefix).

    A server that is enabled but not started has no live client → it is simply
    absent from the map → the relevance gate sees an empty tool list and matches
    on the server NAME / usage card only (the correct degraded behaviour: export
    only if the task names it). Never raises.
    """
    out: dict[str, list] = {}
    try:
        from dodaios.core.runtime_refs import get_mcp_registry

        reg = get_mcp_registry()
        if reg is None:
            return out
        for sid, client in reg.active_clients().items():
            tools: list[dict] = []
            for t in getattr(client, "_tools_cache", []) or []:
                if isinstance(t, dict):
                    name = t.get("name") or ""
                    desc = t.get("description") or ""
                else:
                    name = getattr(t, "name", "") or ""
                    desc = getattr(t, "description", "") or ""
                if name:
                    tools.append({"name": f"{sid}/{name}", "description": desc})
            out[sid] = tools
    except Exception:  # noqa: BLE001 - gate must never break mission dispatch
        logger.debug("missions: live MCP tool gather failed", exc_info=True)
        return None
    return out


def _filter_servers_by_relevance(  # noqa: ANN201
    servers,  # noqa: ANN001
    *,
    task_text=None,  # noqa: ANN001
    relevance_filter=None,  # noqa: ANN001
    server_tools=None,  # noqa: ANN001
):
    """Drop MCP servers irrelevant to this mission's task, ungated otherwise.

    Mirrors the router's plugin-relevance gate one layer below it: a worker runs
    ``--permission-mode bypassPermissions`` so an exported off-topic server is
    actually reachable and re-introduces the ~35 s wrong-MCP stall. A server is
    kept only when ``plugin_is_relevant(task_text, server_id, server_tools)`` is
    True (NAMES the server, OR a usage card matches, OR a distinctive tool-noun
    matches) — the SAME definition the router uses.

    Fail-OPEN at every layer so a gate bug can NEVER silently strip a mission's
    MCPs: no task context → full export; kill-switch OFF → full export; any
    per-server or setup fault → export that server. NO silent truncation — the
    kept/dropped server ids are logged at INFO when anything is dropped.
    """
    # No task context → we cannot judge relevance → export everything (honesty
    # over guessing; this is the back-compat path for callers without a prompt).
    if not servers or not task_text or not str(task_text).strip():
        return servers

    enabled = relevance_filter
    if enabled is None:
        enabled = _worker_mcp_relevance_filter_enabled()
    if not enabled:
        return servers  # kill-switch OFF → exact prior behaviour (full export)

    try:
        from dodaios.marketplace.plugin_relevance import plugin_is_relevant

        tool_lookup = server_tools if server_tools is not None else _live_server_tools()
        if tool_lookup is None:
            logger.warning("missions: MCP relevance evidence unavailable - full export")
            return servers
        kept: dict[str, dict] = {}
        dropped: list[str] = []
        for sid, entry in servers.items():
            tools = tool_lookup.get(sid, []) if hasattr(tool_lookup, "get") else []
            try:
                relevant = plugin_is_relevant(str(task_text), sid, tools)
            except Exception:  # noqa: BLE001 — a relevance fault must NOT strip
                relevant = True
            if relevant:
                kept[sid] = entry
            else:
                dropped.append(sid)
        if dropped:
            logger.info(
                "missions: MCP relevance filter kept %s, dropped %s (off-task)",
                sorted(kept),
                sorted(dropped),
            )
        return kept
    except Exception as exc:  # noqa: BLE001 — never break dispatch; full export
        logger.debug("missions: MCP relevance filter failed (%s) — full export", exc)
        return servers


def _assemble_worker_mcp_servers(  # noqa: ANN201
    token_store=None,  # noqa: ANN001
    mcp_json_servers=None,  # noqa: ANN001
    *,
    task_text=None,  # noqa: ANN001
    relevance_filter=None,  # noqa: ANN001
    server_tools=None,  # noqa: ANN001
):
    """Build the claude-cli ``mcpServers`` map for the delegated worker.

    Two sources, both reaching the worker identically:
      1. Connected Marketplace plugins (saved tokens + catalog mcp_server spec).
      2. Self-added MCP servers from ``mcp.json`` (the "MCPs" section), converted
         via :func:`dodaios.mcp.claude_export.mcp_json_to_claude_servers`.

    When ``task_text`` is provided, the assembled set is filtered down to the
    servers RELEVANT to that mission's task (the same plugin-relevance gate the
    router uses) — a worker runs ``bypassPermissions`` so an exported off-topic
    MCP is reachable and would re-introduce the ~35 s wrong-MCP stall. The filter
    is reversible (``relevance_filter=False`` or the ``[brain.routing].
    worker_mcp_relevance_filter`` kill-switch) and ALWAYS degrades to exporting
    on a fault, so it can never silently strip a mission's MCPs. ``server_tools``
    is an optional per-server tool map (``{id: [tool, ...]}``) for the relevance
    decision; when omitted it is gathered from the live MCP registry.

    Never raises: a marketplace / keyring / mcp.json hiccup degrades to an
    empty (or partial) map so mission dispatch is never blocked.
    """
    try:
        from dodaios.marketplace.catalog_data import load_catalog
        from dodaios.marketplace.mcp_bridge import assemble_claude_mcp_servers
        from dodaios.marketplace.token_store import TokenStore

        store = token_store if token_store is not None else TokenStore()

        # mcp.json (self-added MCP servers) -> claude-cli shape -> extra_servers
        if mcp_json_servers is None:
            try:
                from dodaios.mcp.state import load_config as _load_mcp_json

                mcp_json_servers = (_load_mcp_json() or {}).get("mcpServers", {})
            except Exception as exc:  # noqa: BLE001
                logger.warning("missions: mcp.json read failed (%s)", exc)
                mcp_json_servers = {}
        try:
            from dodaios.mcp.claude_export import mcp_json_to_claude_servers

            extra = mcp_json_to_claude_servers(mcp_json_servers)
        except Exception as exc:  # noqa: BLE001
            logger.warning("missions: mcp.json -> claude config failed (%s)", exc)
            extra = {}

        servers = assemble_claude_mcp_servers(load_catalog(), store, extra_servers=extra)
        return _filter_servers_by_relevance(
            servers,
            task_text=task_text,
            relevance_filter=relevance_filter,
            server_tools=server_tools,
        )
    except Exception as exc:  # noqa: BLE001
        logger.warning(
            "missions: MCP-config assembly failed (%s) — worker runs without "
            "plugins / mcp.json servers",
            exc,
        )
        return {}


def _assemble_worker_capability_inventory(task_text: str) -> WorkerCapabilityInventory:
    """Build the one restricted capability snapshot shared by all backends."""
    return WorkerCapabilityInventory.build(
        mcp_servers=_assemble_worker_mcp_servers(task_text=task_text),
        app_commands=restricted_worker_app_commands(),
        native_tool_names=(
            *restricted_worker_knowledge_tools(),
            *_connected_native_worker_tools(task_text),
        ),
        task_text=task_text,
    )


def _connected_native_worker_tools(task_text: str) -> tuple[str, ...]:
    """Connected, task-relevant native connector tools without credentials.

    Some Marketplace connectors (for example Gmail and Vercel) use a native
    supervisor tool instead of an MCP server.  Include only catalog-declared
    tools whose credential is present and healthy, and only when the mission
    names or semantically matches that connector.  Any store/catalog fault
    fails closed for that connector rather than granting a phantom tool.
    """
    selected = list(_custom_api_worker_tools(task_text))
    try:
        from dodaios.marketplace.catalog_data import load_catalog
        from dodaios.marketplace.plugin_relevance import plugin_is_relevant
        from dodaios.marketplace.token_store import TokenStore

        store = TokenStore()
        for plugin in load_catalog().plugins:
            native_name = str(plugin.native_tool or "").strip()
            if not native_name:
                continue
            try:
                tokens = store.load(plugin.id)
            except Exception:  # noqa: BLE001 - one broken credential stays isolated
                logger.debug(
                    "missions: connector credential unreadable for %s", plugin.id
                )
                continue
            if tokens is None or not tokens.access or tokens.needs_reauth:
                continue
            evidence = [{"name": native_name, "description": plugin.description}]
            if plugin_is_relevant(task_text, plugin.id, evidence):
                selected.append(native_name)
        return tuple(dict.fromkeys(selected))
    except Exception:  # noqa: BLE001 - capability discovery must not block missions
        logger.debug("missions: native connector discovery failed", exc_info=True)
        return tuple(selected)


def _custom_api_worker_tools(task_text: str) -> tuple[str, ...]:
    """Grant relevant native API actions through the credential-free gateway."""
    import re

    from dodaios.core.runtime_refs import get_supervisor_tool_gateway
    from dodaios.marketplace.plugin_relevance import plugin_is_relevant

    gateway = get_supervisor_tool_gateway()
    if gateway is None:
        return ()
    try:
        return tuple(
            tool.name for tool in gateway.catalog()
            if re.fullmatch(r"api_[a-f0-9]{32}_[a-z][a-z0-9_]{0,23}", tool.name)
            and tool.risk_tier != "block"
            and plugin_is_relevant(task_text, tool.name, [
                {"name": f"{tool.name}/action", "description": tool.description},
            ])
        )
    except Exception:  # noqa: BLE001 - a unavailable surface grants no extra access
        logger.debug("missions: custom API discovery failed", exc_info=True)
        return ()


def _select_subagent_worker_kind(sub_jarvis_provider: str | None, step_model: str) -> str:
    """Pure routing decision for the Heavy-Task subagent worker.

    Returns one of ``"claude_direct"`` | ``"codex_direct"`` | ``"antigravity"``
    | ``"grok_build"`` | ``"subjarvis"`` | ``"gemini"``.

    Defense-in-depth (2026-05-29, user mandate: heavy tasks run on the
    configured provider — claude-api -> Claude Max OAuth — and Gemini must
    NEVER be a silent fallback): when a subagent provider IS configured it is
    the single source of truth. A per-step ``model`` string can never divert
    heavy work to the Gemini API key — the configured provider wins. The bare
    ``gemini`` branch is reachable ONLY when no provider is configured at all,
    and the caller logs that case so a Gemini spawn is never silent.

    Note that choosing ``"gemini"`` as the *subagent provider* routes through
    the Jarvis-Agent worker (``"subjarvis"``), NOT the direct ``GeminiWorker``
    API path — the latter is purely the legacy no-provider fallback.
    """
    if sub_jarvis_provider == "claude-api":
        return "claude_direct"
    if sub_jarvis_provider == "openclaw-claude":
        return "subjarvis"
    if sub_jarvis_provider in CODEX_SUBAGENT_SLUGS:
        return "codex_direct"
    # "antigravity" (Google subscription via the official agy/gemini CLI over the
    # OAuth login) is a HARD LOCK like claude-api: no per-step model can divert it
    # to the API-key Gemini path. It reuses GeminiWorker but with the API key
    # stripped from the worker env (the OAuth login then bills the subscription).
    if sub_jarvis_provider in ANTIGRAVITY_SUBAGENT_SLUGS:
        return "antigravity"
    if sub_jarvis_provider in GROK_BUILD_SUBAGENT_SLUGS:
        return "grok_build"
    # openai / openrouter / grok / nvidia run on their own provider via the in-process
    # ApiAgentWorker (OpenAI-compatible chat API + tool-use loop writing files
    # into the worktree). They used to fall through to "subjarvis" ->
    # ClaudeDirectWorker, so picking them silently ran the mission on Claude
    # (violates the "selected provider must run" mandate). A HARD LOCK like
    # claude-api/antigravity: no per-step model can divert it.
    if sub_jarvis_provider in _API_AGENT_SLUGS:
        return "api_agent"
    # Explicitly selecting "gemini" routes to the direct GeminiWorker so the
    # sub-agent actually runs on Gemini (the user's "selected provider must run"
    # mandate). This is NOT the anti-silent-Gemini case (2026-05-29) — that
    # forbade gemini as a *silent* fallback when something else was configured;
    # here the user deliberately picked gemini. The Jarvis-Agent path that this
    # used to take ("subjarvis") was removed in Welle 4, so without this it silently
    # ran on Claude instead of Gemini.
    if sub_jarvis_provider == "gemini":
        return "gemini"
    if sub_jarvis_provider:
        return "subjarvis"
    # No subagent provider configured — legacy default path.
    if (step_model or "").lower().startswith("gemini"):
        return "gemini"
    return "subjarvis"


def subagent_runs_on_claude_fallback(sub_jarvis_provider: str | None) -> bool:
    """True when picking this subagent provider does NOT run heavy missions on
    THAT provider but silently falls back to the ClaudeDirectWorker (Opus).

    OpenAI-compatible API-only providers resolve to the ``"api_agent"`` kind
    (the in-process ApiAgentWorker runs them on their OWN provider), so they no
    longer report a Claude fallback here — provided an API key is configured. The
    only remaining always-Claude case is the legacy ``"subjarvis"`` kind
    (the legacy ``openclaw-claude`` alias / unknown provider), whose dedicated
    Jarvis-Agent worker was removed after the ~92% nested-claude hang.

    NOTE: this is the ROUTING truth, not a credential check — an api_agent
    provider with NO key still falls back to Claude at run time (``_worker_
    factory`` honest gate), which the provider card surfaces separately via its
    key-present state.

    Derived from the SINGLE routing source of truth (``_select_subagent_worker_
    kind``) so the badge can never drift from the worker that actually runs.
    """
    return _select_subagent_worker_kind(sub_jarvis_provider, "") == "subjarvis"


def _live_subagent_provider(boot_snapshot: str | None) -> str | None:
    """Re-resolve ``[brain.sub_jarvis].provider`` from the LIVE persisted config.

    The worker factory used to freeze the boot-time provider snapshot, so a
    subagent switch (UI / config / drift-guard) only took effect after an app
    restart — every mission ran the hard-coded ClaudeDirectWorker (Opus)
    fallback until then (live forensic 2026-06-21: a process booted before the
    codex pin kept routing heavy missions to Claude/Opus for hours, even though
    the persisted choice was already ``openai-codex``). Resolving per mission
    makes the running app follow the current selection without a restart.

    Two hops, both reusing tested machinery:
      1. ``refresh_persisted_env_from_user_registry()`` pulls the authoritative
         User-registry value of the persisted ``JARVIS__*`` keys (which already
         include ``JARVIS__BRAIN__SUB_JARVIS__PROVIDER``) into this process's
         ``os.environ``. Without it a stale inherited env keeps winning over the
         TOML via ``_apply_env_overrides`` (env > toml). No-op off Windows /
         when nothing changed.
      2. ``load_config()`` is uncached (re-reads TOML + env on every call), so a
         fresh read now reflects the persisted choice.

    Any failure (config blip, registry hiccup) degrades to ``boot_snapshot`` so
    a transient error can never break mission dispatch — the boot path already
    treats that snapshot as authoritative, so this is strictly safer than the
    frozen-closure behaviour it replaces.
    """
    try:
        from dodaios.core.config import (
            load_config,
            refresh_persisted_env_from_user_registry,
        )

        try:
            refresh_persisted_env_from_user_registry()
        except Exception:  # noqa: BLE001,S110 — best-effort env heal, never fatal
            pass

        cfg = load_config()
        sub_cfg = getattr(cfg.brain, "worker", None)
        raw = getattr(sub_cfg, "provider", None) if sub_cfg is not None else None
        if raw:
            resolved = str(raw).strip().lower()
            if resolved:
                return resolved
        # B6 (open-source AP-22): no explicit [brain.worker].provider → run the
        # heavy worker on the user's ACTIVE brain provider, not the legacy Claude
        # CLI. A fresh openrouter/gemini/codex install never sets sub_jarvis, so
        # without this the default ClaudeDirectWorker spawns the absent `claude`
        # binary and every mission fails.
        primary = (getattr(cfg.brain, "primary", None) or "").strip().lower()
        if primary:
            return primary
    except Exception as exc:  # noqa: BLE001
        logger.debug(
            "missions: live subagent re-resolve failed (%s) — using boot snapshot %r",
            exc,
            boot_snapshot,
        )
    return boot_snapshot


def _anthropic_key_for_cli_env(
    key: str | None, *, cli_present: bool, pinned: bool
) -> str | None:
    """The Anthropic credential a mission's ``claude`` CLI may see, or None.

    On a subscription install (``pinned``, dodaios/missions/capacity.py) with
    the CLI installed, only the subscription login's OAuth bearer may reach
    the process — worker and critic alike. A classic per-token key in
    ``ANTHROPIC_API_KEY`` would make the CLI bill it silently; paid use runs
    only on consent, in-process, never through this environment. A key-only
    install keeps its key: it is that install's primary credential (AP-22).
    """
    if key and cli_present and pinned and not key.startswith("sk-ant-oat"):
        return None
    return key


def _claude_subscription_login_state() -> bool | None:
    """The ``claude`` CLI's SUBSCRIPTION login: usable (True), proven dead this
    session (False), or absent (None).

    Surfaces 1 and 2 of :func:`_claude_cli_auth_viable` — never the classic
    Anthropic API key, which bills per token. A mission pinned to the
    subscription (dodaios/missions/capacity.py) runs Claude only on this.
    """
    from dodaios.claude_auth_state import claude_auth_dead, credential_fingerprint
    from dodaios.missions.isolation.env import (
        live_claude_oauth_status,
        read_live_claude_oauth_token,
    )

    if live_claude_oauth_status() == "valid":
        token = read_live_claude_oauth_token()
        return not claude_auth_dead(current_fingerprint=credential_fingerprint(token))

    try:
        from dodaios.claude_auth import usable_native_claude_subscription

        status = usable_native_claude_subscription()
        if status is not None:
            account_marker = ":".join(
                (
                    "native-claude-account",
                    status.binary_path,
                    status.user_email or "",
                    status.subscription_type or "",
                )
            )
            return not claude_auth_dead(
                current_fingerprint=credential_fingerprint(account_marker)
            )
    except Exception:  # noqa: BLE001,S110 — optional native auth path
        pass
    return None


def _positive_subscription_login() -> bool:
    """True when a subscription login is usable RIGHT NOW: the ``claude`` CLI's
    subscription login (never a classic key) or codex over the ChatGPT login.

    Offline: file reads and the process-cached CLI login probes. A merely
    installed CLI is not a login.
    """
    from dodaios.missions.workers.claude_direct_worker import _resolve_claude_binary

    try:
        if _resolve_claude_binary() is not None and _claude_subscription_login_state() is True:
            return True
    except Exception:  # noqa: BLE001 - an unreadable probe is "no positive login", logged
        logger.debug("missions: claude subscription login probe failed", exc_info=True)
    from dodaios.missions.workers.codex_direct_worker import _codex_oauth_available

    return bool(_codex_oauth_available())


def install_is_pinned() -> bool:
    """Whether missions on this install are pinned to subscriptions
    (dodaios/missions/capacity.py): a subscription seen connected recently
    (sticky) or a positive login probe now. Worker factory, env builder and
    critic all ask this one question."""
    return pinned_to_subscription(login_probe=_positive_subscription_login)


def _claude_cli_auth_viable() -> bool:
    """True when the ``claude`` CLI has a REACHABLE auth surface for a worker.

    Binary presence alone is NOT viability (2026-07-06 incident): the worker
    must have one of three executable auth surfaces:

    1. the process-local ``claude_auth_dead`` flag (a worker PROVED the current
       credential dead this session — fingerprinted, so a fresh login/key
       re-enables Claude instantly);
    2. a live file-backed OAuth bearer for the legacy isolated-config path, or
       a native CLI account plus the ``--safe-mode`` capability (preserves the
       macOS Keychain while disabling hooks/plugins);
    3. failing that, a classic (non-``sk-ant-oat``) Anthropic API key.

    The CLI probes are tightly timed and process-cached. A probe failure is not
    fatal: the cross-family worker resolver continues to another usable family.
    """
    from dodaios.claude_auth_state import claude_auth_dead, credential_fingerprint

    login = _claude_subscription_login_state()
    if login is not None:
        return login

    try:
        from dodaios.core.config import get_jarvis_agent_secret

        key = get_jarvis_agent_secret("claude-api")
    except Exception:  # noqa: BLE001 — unreadable secret store => not viable
        return False
    if not key or key.startswith("sk-ant-oat"):
        return False
    return not claude_auth_dead(current_fingerprint=credential_fingerprint(key))


def _api_key_family_viable(provider: str) -> bool:
    """True when *provider* has a USABLE API key for the in-process worker.

    Key EXISTENCE is not key viability (2026-07-07, mission 019f3d01 — the
    verify run of the codex-cooldown fix): the stored anthropic credential was
    a stale ``sk-ant-oat`` OAuth bearer — the copy of a login that no longer
    exists. The worker env builder deliberately DROPS that shape (guaranteed
    401) and ``_claude_cli_auth_viable`` refuses it, but the cross-family walk
    counted its mere existence as a claude-api key and dead-ended every retry
    on ApiAgentWorker('claude-api') 401s while a healthy openrouter key sat
    one slot further in the SAME loop (AP-22). Apply the one shared rule here
    too: an ``sk-ant-oat`` bearer is not an API key, and a classic key a
    worker already proved dead this session (fingerprinted) is skipped until
    it changes.
    """
    from dodaios.brain.app_control import LOCAL_PROVIDERS
    from dodaios.core.config import get_jarvis_agent_secret

    if provider in LOCAL_PROVIDERS:
        # Keyless local family (spec-declared auth_mode "none"): no credential
        # can exist, so viability is reachability — a dead server fast-fails
        # at call time (2 s connect) and the walk moves on. The quota cooldown
        # still applies when a run just proved the server down.
        from dodaios.api_family_quota_state import api_family_in_cooldown

        return not api_family_in_cooldown(provider)

    key = get_jarvis_agent_secret(provider)
    if not key:
        return False
    # A family a worker just proved quota-depleted / auth-dead is skipped
    # until its cooldown self-expires — fingerprinted, so saving a NEW key in
    # the API-Keys view lifts the block instantly (mission 019f3d0f: gemini's
    # depleted prepaid credits were re-picked on every retry, BUG-042).
    from dodaios.api_family_quota_state import api_family_in_cooldown
    from dodaios.claude_auth_state import claude_auth_dead, credential_fingerprint

    if api_family_in_cooldown(provider, current_fingerprint=credential_fingerprint(key)):
        return False
    if provider == "claude-api":
        if key.startswith("sk-ant-oat"):
            return False
        return not claude_auth_dead(current_fingerprint=credential_fingerprint(key))
    return True


def reachable_worker_families() -> list[str]:
    """Which worker families could run a heavy mission RIGHT NOW (cheap,
    offline — file reads + process-local flags, never a network probe).

    Same subscription-first order as ``_cross_family_last_resort_worker``:
    Claude Max CLI (auth-viable), codex ChatGPT OAuth, then the API-key
    families. Feeds the Sub-Agents section health so the app can warn
    BEFORE a mission is dispatched (2026-07-06: the tab stayed green for
    17 hours of guaranteed-dead spawns).
    """
    families: list[str] = []
    from dodaios.missions.workers.claude_direct_worker import _resolve_claude_binary

    if _resolve_claude_binary() is not None and _claude_cli_auth_viable():
        families.append("claude")
    from dodaios.codex_auth_state import codex_needs_reauth
    from dodaios.codex_quota_state import codex_in_quota_cooldown
    from dodaios.missions.workers.codex_direct_worker import _codex_oauth_available

    if _codex_oauth_available() and not codex_needs_reauth() and not codex_in_quota_cooldown():
        families.append("codex")
    from dodaios.missions.workers.api_agent_worker import supports_api_agent_worker

    for prov in ("claude-api", "gemini", "openrouter", "openai", "grok", "nvidia"):
        if supports_api_agent_worker(prov) and _api_key_family_viable(prov):
            families.append(prov)
    return families


def _cross_family_last_resort_worker(
    task_text: str,
    capability_inventory: WorkerCapabilityInventory | None = None,
    *,
    allow_metered: bool = True,
) -> Any | None:
    """The key-aware, cross-family LAST-resort heavy worker (open-source AP-22/23).

    The legacy last resort was always ``ClaudeDirectWorker`` — the Claude Max
    OAuth ``claude`` CLI. A downloader whose only credential is a Gemini /
    OpenRouter / OpenAI key (and who never switched ``[brain.worker].provider``
    off the ``claude-api`` default) then bricked every heavy mission: there is no
    ``claude`` binary on a fresh install and no Anthropic key. This mirrors the
    Brain's cross-family fallback chain — probe the families the user ACTUALLY
    has and run on the first reachable one, crossing families instead of
    dead-ending on Claude.

    Subscription-first ordering (no metered key before a metered key):
      1. Claude Max OAuth ``claude`` CLI, when its binary is present — this keeps
         the maintainer/subscription path unchanged (it is reached first, so a
         host WITH Claude never diverts to a metered key);
      2. ChatGPT subscription via the codex CLI OAuth login (no API key);
      3. the in-process ``ApiAgentWorker`` on whatever single API key is
         configured — ``claude-api``, ``gemini``, ``openrouter``, ``openai``, in
         the Brain chain's family order.

    Returns ``None`` ONLY when nothing is reachable (the genuine no-credential
    case); the caller then keeps the honest Claude last resort, which fails
    legibly rather than silently. Because Claude is probed first, this never
    silently diverts a working Claude to Gemini — it only rescues a host that
    has no Claude at all (the §3 single-key downloader).
    """
    # 1. Claude Max OAuth CLI — subscription, no metered key, preferred floor.
    #    Auth-aware since 2026-07-06: binary presence alone picked a claude CLI
    #    whose OAuth token had expired in place, and every mission 401'd while
    #    a healthy codex login + OpenRouter key sat unused (AP-22).
    inventory = capability_inventory or _assemble_worker_capability_inventory(task_text)

    from dodaios.missions.workers.claude_direct_worker import _resolve_claude_binary

    if _resolve_claude_binary() is not None:
        if _claude_cli_auth_viable():
            return ClaudeDirectWorker(capability_inventory=inventory)
        logger.warning(
            "Mission worker: the `claude` CLI is installed but its auth is "
            "dead/expired (no live OAuth login, no classic Anthropic key) — "
            "skipping Claude and crossing provider families. Run "
            "`claude /login` or save a fresh Anthropic key in the API-Keys "
            "view to restore Claude."
        )
    # 2. ChatGPT subscription via the codex CLI OAuth login (no API key).
    #    Quota-aware since 2026-07-07 (mission_019f3cd8-1dd4): a usage-capped
    #    plan keeps `codex status` connected=True, so login presence alone
    #    re-picked a codex that failed the cap check ~28 s into every mission
    #    while a healthy API key sat unused (AP-22). The cooldown self-expires,
    #    then codex is re-probed; a codex success clears it.
    from dodaios.codex_auth_state import codex_needs_reauth
    from dodaios.codex_quota_state import codex_in_quota_cooldown
    from dodaios.missions.workers.codex_direct_worker import _codex_oauth_available

    if _codex_oauth_available() and not codex_needs_reauth():
        if not codex_in_quota_cooldown():
            return CodexDirectWorker(capability_inventory=inventory)
        logger.warning(
            "Mission worker: the codex ChatGPT plan is in quota cooldown "
            "(usage cap hit this session) — skipping codex and crossing "
            "provider families until the cooldown expires."
        )
    # 3. In-process API worker on whatever single key the user has, crossing
    #    families — the same cross-family set the Brain fallback chain uses.
    #    Viability-gated (not existence-gated): see _api_key_family_viable.
    #    Skipped on a subscription install (``allow_metered=False``): a per-token
    #    key is billed only after the user approves it (missions/capacity.py).
    if not allow_metered:
        return None
    from dodaios.missions.workers.api_agent_worker import supports_api_agent_worker

    for prov in ("claude-api", "gemini", "openrouter", "openai", "grok", "nvidia"):
        if supports_api_agent_worker(prov) and _api_key_family_viable(prov):
            logger.warning(
                "Mission worker -> ApiAgentWorker(%r): no Claude CLI / Codex login "
                "reachable, crossing to the configured API-key family so the heavy "
                "mission runs instead of failing on the absent `claude` binary "
                "(open-source AP-22/AP-23, single-key downloader).",
                prov,
            )
            return ApiAgentWorker(prov, capability_inventory=inventory)
    return None


def _pinned_claude_worker(
    capability_inventory: WorkerCapabilityInventory | None,
    *,
    binary_present: bool,
    login: bool | None,
) -> Any:
    """The Claude worker for a mission pinned to the subscription, or a
    :class:`WorkerCapacityUnavailable` that parks the mission.

    ``login`` is :func:`_claude_subscription_login_state`. Never codex, never
    another family, never the Anthropic API key: the user approves paid use per
    mission (dodaios/missions/capacity.py).
    """
    from dodaios.claude_quota_state import claude_in_quota_cooldown

    if not binary_present:
        raise WorkerCapacityUnavailable(
            "provider_unavailable",
            "claude",
            "the claude CLI is not installed; the Anthropic API key needs approval",
        )
    if claude_in_quota_cooldown():
        raise WorkerCapacityUnavailable("provider_quota", "claude")
    if login is not True:
        raise WorkerCapacityUnavailable("provider_auth", "claude")
    return ClaudeDirectWorker(capability_inventory=capability_inventory, backend_fallback=False)


def _pinned_codex_worker(capability_inventory: WorkerCapabilityInventory | None) -> Any:
    """The codex worker for a pinned mission, or a WorkerCapacityUnavailable.

    Only over the ChatGPT login: without it codex would run on
    ``OPENAI_API_KEY``, which bills per token.
    """
    from dodaios.codex_auth_state import codex_needs_reauth
    from dodaios.codex_quota_state import codex_in_quota_cooldown
    from dodaios.missions.workers.codex_direct_worker import _codex_oauth_available

    if not _codex_oauth_available():
        raise WorkerCapacityUnavailable("provider_auth", "codex", "no ChatGPT login")
    if codex_needs_reauth():
        raise WorkerCapacityUnavailable("provider_auth", "codex")
    if codex_in_quota_cooldown():
        raise WorkerCapacityUnavailable("provider_quota", "codex")
    return CodexDirectWorker(capability_inventory=capability_inventory, backend_fallback=False)


def _pinned_claude_from_probes(capability_inventory: WorkerCapabilityInventory | None) -> Any:
    """:func:`_pinned_claude_worker` on the live binary and login probes."""
    from dodaios.missions.workers.claude_direct_worker import _resolve_claude_binary

    binary_present = _resolve_claude_binary() is not None
    login = _claude_subscription_login_state() if binary_present else None
    return _pinned_claude_worker(
        capability_inventory, binary_present=binary_present, login=login
    )


#: Subscription families a pinned mission may move between for free, in the
#: order they are tried after the configured one. Only families whose login
#: and spent-window state can be read offline (login file + the process-local
#: quota/auth flags); antigravity and grok build run when configured but are
#: never a silent fallback target, since nothing here can tell whether they
#: have capacity.
_SUBSCRIPTION_FALLBACK_ORDER: tuple[str, ...] = ("claude", "codex")
#: Builder per family, by name so the module attribute is looked up per call.
_SUBSCRIPTION_BUILDERS: dict[str, str] = {
    "claude": "_pinned_claude_from_probes",
    "codex": "_pinned_codex_worker",
}


def _subscription_worker(
    preferred: str | None,
    capability_inventory: WorkerCapabilityInventory | None,
    *,
    first_error: WorkerCapacityUnavailable | None = None,
) -> Any:
    """A worker on the configured subscription, else on another connected
    subscription (costs the user nothing extra, no approval needed).

    Raises the configured family's :class:`WorkerCapacityUnavailable` (or
    ``first_error``) when no subscription can run — the orchestrator then
    decides between paid use by consent and parking.
    """
    order = [
        f for f in (preferred, *_SUBSCRIPTION_FALLBACK_ORDER) if f in _SUBSCRIPTION_BUILDERS
    ]
    first = first_error
    for family in dict.fromkeys(order):
        try:
            builder: Callable[[WorkerCapabilityInventory | None], Any] = globals()[
                _SUBSCRIPTION_BUILDERS[family]
            ]
            worker = builder(capability_inventory)
        except WorkerCapacityUnavailable as exc:  # kept: raised below if no family can run
            if first is None:
                first = exc
            continue
        if first is not None:
            logger.warning(
                "Mission worker -> %s subscription: %s has no capacity (%s); "
                "moving to another connected subscription (no extra cost).",
                family, first.provider, first.reason,
            )
        return worker
    if first is None:  # pragma: no cover - the order is never empty
        first = WorkerCapacityUnavailable("provider_unavailable", preferred or "subscription")
    raise first


# The API-key family of the same vendor as a subscription worker: the paid
# alternative offered first for a mission parked on that subscription.
_PAID_FAMILY_FOR_SUBSCRIPTION: dict[str, str] = {
    "claude": "claude-api",
    "codex": "openai",
    "antigravity": "gemini",
    "gemini": "gemini",
    "grok-build": "grok",
}
_PAID_FAMILY_ORDER: tuple[str, ...] = (
    "claude-api", "gemini", "openrouter", "openai", "grok", "nvidia",
)


class ApiKeyPaidOption:
    """The paid alternative for a parked mission: the in-process API worker
    on one of the user's own keys. Offered, never used, until the user
    approves it for one mission (dodaios/missions/capacity.py).

    The same vendor's key comes first; a model without a known price is never
    offered, since neither its estimate nor the cost cap could be trusted.
    Reads keys and config only — never calls a provider.
    """

    def offer(
        self, *, pinned_family: str | None, open_steps: int, reason: str
    ) -> PaidOffer | None:
        from dodaios.missions.workers.api_agent_worker import (
            _resolve_worker_model,
            supports_api_agent_worker,
        )

        preferred = _PAID_FAMILY_FOR_SUBSCRIPTION.get(pinned_family or "")
        order = dict.fromkeys(p for p in (preferred, *_PAID_FAMILY_ORDER) if p)
        # A mission parked on an API key gets a DIFFERENT key, not the one
        # that just ran out.
        order.pop(pinned_family or "", None)
        for provider in order:
            if not supports_api_agent_worker(provider):
                continue
            if not _api_key_family_viable(provider):
                continue
            model = _resolve_worker_model(provider, "")
            estimate = estimate_paid_cost_usd(model, open_steps)
            if estimate is None:
                continue
            return PaidOffer(
                provider=provider,
                model=model,
                estimated_cost_usd=estimate,
                cost_cap_usd=PAID_MISSION_CAP_USD,
                reason=reason,
                open_steps=open_steps,
            )
        return None

    def worker(self, offer: PaidOffer, *, gate: PaidCallGate, task_text: str) -> Any:
        """The in-process API worker on exactly the offered provider and
        model; ``gate`` checks consent and caps before each of its calls."""
        return ApiAgentWorker(
            offer.provider,
            capability_inventory=_assemble_worker_capability_inventory(task_text),
            pinned_model=offer.model,
            paid_gate=gate,
        )


def _resolve_api_agent_worker(
    provider: str,
    task_text: str,
    capability_inventory: WorkerCapabilityInventory | None = None,
    *,
    pinned: bool = False,
) -> Any:
    """Worker for an ``api_agent``-kind Jarvis-Agent provider.

    OpenAI, OpenRouter, Grok, and NVIDIA run on their own provider through the
    in-process :class:`ApiAgentWorker`.

    Viability-gated (not existence-gated, ``_api_key_family_viable``): a bare
    key-existence check re-picked a family a worker already proved
    quota-depleted / auth-dead every single critic round instead of crossing
    to a healthy one (BUG-042 twin, AP-22). When the provider is not viable,
    tries the user's other provider families before the honest Claude last
    resort — never a guaranteed-fail worker.
    """
    inventory = capability_inventory or _assemble_worker_capability_inventory(task_text)
    try:
        has_key = _api_key_family_viable(provider)
    except Exception:  # noqa: BLE001 — any resolve failure => no usable key
        has_key = False
    if has_key:
        logger.info(
            "Mission worker -> ApiAgentWorker on %r (in-process tool-use "
            "loop over the provider's own API, writes files in the worktree).",
            provider,
        )
        return ApiAgentWorker(provider, capability_inventory=inventory)
    if pinned:
        # A subscription install never crosses to another METERED family on
        # its own (dodaios/missions/capacity.py): another connected
        # subscription is free and fine; otherwise the orchestrator decides
        # between paid use by consent and parking.
        from dodaios.api_family_quota_state import api_family_in_cooldown

        return _subscription_worker(
            None,
            inventory,
            first_error=WorkerCapacityUnavailable(
                "provider_quota" if api_family_in_cooldown(provider) else "provider_unavailable",
                provider,
            ),
        )
    logger.warning(
        "Mission worker: subagent provider %r has no API key configured, "
        "so it cannot run — trying the user's other provider families "
        "before the Claude last resort (open-source AP-22/AP-23).",
        provider,
    )
    cross = _cross_family_last_resort_worker(task_text, inventory)
    if cross is not None:
        return cross
    return ClaudeDirectWorker(capability_inventory=inventory)


def _resolve_codex_dead_login_worker(
    task_text: str,
    capability_inventory: WorkerCapabilityInventory | None = None,
) -> Any:
    """Worker to use when the codex ChatGPT login is flagged dead this session
    (``kind == "codex_direct"`` and ``codex_needs_reauth()`` is True).

    Mirrors ``_resolve_api_agent_worker`` / the claude_direct branch's Claude
    viability gates (CLI binary + auth, quota cooldown, or an Anthropic API
    key) instead of handing back an unconditional ``ClaudeDirectWorker`` —
    and crosses to another provider family when Claude itself is not
    reachable either (open-source AP-22/AP-23).
    """
    inventory = capability_inventory or _assemble_worker_capability_inventory(task_text)

    from dodaios.claude_quota_state import claude_in_quota_cooldown
    from dodaios.missions.workers.claude_direct_worker import _resolve_claude_binary

    if _resolve_claude_binary() is None and _api_key_family_viable("claude-api"):
        logger.info(
            "Mission worker -> ApiAgentWorker('claude-api'): codex login is "
            "dead and no `claude` CLI binary is present, running in-process "
            "on the Anthropic API key."
        )
        return ApiAgentWorker("claude-api", capability_inventory=inventory)
    claude_cli_ready = (
        _resolve_claude_binary() is not None
        and _claude_cli_auth_viable()
        and not claude_in_quota_cooldown()
    )
    if claude_cli_ready:
        logger.warning(
            "Mission worker -> ClaudeDirectWorker: codex ChatGPT login "
            "is flagged dead this session — running on Claude Max until "
            "`codex login` restores it (avoids the dead-provider double "
            "fallback)."
        )
        return ClaudeDirectWorker(capability_inventory=inventory)
    logger.warning(
        "Mission worker: codex login is dead and Claude is not reachable "
        "either (no CLI auth, quota cooldown, or no Anthropic key) — "
        "crossing provider families instead of a guaranteed-fail worker "
        "(open-source AP-22/AP-23)."
    )
    cross = _cross_family_last_resort_worker(task_text, inventory)
    if cross is not None:
        return cross
    return ClaudeDirectWorker(capability_inventory=inventory)


async def bootstrap_missions(
    *,
    db_path: Path,
    isolation_root: Path,
    repo_root: Path | None = None,
    bus: MissionBus | None = None,
    tts_speak_fn: TTSSpeakFn | None = None,
    brain_caller: BrainCallerFn | None = None,
    # Safety flags (from [phase6.safety])
    safety_enabled: bool = True,
    extra_blocked_globs: tuple[str, ...] = (),
    # Budget flags (from [phase6.budget])
    per_mission_usd: float = 5.0,
    daily_usd: float = 50.0,
    warn_pct: tuple[int, ...] = (50, 80),
    # When False the BudgetTracker is a no-op (no cost cap, no abort). User
    # mandate 2026-05-31 ("no budget at all"). Default True keeps the
    # cap for other installs / the cloud-first €5-VPS profile.
    budget_enabled: bool = True,
    # Voice flags (from [phase6.voice])
    voice_announce_critic_loop: bool = False,
    voice_language_default: str = "en",
    # Cleanup flags (from [phase6.cleanup])
    cleanup_days: int = 14,
    cleanup_startup_sweep: bool = True,
    cleanup_daily: bool = False,
    # Orchestrator flags (from [phase6.orchestrator])
    max_workers: int = 5,
    # Wave-4 Y: speech bus for MissionAnnouncer (Mission-Bus -> Speech-Bus bridge).
    # When None: no announcer is started — Wave-3 behaviour.
    speech_bus: _SpeechEventBus | None = None,
    # ``speech_bus`` carries milestone + boundary events to ack_brain and
    # selects the MissionAnnouncer readback path (see _resolve_readback_mode).
    # ``brain_manager_resolver`` is a reserved lazy-resolver hook (same pattern
    # as ``_resolve_mission_manager`` in dodaios/brain/factory.py); currently
    # unused by the bootstrap but kept on the signature for callers.
    brain_manager_resolver: Callable[[], Any | None] | None = None,
    # Recovery is OPT-IN and fail-closed: only the proven primary process
    # (the launcher that holds the single-instance lock) passes True.
    # Any side-process — smoke scripts, eval harnesses, --no-lock parallel
    # sessions, or any caller that forgets to set the flag — defaults to
    # False and will NOT sweep live missions to crash_recovery.
    # The launcher sets os.environ["JARVIS_PRIMARY_INSTANCE"] = "1" exactly
    # when it holds the lock, and server.py reads that to decide whether to
    # pass recover_missions=True here.
    recover_missions: bool = False,
) -> dict[str, Any]:
    """Boot the entire Phase-6 subsystem.

    Args:
        db_path: Path to missions.db (typically ``data/missions.db``).
        isolation_root: ``sub-agents-outputs/`` (mission-root container).
        repo_root: optional, used for git-worktree operations + cleanup.
        bus: optional external bus; otherwise MissionManager uses its own.
        tts_speak_fn: optional ``async fn(text, lang) -> None`` for voice readback.
            When None: no VoiceListener is started.
        brain_caller: optional ``async fn(prompt) -> str`` for the LLM decomposer.
            When None: decomposer operates in heuristic-only mode (1-step plans).
        safety_enabled: enables the PostToolUse scanner + path guard in the orchestrator.
        ... (cfg-specific flags, default values from jarvis.toml)

    Returns:
        dict with keys: manager, kontrollierer, budget, voice_listener,
        cleanup_task, sweep_stats. The caller stores these in ``app.state.<key>``.
    """
    isolation_root.mkdir(parents=True, exist_ok=True)
    db_path.parent.mkdir(parents=True, exist_ok=True)

    # 1. Startup sweep (before MissionManager — do not interfere with running worktrees)
    sweep_stats: dict[str, int] = {"scanned": 0, "removed": 0, "errors": 0}
    if cleanup_startup_sweep:
        sweep_stats = await startup_sweep(
            isolation_root=isolation_root,
            cleanup_days=cleanup_days,
            repo_root=repo_root,
        )

    # 2. MissionManager + Recovery (only the primary instance sweeps — #2)
    manager = MissionManager(db_path, bus=bus)
    recovered = await manager.start(recover=recover_missions)
    if recovered:
        logger.info("Phase-6 startup-recover: %d stale missions -> FAILED", len(recovered))
    elif not recover_missions:
        logger.info(
            "Phase-6 startup-recover skipped — secondary instance "
            "(not the single-instance-lock holder)"
        )

    # 3. BudgetTracker (emitter = store.append_and_publish so warnings persist)
    budget = BudgetTracker(
        per_mission_usd=per_mission_usd,
        daily_usd=daily_usd,
        warn_pct=warn_pct,
        emitter=manager.store.append_and_publish,
        enabled=budget_enabled,
    )
    # Auto-track WorkerDraftReady events
    budget.bind_to_event_bus(manager.bus)

    # 4. WorktreeManager
    if repo_root is None:
        repo_root = Path.cwd()
    worktree_mgr = WorktreeManager(
        repo_root=repo_root,
        outputs_root=isolation_root,
    )

    # H6 (2026-05-17 audit): one-shot boot-time sweep of leaked worktree
    # dirs that crashed/force-quit/race-blocked sessions left behind.
    # Audit-4 counted ~60 of these on disk. Best-effort, never raises;
    # `prune_and_sweep_leaked` swallows its own errors and returns a
    # telemetry dict that we log for forensics.
    # Off-loop via to_thread: the sweep is blocking work (git subprocesses +
    # rmtree over deep trees) and bootstrap runs on the event loop that
    # serves /api/health at boot — blocking it here kept the desktop window
    # from appearing (10s of the 30s-launch bug, 2026-06-10).
    # Fire-and-forget: nothing below consumes ``sweep_report`` (it is only
    # logged), and the sweep is blocking cleanup (git subprocess + rmtree over
    # deep trees). Awaiting it sat on the desktop-boot path; running it as a
    # tracked background task lets the mission stack come up immediately while
    # the leaked-worktree cleanup finishes behind the boot.
    async def _bg_worktree_sweep() -> None:
        try:
            sweep_report = await asyncio.to_thread(
                worktree_mgr.prune_and_sweep_leaked, max_age_hours=6.0
            )
            if sweep_report.get("swept_run_dirs", 0) > 0 or sweep_report.get("errors", 0) > 0:
                logger.info("worktree-sweep at bootstrap: %s", sweep_report)
        except Exception:  # noqa: BLE001
            logger.warning("worktree-sweep at bootstrap failed", exc_info=True)

    _spawn_boot_cleanup(_bg_worktree_sweep(), name="mission-boot-worktree-sweep")

    # 5. CriticRunner
    # Same containment job factory the orchestrator (Kontrollierer) uses for
    # workers below (AP-10) — a critic subprocess (claude-direct / codex-direct)
    # previously escaped every ambient job (create_worker_subprocess sets
    # CREATE_BREAKAWAY_FROM_JOB) and never got one of its own.
    critic_runner = CriticRunner(job_factory=_default_job_factory)

    # 6. MissionDecomposer
    decomposer = MissionDecomposer(brain=brain_caller)

    # Read brain primary AND sub_jarvis-provider once at bootstrap so
    # worker_factory + env_builder both make the same choice. Lazy-imported
    # so the missions module stays importable in test environments where
    # the global Jarvis config isn't loaded.
    brain_primary = "gemini"
    brain_deep_model = "sonnet"
    sub_jarvis_provider: str | None = None
    try:
        from dodaios.core.config import load_config

        cfg = load_config()
        brain_primary = (cfg.brain.primary or "claude-api").lower()
        # deep_model is the per-provider field; resolve via providers map.
        provider_cfg = (cfg.brain.providers or {}).get(brain_primary)
        if provider_cfg is not None:
            brain_deep_model = (
                getattr(provider_cfg, "deep_model", None)
                or getattr(provider_cfg, "model", None)
                or brain_deep_model
            )
        # [brain.worker] is the SOURCE OF TRUTH for the Jarvis-Agent worker
        # selection (post-Welle-4). If present and provider is set, every
        # mission step routes to the worker — regardless of brain.primary.
        sub_cfg = getattr(cfg.brain, "worker", None)
        if sub_cfg is not None:
            raw_provider = getattr(sub_cfg, "provider", None)
            if raw_provider:
                sub_jarvis_provider = str(raw_provider).strip().lower() or None
    except Exception as exc:  # noqa: BLE001
        logger.warning(
            "missions: brain config lookup failed (%s) — defaulting to "
            "jarvis-agent-backed worker routing",
            exc,
        )

    # B6 (open-source AP-22): no explicit sub-agent provider → default to the
    # active brain provider so the boot snapshot, env_builder, and the per-mission
    # _live_subagent_provider all agree (and never silently route to the Claude CLI).
    if not sub_jarvis_provider:
        sub_jarvis_provider = brain_primary

    # 7. Kontrollierer
    def _env_builder(mission_dir: Path) -> dict[str, str]:
        # Each worker CLI reads its own API-key env
        # var. Pull all three from Jarvis' secret store (Windows Credential
        # Manager → ENV → .env) so a config-driven worker switch doesn't
        # require a separate bootstrap pass. The relevant key actually
        # reaches the worker because build_worker_env sets ANTHROPIC_,
        # GEMINI_/GOOGLE_, OPENAI_API_KEY explicitly — none of them leak
        # to a worker that doesn't need them.
        anthropic_key: str | None = None
        openai_key: str | None = None
        gemini_key: str | None = None
        xai_key: str | None = None
        openrouter_key: str | None = None
        live_provider = _live_subagent_provider(sub_jarvis_provider)
        try:
            from dodaios.core.config import get_jarvis_agent_secret, get_secret

            # Resolve the provider LIVE here too, so the injected key matches the
            # worker the factory will actually pick (both read the same current
            # persisted choice instead of the frozen boot snapshot).
            if live_provider in {"claude", "claude-api"}:
                anthropic_key = get_jarvis_agent_secret("claude-api")
            # Codex-as-subagent API-key path: prefer the dedicated Codex key slot
            # so OPENAI_API_KEY carries it (the OAuth path strips the key anyway —
            # see CodexDirectWorker._build_codex_env). Other subagents use the
            # general OpenAI key unchanged.
            if live_provider in CODEX_SUBAGENT_SLUGS:
                openai_key = get_secret(
                    "codex_openai_api_key", env_fallback="CODEX_OPENAI_API_KEY"
                )
            elif live_provider == "openai":
                openai_key = get_jarvis_agent_secret("openai")
            # GoogleCliWorker strips this key before the subscription/OAuth agy
            # path, but needs it to cross to Gemini API billing when no OAuth
            # login exists. Suppressing it here made key-only Antigravity look
            # selectable and then fail at execution time.
            # On a subscription install (dodaios/missions/capacity.py) that
            # cross-over to Gemini API billing is an automatic paid switch, so
            # the antigravity worker gets no key there: without its OAuth login
            # it fails honestly instead of billing the key unapproved.
            if live_provider in {"gemini", "google"} or (
                live_provider == "antigravity" and not install_is_pinned()
            ):
                gemini_key = get_jarvis_agent_secret("gemini")
            # Grok / xAI: Jarvis stores under ``grok_api_key`` in the
            # credential manager (ENV fallback ``GROK_API_KEY``); we set
            # both XAI_API_KEY + GROK_API_KEY on the worker side so
            # Jarvis-Agent (XAI_API_KEY) and any legacy SDK (GROK_API_KEY)
            # both find it.
            if live_provider in {"grok", "xai"}:
                xai_key = get_jarvis_agent_secret("grok")
            if live_provider == "openrouter":
                openrouter_key = get_jarvis_agent_secret("openrouter")
        except Exception as exc:  # noqa: BLE001
            logger.warning(
                "missions: secret lookup failed (%s) — worker will hit authentication_failed",
                exc,
            )

        # Subscription-first billing for Claude (mirror of Codex's "OAuth wins,
        # drop the API key"): a LIVE Claude Max OAuth login in
        # ~/.claude/.credentials.json bills the plan's included usage, so it wins
        # over a stored Anthropic API key — the key is the fallback only when no
        # subscription login is present. (Was API-key-first, which silently
        # metered a user who had both a Claude Max login AND an API key.)
        #
        # Prefer the LIVE file token: `claude` refreshes its access token in
        # place, but get_secret may return a STALE oat from the credential
        # manager / .env; pinned to an isolated CLAUDE_CONFIG_DIR the env token is
        # the only auth surface and a stale one 401s. A classic API key
        # (sk-ant-api03) is used verbatim when there is no live OAuth login.
        live_oat = (
            read_live_claude_oauth_token()
            if live_provider in {"claude", "claude-api"}
            else None
        )
        if live_oat:
            anthropic_key = live_oat
        elif live_provider in {"claude", "claude-api"}:
            # Current macOS Claude Code stores the subscription in Keychain,
            # so no bearer file exists to inject. When the CLI confirms that
            # native login and supports auth-preserving safe mode, do not let a
            # separately stored API key override subscription billing via the
            # ANTHROPIC_API_KEY environment variable.
            try:
                from dodaios.claude_auth import usable_native_claude_subscription

                if usable_native_claude_subscription() is not None:
                    anthropic_key = None
            except Exception:  # noqa: BLE001,S110 — optional native auth path
                pass
        if not live_oat and anthropic_key and anthropic_key.startswith("sk-ant-oat"):
            # 2026-07-06: no live (non-expired) OAuth login, and the stored
            # credential is itself an OAuth bearer — i.e. a STALE copy of a
            # login that no longer exists. Injecting it is a guaranteed 401
            # ("Failed to authenticate. API Error: 401 Invalid authentication
            # credentials", missions 019f36e5 + 019f38b1). Drop it so the
            # worker either runs on a different family (the factory's
            # viability gate) or fails with the honest "Not logged in".
            anthropic_key = None

        if live_provider in {"claude", "claude-api"}:
            from dodaios.missions.workers.claude_direct_worker import (
                _resolve_claude_binary,
            )

            cli_present = _resolve_claude_binary() is not None
            anthropic_key = _anthropic_key_for_cli_env(
                anthropic_key,
                cli_present=cli_present,
                pinned=cli_present and install_is_pinned(),
            )

        return build_worker_env(
            run_dir=mission_dir,
            anthropic_api_key=anthropic_key,
            openai_api_key=openai_key,
            gemini_api_key=gemini_key,
            xai_api_key=xai_key,
            openrouter_api_key=openrouter_key,
        )

    def _worker_factory(step):  # noqa: ANN001 - Step type local
        task_text = getattr(step, "prompt", "") or ""
        capability_inventory = _assemble_worker_capability_inventory(task_text)
        # Worker routing post-Welle-4:
        #
        # 1. If ``[brain.sub_jarvis].provider`` is set in jarvis.toml,
        #    every mission step routes to SubJarvisWorker (which drives
        #    the provider-agnostic Jarvis-Agent CLI). This is the documented
        #    Jarvis-Agent-bridge migration path and the way the user switches
        #    between grok / gemini / openai / claude-api / openrouter as
        #    the Heavy-Worker provider without code changes.
        #
        # 2. Otherwise use SubJarvisWorker as the default heavy worker.
        #    That keeps complex work on the provider-agnostic Jarvis-Agent path
        #    instead of spawning a vendor-specific code CLI.
        # BUG-023 fix (2026-05-16): the external openclaw worker CLI 2026.5.7
        # silently swallows `cliBackends["claude-cli"].args` injection, so
        # Sonnet via Jarvis-Agent never gets file_write tools (verified live
        # in mission_019e3236).
        # When the configured provider is `claude-api`, bypass Jarvis-Agent and
        # drive the `claude` CLI directly — that path was empirically
        # proven to actually invoke Write tools (see /tmp/probe5 + /tmp/probe6
        # on 2026-05-16). Other providers (grok / gemini / openai / openrouter)
        # still go through SubJarvisWorker / Jarvis-Agent because Jarvis-Agent
        # is the right surface for them.
        # Welle 7 (2026-05-20): two opt-in routes coexist for the claude-cli
        # backend.
        #   - "claude-api": direct claude CLI via ClaudeDirectWorker
        #     (BUG-023-era shortcut, retained for back-compat).
        #   - "openclaw-claude": real Jarvis-Agent subprocess (`openclaw agent
        #     --local --json --model claude-cli/<model>`, the external worker
        #     binary). Empirically verified 2026-05-20 via a local probe
        #     directory: file write succeeded once SubJarvisWorker.spawn sets
        #     agents.defaults.workspace to the per-mission worktree. The
        #     SubJarvisWorker resolves "openclaw-claude" to the claude-api
        #     Jarvis-Agent provider via _resolve_provider_chain's
        #     primary_provider remap below.
        # Welle 6 (2026-05-18): user switched from Claude Max to ChatGPT
        # subscription. ``chatgpt`` / ``openai-codex`` route through the
        # codex CLI's ChatGPT-OAuth path -- no API key, no Jarvis-Agent, just
        # `codex exec --json --skip-git-repo-check ...`. Both slug names
        # are accepted so a future jarvis.toml renames don't break boot.
        #
        # The (provider, step_model) -> worker-kind decision is a pure,
        # unit-tested function (``_select_subagent_worker_kind``) so the
        # worker that runs can never drift from the configured provider —
        # in particular a configured ``claude-api`` is a HARD LOCK that no
        # per-step model can divert to the Gemini API key (anti-silent-Gemini
        # defense-in-depth, 2026-05-29).
        # Re-resolve the subagent provider from the LIVE persisted config on
        # every mission, instead of the frozen boot snapshot. A switch to Codex
        # then takes effect on the next mission without an app restart — the
        # 2026-06-21 incident was a process that booted before the codex pin and
        # kept routing every heavy mission to the ClaudeDirectWorker (Opus)
        # fallback for hours. Degrades to the boot snapshot on any read failure.
        live_provider = _live_subagent_provider(sub_jarvis_provider)
        kind = _select_subagent_worker_kind(live_provider, getattr(step, "model", "") or "")
        if kind == "claude_direct":
            from dodaios.missions.workers.claude_direct_worker import (
                _resolve_claude_binary,
            )

            # Capacity policy (dodaios/missions/capacity.py): on a subscription
            # install (sticky subscription signal or a positive login probe —
            # NOT merely an installed CLI) the mission runs on Claude's
            # subscription login, else on another connected subscription; with
            # none it never falls to the Anthropic API key here — the
            # orchestrator decides between consented paid use and parking.
            if install_is_pinned():
                return _subscription_worker("claude", capability_inventory)
            # B3 (open-source AP-22): an Anthropic-API-key-only user has NO `claude`
            # CLI binary — run the heavy worker IN-PROCESS via ApiAgentWorker on the
            # API key instead of failing on the missing binary. The CLI stays
            # preferred (subscription-first) whenever the binary IS present.
            if _resolve_claude_binary() is None and _api_key_family_viable("claude-api"):
                logger.info(
                    "Mission worker -> ApiAgentWorker('claude-api'): no `claude` CLI "
                    "binary, running in-process on the Anthropic API key."
                )
                return ApiAgentWorker("claude-api", capability_inventory=capability_inventory)
            # Proactive quota routing (mirror of the codex_needs_reauth branch
            # below): if a Claude worker already proved the Max window exhausted
            # this session, route STRAIGHT to codex (a separate ChatGPT
            # subscription) instead of wasting a ~16 s Claude probe per mission
            # until the window resets. The cooldown self-expires, then Claude is
            # re-probed; a Claude success clears it. Guarded on codex being a
            # viable backend (oauth present, not flagged dead).
            from dodaios.claude_quota_state import claude_in_quota_cooldown

            if claude_in_quota_cooldown():
                from dodaios.codex_auth_state import codex_needs_reauth
                from dodaios.codex_quota_state import codex_in_quota_cooldown
                from dodaios.missions.workers.codex_direct_worker import (
                    _codex_oauth_available,
                )

                if (
                    _codex_oauth_available()
                    and not codex_needs_reauth()
                    and not codex_in_quota_cooldown()
                ):
                    logger.warning(
                        "Mission worker -> CodexDirectWorker: Claude Max is in "
                        "quota cooldown this session — routing to codex until the "
                        "window resets (avoids a wasted Claude probe per mission)."
                    )
                    return CodexDirectWorker(capability_inventory=capability_inventory)
            # Open-source AP-22/AP-23: before the honest Claude last resort, try
            # the user's ACTUAL provider family. A fresh install whose only key is
            # gemini/openrouter/openai (and who never moved off the claude-api
            # default) has neither the `claude` binary nor an Anthropic key, so a
            # bare ClaudeDirectWorker here would brick the mission. The helper
            # probes Claude FIRST, so a host WITH Claude is unchanged.
            cross = _cross_family_last_resort_worker(task_text, capability_inventory)
            if cross is not None:
                return cross
            # Give the delegated worker the connected marketplace plugins as a
            # claude-cli MCP config so it can issue the plugin tool calls (AD-OE4).
            return ClaudeDirectWorker(capability_inventory=capability_inventory)
        if kind == "codex_direct":
            # The ChatGPT login is a subscription: pinned like Claude above,
            # with the free move to the Claude subscription restored.
            if install_is_pinned():
                return _subscription_worker("codex", capability_inventory)
            # If a codex subprocess already proved the ChatGPT login dead this
            # session, skip codex entirely and run on Claude Max directly (one
            # path, like grok) — re-spawning the dead provider + double-falling-
            # back every mission doubled the Claude Max load and made the critic
            # flaky (critic_loop_exhausted). Cleared on a codex success / login.
            from dodaios.codex_auth_state import codex_needs_reauth

            if codex_needs_reauth():
                # Mirror of the claude_direct branch above (open-source
                # AP-22/AP-23): a dead codex login must not hand back an
                # unconditional ClaudeDirectWorker — see
                # `_resolve_codex_dead_login_worker`.
                return _resolve_codex_dead_login_worker(task_text, capability_inventory)
            return CodexDirectWorker(capability_inventory=capability_inventory)
        if kind == "antigravity":
            # "antigravity" (Google subscription): drive the official `agy` CLI
            # over a PTY with --dangerously-skip-permissions so it can write files
            # in the worktree. The worker env has the Gemini API key stripped (see
            # the env builder), so the CLI uses the ~/.gemini OAuth login and bills
            # the subscription. GoogleCliWorker falls back to GeminiWorker when the
            # resolver finds the Gemini CLI instead of agy (it writes to a pipe; agy
            # emits 0 bytes over a pipe and needs the PTY). The previous code reused
            # GeminiWorker here, which drove `gemini` with gemini flags and never
            # invoked agy at all (the gemini consumer-OAuth was sunset 2026-06-18).
            logger.info(
                "Mission worker -> GoogleCliWorker over the Google subscription "
                "(agy over PTY, OAuth login, no API key) — billed against Antigravity."
            )
            return GoogleCliWorker(capability_inventory=capability_inventory)
        if kind == "grok_build":
            logger.info(
                "Mission worker -> GrokBuildDirectWorker over the SuperGrok "
                "subscription (grok -p, OAuth login, no API key)."
            )
            return GrokBuildDirectWorker(capability_inventory=capability_inventory)
        if kind == "api_agent":
            # openai / openrouter / grok / nvidia: run on the selected
            # provider via the in-process ApiAgentWorker — see
            # `_resolve_api_agent_worker` (viability-gated, cross-family
            # fallback, honest Claude last resort).
            provider = live_provider or ""
            return _resolve_api_agent_worker(
                provider,
                task_text,
                capability_inventory,
                pinned=install_is_pinned(),
            )
        if kind == "gemini":
            # B4 (open-source AP-22): no Gemini CLI but a Gemini API key → run the
            # heavy worker IN-PROCESS via ApiAgentWorker instead of failing on the
            # missing npm `gemini` CLI binary.
            import shutil

            from dodaios.core.config import get_jarvis_agent_secret

            if not (shutil.which("gemini") or shutil.which("gemini.cmd")) and get_jarvis_agent_secret(
                "gemini"
            ):
                logger.info(
                    "Mission worker -> ApiAgentWorker('gemini'): no Gemini CLI, "
                    "running in-process on the Gemini API key."
                )
                return ApiAgentWorker("gemini", capability_inventory=capability_inventory)
            # Reached when [brain.sub_jarvis].provider == "gemini" was selected
            # (the user's "selected provider must run" mandate) OR, legacy, when
            # no provider is configured but the step model is a gemini model.
            # Make it LOUD either way — this runs on the Gemini API key, NOT the
            # Claude Max subscription (so a key/quota issue is the user's to fix).
            logger.warning(
                "Mission worker -> GeminiWorker (step model=%r) — running on the "
                "Gemini API key (GEMINI_API_KEY/GOOGLE_API_KEY), NOT the Claude "
                "Max subscription.",
                getattr(step, "model", ""),
            )
            return GeminiWorker(capability_inventory=capability_inventory)
        # The legacy ``"subjarvis"`` kind (the legacy ``openclaw-claude`` alias /
        # unknown provider / unset default) routed to the Jarvis-Agent
        # subprocess worker, which was removed (it caused the ~92%
        # nested-claude hang).
        # Open-source AP-22/AP-23: try the user's ACTUAL provider family before
        # the Claude last resort, so an openrouter/gemini/openai-only downloader
        # is not dead-ended on the absent `claude` binary. A subscription
        # install never lands on a per-token key this way (missions/capacity.py).
        cross = _cross_family_last_resort_worker(
            task_text,
            capability_inventory,
            allow_metered=not install_is_pinned(),
        )
        if cross is not None:
            return cross
        return ClaudeDirectWorker(capability_inventory=capability_inventory)

    kontrollierer = Kontrollierer(
        manager=manager,
        decomposer=decomposer,
        critic_runner=critic_runner,
        worktree_mgr=worktree_mgr,
        env_builder=_env_builder,
        budget=budget,
        worker_factory=_worker_factory,
        job_factory=_default_job_factory,
        isolation_root=isolation_root,
        max_workers=max_workers,
        safety_enabled=safety_enabled,
        extra_blocked_globs=extra_blocked_globs,
        paid_option=ApiKeyPaidOption(),
    )

    # 8. VoiceListener / Announcer — mutually exclusive (2026-05-27 finding
    # #6): exactly one readback path runs, else every completion is spoken
    # twice. The announcer wins when a speech_bus is present (production),
    # the listener is the direct-TTS fallback.
    _readback_mode = _resolve_readback_mode(tts_speak_fn=tts_speak_fn, speech_bus=speech_bus)

    # The spoken line is the mission's own signed summary or a fixed status
    # phrase — no extra model call rephrases it (2026-09-30: the flash
    # composer billed an API key for every background result). Inside a live
    # call the realtime model already words the announcement itself.
    voice_listener: MissionVoiceListener | None = None
    if _readback_mode == "listener":
        voice_listener = MissionVoiceListener(
            bus=manager.bus,
            store=manager.store,
            readback=MissionReadback(),
            tts_speak_fn=tts_speak_fn,
            announce_critic_loop=voice_announce_critic_loop,
            language_default=voice_language_default,  # type: ignore[arg-type]
        )
        await voice_listener.start()
        logger.info("Phase-6 voice listener active (direct-TTS readback)")
    elif _readback_mode == "announcer" and tts_speak_fn is not None:
        logger.info(
            "Phase-6 voice listener suppressed — speech_bus present, "
            "MissionAnnouncer owns readback (avoids double announcement)"
        )
    else:
        logger.info("Phase-6 voice listener disabled (no tts_speak_fn provided)")

    # 8b. MissionAnnouncer (Wave-4 Y): Mission-Bus -> Speech-Bus bridge for
    # AnnouncementRequested events. Activates only when a speech bus is provided
    # (typically the global UI/pipeline bus). Without this bridge, mission-completion
    # events never reach the scrub_for_voice path.
    mission_announcer: MissionAnnouncer | None = None
    if _readback_mode == "announcer":
        mission_announcer = MissionAnnouncer(
            bus=manager.bus,
            store=manager.store,
            speech_bus=speech_bus,
            announce_critic_loop=voice_announce_critic_loop,
            language_default=voice_language_default,  # type: ignore[arg-type]
        )
        await mission_announcer.start()
        logger.info("Phase-6 mission-announcer active (mission-bus -> speech-bus)")
    else:
        logger.info("Phase-6 mission-announcer disabled (no speech_bus provided)")

    # 8c. MissionEventBridge: Mission-Bus -> global-bus MissionCompleted signal
    # that drives the When-Then Tasks rules (on_event triggers). Independent of
    # the announcer (different event class — no double announcement). Activates
    # whenever a global bus is present (speech_bus IS the global EventBus the
    # Tasks scheduler binds to). The bridge only emits a machine-readable signal;
    # it never speaks.
    mission_event_bridge: MissionEventBridge | None = None
    if speech_bus is not None:
        mission_event_bridge = MissionEventBridge(
            bus=manager.bus,
            global_bus=speech_bus,
        )
        await mission_event_bridge.start()
        logger.info("Phase-6 mission-event-bridge active (mission-bus -> global MissionCompleted)")
    else:
        logger.info("Phase-6 mission-event-bridge disabled (no global bus provided)")

    # 9. Daily cleanup task (opt-in)
    cleanup_task: asyncio.Task[None] | None = None
    if cleanup_daily:
        cleanup_task = asyncio.create_task(
            daily_cleanup_task(
                isolation_root=isolation_root,
                cleanup_days=cleanup_days,
                repo_root=repo_root,
            ),
            name="phase6-daily-cleanup",
        )
        logger.info("Phase-6 daily-cleanup-task scheduled")

    return {
        "manager": manager,
        "kontrollierer": kontrollierer,
        "budget": budget,
        "voice_listener": voice_listener,
        "mission_announcer": mission_announcer,
        "mission_event_bridge": mission_event_bridge,
        "cleanup_task": cleanup_task,
        "sweep_stats": sweep_stats,
        "recovered_mission_ids": recovered,
        "decomposer": decomposer,
        "worktree_manager": worktree_mgr,
    }


async def shutdown_missions(bootstrap_result: dict[str, Any]) -> None:
    """Clean shutdown of the Phase-6 stack.

    Cancels the cleanup task and closes the MissionManager (DB).
    """
    cleanup_task = bootstrap_result.get("cleanup_task")
    if cleanup_task is not None:
        cleanup_task.cancel()
        try:
            await cleanup_task
        except asyncio.CancelledError:
            pass

    bridge = bootstrap_result.get("mission_event_bridge")
    if bridge is not None:
        bridge.stop()

    announcer = bootstrap_result.get("mission_announcer")
    if announcer is not None:
        announcer.stop()

    manager = bootstrap_result.get("manager")
    if manager is not None:
        await manager.stop()


__all__ = ["bootstrap_missions", "shutdown_missions"]