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.

103 KB
Raw Blame
"""Brain factory: delivers a `BrainCallback` (async (str) -> str) for the pipeline.

The factory is the only authorised entry point for Phase-1b launchers
(`speech/pipeline.py` + `speech/watchdog.py`). It attempts in order:

1. **BrainManager** (Phase 5.5, tier-aware) — Router tier (Haiku) or sub tier (Opus).
2. **GeminiTestBrain** — Phase-1b fallback if BrainManager is missing/crashed.
3. **Echo** — last resort so the pipeline does not die completely.

The factory is therefore **drop-in-compatible**: regardless of which brain level
loads, the pipeline always receives something that can `async def __call__(text) -> str`.
"""
from __future__ import annotations

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

log = logging.getLogger(__name__)

BrainCallback = Callable[[str], Awaitable[str]]

# Router-tier: pure-dispatcher set (grown via documented ADR-0011 amendments;
# the exact-match regression test pins the current membership) plus three
# self-mod tools (Phase 7.3, registered separately in the loader). See
# ``router.py:SYSTEM_PROMPT`` and ADR-0011 (including the Phase-7/8 amendment
# + Wave-4 amendment ``spawn-sub-jarvis`` -> ``spawn-worker``) and
# Master-Plan §22 / Persona-Mandate Phase 3.
#
# Baseline after the 2026-07-13 cleanup: run-shell, screen-snapshot, and
# spawn-worker. The legacy dispatch-to-harness, multi-spawn, and
# dispatch-with-review paths are deliberately not model-visible because each
# duplicated or bypassed the supervised Mission Manager lifecycle.
#
# REMOVED 2026-06-28 — ``dispatch-to-harness`` is intentionally NOT a
# LLM-visible router tool. Its raw ``harness`` parameter let the brain request
# a sub-agent vehicle by NAME (``harness="openclaw"``), but that value is not a
# registered harness (Wave-4 removal, ~92% hang). The operational harness
# inventory now contains only python-script and the capability-gated screenshot
# adapter. A "start a
# subagent" turn then dispatched to a phantom harness and surfaced the raw
# "Harness 'openclaw' nicht verfügbar" KeyError to voice.  # i18n-allow
# Heavy Jarvis-Agent work is ``spawn-worker`` (Mission Manager → worker);
# live desktop work
# is ``computer-use``. The tool class itself still exists for the INTERNAL,
# non-LLM local-action fast path (see ``_load_local_action_tools``, called
# programmatically with harness="screenshot"); it is just not router-selectable.
# Do NOT re-add it here — that resurrects the phantom-harness routing bug.
#
# Rationale: Hauptjarvis is a pure dispatcher. Direct actions outside this
# list (open_app, type_text, remember, whoami …) are delegated to a background
# worker — the router delegates them via ``spawn_worker``. Read-only lookups
# (search-web, wiki-recall) and safe-gated direct actions
# (computer-use, cli-tools, plugin-tools) are router-tier by design — see the
# ADR-0011 amendments (2026-05-24 CLI, 2026-05-29 Computer-Use, 2026-06-01
# plugins, 2026-06-10 inline web search).
# This prevents the spawn-reflex behaviour documented in
# ``docs/persona-research.md`` Section 2 and keeps the tool set deterministic.
ROUTER_TOOLS = frozenset({
    "run-shell",
    "screen-snapshot",
    # NB: ``dispatch-to-harness`` deliberately absent (removed 2026-06-28) —
    # see the header comment above. Heavy work → spawn-worker; desktop →
    # computer-use. The tool remains for the internal local-action fast path.
    "spawn-worker",
    # AI Pointer (pull path): resolve the on-screen element under the mouse
    # cursor via the OS accessibility tree. Read-only, safe-tier; the brain
    # calls it on deictic questions ("what is this?"). A direct safe-gated read,
    # never a spawn — never in a worker set (AP-5/AP-14). See
    # docs/plans/ai-pointer/DESIGN.md.
    "inspect-pointer",
    # UI navigation (2026-06-02): switch the active sidebar section by voice/chat
    # ("zeig die Socials", "open settings"). Publishes NavigateSidebar; the
    # frontend listener moves the UI. Pure UI action, risk safe, NO spawn —
    # never in a worker set (AP-5/AP-14). See ADR-0011 amendment "Navigate tool".
    "navigate",
    # On-demand visualisation (2026-08-11): draw what is under discussion as a
    # On-demand artifact (2026-08-23, rebuilt from the 2026-08-11 visualize
    # tool): build ONE self-contained HTML page — dashboard, report, diagram,
    # small tool — through the mission stack on the strongest model, archived
    # as the run's deliverable and shown full-size in the Artifacts section.
    # Router-tier dispatch (risk monitor, like spawn-worker) — never in a
    # worker set (AP-5/AP-14).
    #
    # ASK-ONLY, and enforced structurally rather than by prompt: the tool is
    # removed from the tool set on every turn whose utterance does not
    # explicitly ask for an artifact (BrainManager
    # ._hide_artifact_tool_without_request over dodaios/brain/artifact_gate).
    # Membership here is what makes it REACHABLE; the gate decides WHEN.
    "create-artifact",
    # Command Registry executor (2026-07-09): run ONE curated app command
    # (dodaios/commands/registry.py) through the SAME REST endpoint the UI
    # uses, in-process via ASGI transport. Enum-constrained command_id +
    # schema-validated args; dangerous commands escalate to risk "ask"
    # (two-turn voice confirm). Direct gated action, never a spawn — never in
    # a worker set (AP-5/AP-14). See ADR-0011 amendment "app-command tool".
    "app-command",
    # Every app action (2026-09-29): search the app's own REST surface and
    # run ONE operation in-process, each call tiered by the person's
    # Jarvis-actions policy (allow / ask / block, else the action default).
    # Secrets, sign-ins and the policy itself are never in the catalog.
    # Direct gated action, never a spawn — never in a worker set
    # (AP-5/AP-14). See ADR-0011 amendment "Every app action".
    "find-app-action",
    "run-app-action",
    # Agent society (2026-09-02): the voice front door of the user's named
    # agents. ``delegate-to-agent`` appends ONE ASSIGN envelope to the
    # society board and acknowledges inside the voice budget; the society
    # scheduler (trusted Python) decides whether work starts - the tool
    # itself never spawns (risk monitor, like spawn-worker; never in a
    # worker set, AP-5/AP-14). ``society-status`` reads the roster and the
    # last events - no model call, risk safe. See ADR-0011 amendment
    # "Agent society voice tools".
    "delegate-to-agent",
    "society-status",
    "message-agent",
    # Skills-Brain-Integration: Brain-callable executor for installed user
    # skills. D9-recursion-protection is structural — SkillRunner is constructed
    # without a tool_registry that would re-expose run-skill recursively.
    # Available to BOTH Router-Tier (here) and in Wave 4: bypasses the
    # Jarvis-Agent worker because the worker itself has no skill layer.
    "run-skill",
    # Skill authoring by voice/chat (2026-08-18): the brain writes a NEW skill
    # from the user's description — one bounded brain call through the
    # SkillCreatorService ladder, committed as ``state: draft`` (AP-15, the
    # user activates it in the Skills view). Direct gated action (monitor: an
    # inactive file, instantly deletable), never a spawn — never in a worker
    # tool set (AP-5/AP-14). Replaces the phantom ``spawn-skill-author`` (see
    # dodaios/brain/tools/skill_authoring.py) with a tool the entry-point
    # loader CAN construct: it resolves registry + brain lazily at execute
    # time. Live reason: the 2026-08-18 17:51 voice turn "erstell mir einen
    # neuen Skill …" had no authoring tool at all and died on `jarvisctl
    # --help` rounds. See ADR-0011 amendment "create-skill router tool".
    "create-skill",
    # Personal memory vault (ADR-0044): search beyond the always-on memory
    # block, and erase a memory when the user asks. Router-tier only.
    "memory-search",
    "memory-forget",
    # Phase B5 (recall-tool): read-only keyword search over the long-term
    # Obsidian wiki vault. Router-tier only — never in SUB_TOOLS (AP-D9).
    # The brain calls this when the user asks "what do we know about X" or
    # references a past project, person, or decision by name.
    "wiki-recall",
    # Phase B5 follow-up: full-page reader for the wiki vault. Used after
    # wiki-recall when the brain has narrowed to one page and needs the
    # complete content, not the 240-char snippet.
    "wiki-page-read",
    # Grounded vault listing (2026-07-14): deterministic ground-truth answer
    # for "what is in my wiki" in ONE round. Without it the brain probed
    # blindly (index.md/SOUL.md → not found, ~14 rounds, 66 s) and recited
    # schema.md's example layout as actual content. Read-only and safe;
    # Jarvis-Agents may call it only through the ADR-0025 supervisor broker,
    # never through a legacy worker tier (AP-5/AP-14). See ADR-0011.
    "wiki-list",
    # Phase B5 follow-up: deterministic ingest path. Lets the brain
    # explicitly store a fact ("merk dir: …") rather than relying on the
    # VoiceFactBridge acknowledgement heuristic.
    "wiki-ingest",
    # CLI-Integration (2026-05-24): virtual loader that expands to one
    # ``cli_<name>`` tool per connected & usable CLI (gcloud, gh, docker, …).
    # This is the MCP/plugin model for command-line tools: only connected
    # CLIs become tools, so the router's tool surface stays small (typically
    # 1-5). The loader resolves the SHARED, bus-connected registry, so
    # connecting a CLI in the UI re-expands the live brain via
    # BrainToolsChanged (no restart). Router-tier only — a ``cli_<name>``
    # tool is a direct safe-gated action, never a recursive spawn, so it does
    # not enter any worker tool-set (AP-5/AP-14). See ADR-0011 amendment
    # "CLI-Integration" + docs/superpowers/specs/2026-05-24-cli-integration-design.md.
    "cli-tools",
    # Marketplace plugins as live brain tools (2026-06-01). Virtual loader,
    # mirror of cli-tools: expands to one MCPToolAdapter per connected plugin
    # tool. Direct safe/risk-gated action, NEVER a spawn — must not enter any
    # worker tool-set (AP-5/AP-14). See docs/.../2026-06-01-live-plugin-tools.md.
    "plugin-tools",
    # MCP servers as live brain tools (2026-06-18). Virtual loader that
    # expands to one MCPToolAdapter per tool of every connected and running
    # MCP server (e.g. notebooklm-mcp, filesystem-mcp). Reads
    # client._tools_cache synchronously — no network I/O. Default risk_tier
    # "monitor". Live-refresh via BrainToolsChanged when a server
    # connects/disconnects. Router-tier only — never a spawn, so it never
    # enters any worker tool-set (AP-5/AP-14). See ADR-0011 amendment
    # "MCP-Tools Virtual Loader".
    "mcp-tools",
    # Gmail Marketplace plugin: native REST tool backed by the marketplace
    # OAuth token. Gmail has no MCP server block, so it must be router-visible
    # directly; otherwise connected Gmail is not callable by voice/chat.
    "gmail",
    # Vercel Marketplace plugin (2026-06-07): native REST tool, same rationale
    # as gmail — Vercel's catalog rest_wrapper transport produced zero MCP tools,
    # so it must be router-visible directly. Read-only; never a spawn (AP-5/AP-14).
    "vercel",
    # Home Assistant Marketplace plugin (2026-07-25): native REST tool, same
    # rationale as gmail — no usable MCP surface, so it must be router-visible
    # directly or a connected smart home is not callable by voice. A direct
    # gated action (risk_tier "ask"), never a spawn (AP-5/AP-14).
    "home_assistant",
    # Google Calendar Marketplace plugin (2026-06-27): native bridge tool whose
    # bot logic is a Node script (calendar_bot.mjs). Same rationale as gmail — no
    # MCP server block, so it must be router-visible directly; otherwise a
    # connected calendar is not callable by voice/chat. Never a spawn (AP-5/AP-14).
    "google_calendar",
    # Google Drive Marketplace plugin (2026-07-23): native REST tool. Replaces
    # Google's hosted Drive MCP (drivemcp.googleapis.com), which 403s every
    # data-plane call for consumer @gmail.com accounts (Workspace Developer
    # Preview). No MCP server block anymore, so it must be router-visible
    # directly; otherwise a connected Drive is not callable by voice/chat. Never
    # a spawn (AP-5/AP-14).
    "google_drive",
    # Spotify Marketplace plugin (2026-08-17): native REST tool, same rationale
    # as gmail — Spotify publishes no MCP server at all, so it must be
    # router-visible directly; otherwise connected Spotify is not callable by
    # voice, which is the entire point of a music plugin. risk_tier "monitor":
    # starting music is audible and instantly undone. Never a spawn (AP-5/AP-14).
    "spotify",
    # YouTube Music Marketplace plugin (2026-08-18): native REST tool over the
    # official YouTube Data API v3 plus the OS media session — Google publishes
    # no YouTube Music API and no MCP server, so it must be router-visible
    # directly; otherwise a connected YouTube Music is not callable by voice.
    # risk_tier "monitor": audible and instantly undone. Never a spawn (AP-5/AP-14).
    "youtube_music",
    # Slack Marketplace plugin (2026-10-05): native REST tool over the Slack Web
    # API. Slack's hosted MCP server admits only Marketplace-listed or internal
    # apps, so the plugin carries no MCP server block and must be router-visible
    # directly. Reads are "safe"; post_message keeps "ask" (echo-confirm).
    # Never a spawn (AP-5/AP-14).
    "slack",
    # Computer-Use (Wave 1, 2026-05-29): first-class, clearly-described tool to
    # drive the user's LIVE desktop (open apps, click, type, scroll, operate
    # any GUI). The router previously had no honest desktop path — spawn-worker
    # runs in an isolated worktree (cannot touch the desktop) and the
    # dispatch-to-harness indirection was never described as desktop control, so
    # the model refused or hallucinated a tool for the German input
    # "öffne ein Terminal".  # i18n-allow
    # ("open a terminal"). This tool delegates to the in-process
    # computer-use harness; it is a direct
    # safe-gated action (per-action risk gating inside the loop, ADR-0008),
    # NOT a spawn — so it never enters a worker tool-set (AP-5/AP-14). See
    # ADR-0011 amendment "Computer-Use Router Tool".
    "computer-use",
    # Profile-write (2026-05-30): deterministic brain-driven writer for the
    # structured USER.md profile (the 5 clusters the Knowledge matrix + the
    # per-turn system prompt read). The legacy background Curator that used to
    # auto-write those clusters is soft-disabled (B4, 2026-05-17); the active
    # WikiCurator only writes free-form wiki prose. This tool closes that gap
    # WITHOUT resurrecting a parallel extractor — it persists a fact only when
    # the brain consciously calls it (the wiki-ingest precedent, monitor-tier,
    # direct safe-gated write, never a spawn → never in a worker set,
    # AP-5/AP-14). See ADR-0011 amendment "Profile-Write Router Tool".
    "update-profile",
    # App-Control (2026-05-31): give the brain a complete overview of the
    # Desktop App and let it change settings/providers/MCP by voice/chat.
    # `describe-app-settings` is read-only (safe); `switch-provider` and
    # `manage-mcp-server` are ask-tier (echo-confirm). All three are direct,
    # safe/ask-gated actions — NEVER a spawn, so they never enter a worker set
    # (AP-5/AP-14). Raw secret values are never accepted (AP-2): switch-provider
    # only flips the active provider, manage-mcp-server uses $SECRET placeholders.
    # See ADR-0011 amendment "App-Control Tools".
    "describe-app-settings",
    "switch-provider",
    "manage-mcp-server",
    # Masked key preview (2026-05-31, user mandate): speak first 3 + last 3 chars
    # of a stored API key ("AIz...xQ2"), never the full value. monitor-tier
    # (logged, no confirmation nag). Read-only, returns only 6 chars — a narrow,
    # safe exception to AP-2; the full-key refusal is a router-prompt rule.
    "reveal-key-preview",
    # Chunk B jarvis-contacts (2026-06-02): three contact-action tools that let
    # the brain act on a person by name. contact-lookup (safe, read-only)
    # resolves a name/alias -> e-mail/phone/address; contact-upsert (monitor,
    # deterministic write) saves a contact by voice ("merk dir Christophs
    # Nummer …"); call-contact (ask, echo-confirm before dialing a real person)
    # places a real outbound call via the telephony engine. All three are
    # direct safe/monitor/ask-gated actions, NEVER a spawn — so they never enter
    # a worker tool-set (AP-5/AP-14). The contact tools degrade gracefully when
    # Chunk A's ContactStore / Chunk C's telephony engine is absent (cloud-first
    # no-op). See ADR-0011 amendment "Contacts Tools".
    "contact-lookup",
    "contact-upsert",
    "call-contact",
    # Inline web search (2026-06-10, user mandate): answer news/knowledge/
    # research QUESTIONS inline instead of spawning a multi-minute worker
    # mission for a single lookup. The previous "research -> spawn_worker"
    # doctrine turned "what's in the news?" into a heavy mission (live
    # complaint 2026-06-10). Read-only DuckDuckGo call, risk safe, a direct
    # safe-gated action — never a spawn, so it never enters a worker tool-set
    # (AP-5/AP-14). See ADR-0011 amendment "Inline web search".
    "search-web",
})

# Phase 7.3 — self-mod tools are registered directly in the router loader in
# addition to the persona-mandate set (no entry_points, no spawn trigger).
# Plan-§AD-2: router tier only.
SELF_MOD_TOOL_NAMES_ROUTER = frozenset({
    "list_mutable_settings",
    "get_config_value",
    "set_config_value",
})


def warn_if_phantom_worker_harness(config: Any, harness_manager: Any) -> bool:
    """Log a warning when ``[harness.jarvis_agent].enabled`` is true but unregistered.

    The legacy ``openclaw`` harness was removed in Welle 4 and has no
    entry-point, so an ``enabled = true`` block is INERT (config honesty,
    2026-06-28). This probe is advisory only: it never raises, never changes
    routing, and "start a subagent" routes to ``spawn_worker`` regardless.
    Returns True when a phantom config was detected (consumed by the
    regression guard in tests).

    The config field was renamed from ``harness.openclaw`` to ``harness.jarvis_agent``
    in the 2026-06-29 Jarvis-Agents rename; both TOML keys are accepted via
    AliasChoices in HarnessConfig. The harness-availability slug string "openclaw"
    is left unchanged because the external openclaw binary keeps its name.
    """
    # Field renamed openclaw → jarvis_agent; back-compat: also check old attribute
    # name in case a partially-upgraded in-memory config is passed.
    oc = getattr(getattr(config, "harness", None), "jarvis_agent", None)
    if oc is None:
        oc = getattr(getattr(config, "harness", None), "openclaw", None)
    if oc is None or not getattr(oc, "enabled", False):
        return False
    try:
        available = harness_manager.available()
    except Exception:  # noqa: BLE001 — an advisory probe must never break boot
        return False
    # The harness registration slug is still "openclaw" (external binary keeps its
    # name); if it ever gets registered, the warning becomes a no-op.
    if "openclaw" in available:
        return False
    log.warning(
        "[harness.jarvis_agent].enabled is true but 'openclaw' is not a registered "
        "harness (available: %s) — the block is inert. Heavy agent work runs "
        "through spawn_worker; set [harness.jarvis_agent].enabled = false to silence "
        "this.",
        available,
    )
    return True


def _per_turn_vision_active(vision_cfg: Any) -> bool:
    """True when ``[brain.router.vision]`` requests the per-turn screenshot feed.

    This is the always-on latency tax (a screenshot injected into EVERY router
    turn). Off by default since the Wave-2 latency fix.
    """
    return vision_cfg is not None and bool(getattr(vision_cfg, "enabled", False))


def _needs_vision_engine(*, per_turn_vision: bool, cu_enabled: bool) -> bool:
    """True when a ``VisionEngine`` must be built.

    The engine is shared by two consumers: (a) the per-turn screenshot injector
    (``_vision_provider``) and (b) Computer-Use's on-demand capture. Build it
    whenever EITHER needs it — so turning the per-turn feed OFF for speed does
    NOT also disable Computer-Use ("klick auf X"). Decouples the two, which were
    previously gated on the single ``[brain.router.vision].enabled`` flag.
    """
    return per_turn_vision or cu_enabled


def _resolve_wiki_vault_root(config: Any) -> Path:
    """Resolve the wiki vault root for the router-tier context injector.

    Reads ``config.wiki_integration.vault_root`` — the SAME field every
    other wiki consumer uses (``wiki_recall._build_search_instance``,
    ``wiki_routes._resolve_vault_root``) — and resolves it through the
    canonical :func:`dodaios.memory.wiki.vault_root.resolve_vault_root`
    (spec A7), so a relative root anchors to the repo root, never the
    process CWD. Falls back to the resolver's standard
    ``<project>/wiki/obsidian-vault`` default when the config has no
    ``wiki_integration`` section (older config) or its value is empty.

    Historical bug: this previously read ``config.memory.vault_root``,
    a field that never existed on ``MemoryConfig`` — so it always
    resolved to ``None`` and a user's ``[wiki_integration].vault_root``
    was silently ignored on the voice path.
    """
    from dodaios.memory.wiki.vault_root import resolve_vault_root

    raw = getattr(getattr(config, "wiki_integration", None), "vault_root", None)
    if raw is not None and str(raw).strip() == "":
        raw = None
    return resolve_vault_root(raw).path


def _load_tools_for_tier(
    tier: str,
    *,
    bus: Any,
    executor: Any,
    harness_manager: Any,
    user_profile: Any,
    people: Any,
    config: Any,
    mission_manager: Any = None,
    contacts: Any = None,
) -> dict[str, Any]:
    """Load all tools for the given tier and instantiate them.

    Wave-4 migration: previously there was a Sub-Jarvis tier with its own
    SUB_TOOLS set + SubJarvisManager. After the Jarvis-Agent-bridge migration
    (see docs/jarvis-agents-bridge.md §11) only ``"router"`` remains as a tier;
    the heavy worker runs as an external subprocess via the Mission-Manager.

    Encapsulates entry-point discovery + special cases (dispatch-to-harness,
    spawn-worker, whoami).

    Args:
        tier: currently only ``"router"``.
        mission_manager: MissionManager instance for ``spawn_worker``.
            When None, the tool is removed from the set.
    """
    from dodaios.core.entry_points import entry_points

    if tier != "router":
        raise ValueError(
            f"Unknown tier {tier!r}. The former sub-agent tier was replaced by the "
            f"agent bridge in Welle 4 — only 'router' remains."
        )

    allow = ROUTER_TOOLS
    tools: dict[str, Any] = {}
    # ``app-command`` and the other virtual loaders can expand to a name that
    # is also provided by a purpose-built native entry point.  Entry-point
    # iteration order is not a contract, so plain ``tools[name] = tool`` made
    # the winner environment-dependent (notably Command Registry
    # ``wiki-ingest`` versus the native lazy-curator WikiIngestTool).  Track
    # provenance and make the precedence explicit: native > virtual; ties are
    # resolved by stable source name.
    tool_sources: dict[str, tuple[bool, str]] = {}

    def register_tool(tool: Any, *, source: str, virtual: bool) -> None:
        name = str(getattr(tool, "name", "") or "").strip()
        if not name:
            log.warning("Tool from %s has no name and was skipped", source)
            return
        candidate = (not virtual, source)
        existing = tool_sources.get(name)
        if existing is not None:
            candidate_wins = candidate[0] and not existing[0]
            if candidate[0] == existing[0]:
                candidate_wins = candidate[1] < existing[1]
            if not candidate_wins:
                log.info(
                    "Tool name collision for %r: keeping %s %r over %s %r",
                    name,
                    "native" if existing[0] else "virtual",
                    existing[1],
                    "native" if candidate[0] else "virtual",
                    candidate[1],
                )
                return
            log.info(
                "Tool name collision for %r: replacing %s %r with %s %r",
                name,
                "native" if existing[0] else "virtual",
                existing[1],
                "native" if candidate[0] else "virtual",
                candidate[1],
            )
        tools[name] = tool
        tool_sources[name] = candidate

    for ep in entry_points(group="jarvis.tool"):
        if ep.name not in allow:
            continue
        try:
            cls = ep.load()
            if ep.name == "spawn-worker":
                # Lazy-Resolver-Pattern: register the tool unconditionally and
                # let it resolve the MissionManager at execute-time. Without
                # this the Brain would freeze the tool dict at build-time, and
                # the post-bootstrap ``set_mission_manager`` call would have
                # no effect on an already-built BrainManager. See
                # docs/jarvis-agents-bridge.md AD-OC1 + the regression in
                # tests/integration/test_worker_lazy_bootstrap.py.
                #
                # The Kontrollierer-Resolver mirrors the manager-resolver:
                # without it the voice path would only persist a PENDING
                # mission and never trigger run_mission, leaving the user
                # in silence (BUG-016 — voice silent after spawn_worker).
                #
                # The announcer composes the spoken spawn confirmation
                # (brain spoken_ack → flash-LLM → bilingual fallback pool);
                # build_spawn_announcer never raises and never returns None.
                inst = cls(
                    bus=bus,
                    manager=mission_manager,
                    manager_resolver=_resolve_mission_manager,
                    kontrollierer_resolver=_resolve_kontrollierer,
                    announcer=build_spawn_announcer(config),
                )
            elif ep.name in ("delegate-to-agent", "society-status", "message-agent"):
                # Agent society (2026-09-02): same lazy-resolver pattern as
                # spawn-worker - the society runtime is built by the server
                # on first use, after the brain exists.
                inst = cls(runtime_resolver=_resolve_society_runtime)
            elif ep.name == "computer-use":
                # Wave 1: wraps the harness-dispatch plumbing with a fixed
                # computer-use harness identity (see computer_use_tool.py).
                #
                # The mission ceiling comes from [computer_use].mission_timeout_s
                # (audit AU-07): without it every voice/chat-triggered desktop
                # mission ran under the tool's own fallback and no user could
                # change it. ``None`` (config absent, e.g. a minimal test config)
                # keeps the tool's fallback.
                inst = cls(
                    bus=bus,
                    manager=harness_manager,
                    max_output_chars=config.harness.max_output_chars,
                    timeout_s=getattr(
                        getattr(config, "computer_use", None),
                        "mission_timeout_s",
                        None,
                    ),
                )
            elif ep.name in ("verify-via-curl", "verify-localhost"):
                inst = cls()
            elif ep.name == "start-preview-server":
                inst = cls(bus=bus)
            elif ep.name == "navigate":
                # UI navigation: publishes NavigateSidebar on the shared bus,
                # which the WS forwarder streams to the frontend (event_name
                # "NavigateSidebar") to switch the active section.
                inst = cls(bus=bus)
            elif ep.name == "create-artifact":
                # The artifact is written by a mission worker (strongest model),
                # so the tool needs the same lazy mission-stack resolvers as
                # spawn-worker (AD-OC1: the stack bootstraps after the brain).
                # Publishes NavigateSidebar("visualization") on dispatch so the
                # Artifacts section shows the build as it happens.
                #
                # The executor and the router's tool set (read lazily — the
                # dict is still being filled here) let the tool read the user's
                # mail / calendar plugins itself before it composes the brief,
                # so a page about the user's own data is built from facts the
                # harness fetched, not from what a worker with no account
                # access imagines (forensic 2026-08-27, mission 01a0426e-8d79).
                inst = cls(
                    bus=bus,
                    manager=mission_manager,
                    manager_resolver=_resolve_mission_manager,
                    kontrollierer_resolver=_resolve_kontrollierer,
                    executor=executor,
                    tools_resolver=lambda: tools,
                )
            elif ep.name == "whoami":
                inst = cls(profile=user_profile, people=people)
            elif ep.name == "wiki-recall":
                # Phase B5: build VaultSearch with the configured vault root.
                # The search instance is created once per brain build and
                # caches file-list + mtime for fast repeated calls.
                # Falls back to Path("wiki/obsidian-vault") when
                # cfg.wiki_integration.vault_root is absent (Agent A defines
                # that config field; if it is not yet merged we use the
                # default so the tool surface stays stable).
                from dodaios.plugins.tool.wiki_recall import _build_search_instance

                inst = cls(search=_build_search_instance())
            elif ep.name == "wiki-page-read":
                # Phase B5 follow-up: same vault-root resolution as wiki-recall.
                from dodaios.plugins.tool.wiki_page_read import _build_page_read_tool

                inst = _build_page_read_tool()
            elif ep.name == "wiki-list":
                # Grounded vault listing: same vault-root resolution as the
                # other wiki tools.
                from dodaios.plugins.tool.wiki_list import _build_wiki_list_tool

                inst = _build_wiki_list_tool()
            elif ep.name == "wiki-ingest":
                # Phase B5 follow-up: lazy curator resolver — the curator is
                # constructed by ``bootstrap_wiki_integration`` after the brain
                # is built, so the tool must defer the lookup to execute time.
                # Mirrors the spawn-worker lazy-resolver pattern.
                from dodaios.memory.wiki.integration import get_running_curator
                from dodaios.plugins.tool.wiki_ingest import WikiIngestTool

                inst = WikiIngestTool(curator_resolver=get_running_curator)
            elif ep.name == "create-skill":
                # Skill authoring by voice/chat: the tool resolves the live
                # SkillRegistry (skill_context) and the live BrainManager
                # (runtime_refs) at execute time — both are set AFTER the
                # brain is built — so it loads unconditionally and the tool
                # surface stays stable. `bus` lets the writer publish
                # SkillCreated for the live Skills view; `config` feeds the
                # brain resolvers when the manager is not reachable yet.
                inst = cls(bus=bus, config=config)
            elif ep.name == "update-profile":
                # Profile-write tool: mutate the SAME live UserProfile instance
                # the BrainManager renders from (factory passes one instance to
                # both this loader and the manager — see lines ~438/592/636), so
                # the next turn's system prompt reflects the change immediately;
                # emit ProfileUpdated on `bus` for live UI sync. Loads even when
                # user_profile is None — execute() returns a clean error then, so
                # the tool surface stays stable across sessions (mirrors
                # wiki-ingest).
                inst = cls(profile_resolver=lambda: user_profile, bus=bus)
            elif ep.name in ("contact-lookup", "contact-upsert", "call-contact"):
                # Chunk B (jarvis-contacts): all three consume Contract 1
                # (ContactStore) via a lazy resolver. The store is built once in
                # _phase2_full_brain and passed in via `contacts`; it is None
                # until Chunk A merges (or if the store fails to build) — the
                # tools then return a clean "contacts unavailable" error rather
                # than disappearing from the schema mid-session (stable tool
                # surface, mirrors wiki-ingest). call-contact
                # additionally lazy-loads Contract 2 (place_call) + the telephony
                # config at execute time, degrading to a clear English no-op when
                # the [telephony] extra / Chunk C is absent.
                inst = cls(store_resolver=lambda: contacts)
            else:
                inst = cls()

            if getattr(inst, "is_virtual_loader", False):
                try:
                    expanded = inst.expand()
                except Exception as exc:  # noqa: BLE001
                    log.debug("virtual-loader '%s' expand() failed: %s", ep.name, exc)
                    continue
                for tool in expanded:
                    register_tool(tool, source=ep.name, virtual=True)
            else:
                register_tool(inst, source=ep.name, virtual=False)
        except Exception as exc:  # noqa: BLE001
            log.debug("Tool %s not loadable: %s", ep.name, exc)

    # Phase 7.3 — self-mod tools are not discoverable via entry_points
    # (they require a shared state writer + PendingMutationStore). Plan-§AD-2:
    # router tier only; Sub-Jarvis does NOT receive them.
    if tier == "router":
        try:
            from dodaios.brain.tools import build_self_mod_tools

            # Pass the EventBus so the writer dispatches ConfigReloaded on a
            # SAFE-tier write (e.g. voice "switch to English"): the BrainManager
            # hot-reload subscriber then applies it to the NEXT turn with no
            # restart. Without the bus the change lands on disk but stays dormant
            # until restart — the exact symptom self-mod "doesn't work".
            #
            # auto_apply="all" (Wave 1.3): the brain-driven (voice/chat) config
            # path applies every non-forbidden change immediately, no confirm
            # round-trip ("never ask, always now"). REST/CLI keep their own
            # confirm UX (they build their store on the default "safe_only").
            self_mod_tools = build_self_mod_tools(
                writer_kwargs={"bus": bus}, auto_apply="all"
            )
            for name, inst in self_mod_tools.items():
                tools[name] = inst
        except Exception as exc:  # noqa: BLE001 — defensive, no tool block fail-stops the Brain
            log.debug("Self-mod tools not loadable (Phase 7.3): %s", exc)

    return tools


def _load_local_action_tools(
    *,
    bus: Any,
    harness_manager: Any,
    config: Any,
) -> dict[str, Any]:
    """Load hidden tools for the deterministic local-action fast path."""
    from dodaios.plugins.tool.dispatch_to_harness import DispatchToHarnessTool
    from dodaios.plugins.tool.hotkey import HotkeyTool
    from dodaios.plugins.tool.open_app import OpenAppTool
    from dodaios.plugins.tool.reset_orb_position import ResetOrbPositionTool
    from dodaios.plugins.tool.type_text import TypeTextTool

    return {
        "open_app": OpenAppTool(),
        "type_text": TypeTextTool(),
        "hotkey": HotkeyTool(),
        "dispatch_to_harness": DispatchToHarnessTool(
            bus=bus,
            manager=harness_manager,
            max_output_chars=config.harness.max_output_chars,
        ),
        # ADR-0016 L2: voice-driven orb recovery
        # ("Orb zurück" /  # i18n-allow
        # "wo bist du" / "reset orb"). Publishes OrbResetRequested
        # on the bus; the orb-side bridge handles the Tk-thread dispatch.
        "reset_orb_position": ResetOrbPositionTool(bus=bus),
    }


def _build_contact_store() -> Any:
    """Build the ContactStore (Contract 1, owned by Chunk A) or return None.

    Chunk B is the integrator: it codes against the frozen Contract-1 interface
    and degrades gracefully when Chunk A is not merged. Mirrors the
    WikiContextInjector import guard in ``_phase2_full_brain``: an ``ImportError``
    (module not merged) or any constructor mismatch yields ``None``, so the
    contact tools return a clean "contacts unavailable" error and the
    ``## Contacts`` name-index block is simply omitted from the system prompt —
    never a boot crash (cloud-first €5-VPS doctrine).
    """
    try:
        from dodaios.contacts.store import ContactStore  # type: ignore[import]
    except Exception as exc:  # noqa: BLE001 — Chunk A not merged yet is expected
        log.debug("ContactStore unavailable (Chunk A not merged?): %s", exc)
        return None
    try:
        return ContactStore()
    except Exception as exc:  # noqa: BLE001 — constructor mismatch must not crash boot
        log.warning("ContactStore could not be built: %s", exc)
        return None


_SOCIETY_FACTORY_REF: list[Any] = []


def set_society_factory(factory: Any) -> None:
    """Register the server's society-runtime factory (see server.py)."""
    _SOCIETY_FACTORY_REF[:] = [factory]


def _resolve_society_runtime() -> Any:
    """Resolve the agent-society runtime for the voice tools (AD-OC1).

    The runtime the server already built wins; otherwise the registered
    factory builds it on this first use. ``None`` means the server has not
    registered a factory yet - the tools answer with an honest 'not ready'.
    """
    from dodaios.society.runtime import current_runtime

    runtime = current_runtime()
    if runtime is not None:
        return runtime
    if not _SOCIETY_FACTORY_REF:
        return None
    return _SOCIETY_FACTORY_REF[0]()


async def prepare_society_context() -> None:
    """Warm the existing team on first conversation use, outside app boot.

    The server factory returns its one instance even while initialization is
    in flight. The runtime's lock serializes concurrent voice/chat first turns.
    Unavailable storage must never prevent an ordinary conversation.
    """
    try:
        runtime = _resolve_society_runtime()
        if runtime is not None:
            await runtime.prepare_context()
    except Exception:  # noqa: BLE001 - optional team cannot prevent conversation
        log.warning("society context initialization failed", exc_info=True)


def _resolve_mission_manager() -> Any:
    """Resolve the MissionManager for the ``spawn_worker`` tool.

    Wave-4 migration: previously the ``SubJarvisManager`` was constructed
    directly in the ``_phase2_full_brain`` flow. Today (Jarvis-Agent bridge) the
    server layer (``dodaios/ui/web/server.py::_init_mission_stack``) bootstraps
    the MissionManager asynchronously — it lives under ``app.state.mission_manager``.

    AD-OC1 (Lazy-Resolver): this function is passed as a closure into
    ``SpawnWorkerTool`` and queried at execute-time, NOT at Brain-build
    time. Required because the DesktopApp builds the BrainManager BEFORE
    ``server.start()`` (which runs ``_init_mission_stack`` and calls
    ``set_mission_manager``). A None return now means "not yet bootstrapped",
    not "permanently unavailable" — the tool surface stays registered, the
    user gets an honest "Mission-Manager initialisiert noch" reply on early
    spawns instead of silent fall-through.
    """
    return _MISSION_MANAGER_REF[0] if _MISSION_MANAGER_REF else None


def _resolve_kontrollierer() -> Any:
    """Resolves the Kontrollierer (mission orchestrator) for ``spawn_worker``.

    Mirrors ``_resolve_mission_manager`` — same lazy-resolver pattern,
    same bootstrap-order rationale. Without this the voice path would
    only ``manager.dispatch()`` (which persists a PENDING mission) but
    never trigger ``kontrollierer.run_mission()``, so the mission would
    sit untouched until the next app restart marked it as
    ``OrchestratorCrash`` via the recovery sweep.

    A ``None`` return is honest: the bootstrap hasn't completed yet.
    The caller logs and skips the run-trigger; the mission will then be
    picked up by the recovery path or a manual ``/missions/{id}/run``.
    """
    return _KONTROLLIERER_REF[0] if _KONTROLLIERER_REF else None


_MISSION_MANAGER_REF: list[Any] = []
_KONTROLLIERER_REF: list[Any] = []
# Sentinel that distinguishes "bootstrap not yet attempted" (default,
# transient) from "bootstrap attempted and crashed" (permanent for this
# process). spawn_worker checks this so the user gets an honest
# "Jarvis-Agent konnte nicht initialisiert werden" instead of the misleading  # i18n-allow
# "noch nicht bereit, bitte einen Moment warten" returned during boot.  # i18n-allow
# returns when both the manager and kontrollierer singletons are None
# but the server is still booting.
_WORKER_BOOTSTRAP_FAILED: list[bool] = [False]


def set_mission_manager(manager: Any) -> None:
    """Singleton setter for the MissionManager.

    Called by the server bootstrap (``_init_mission_stack``) as soon as the
    MissionManager is ready. Subsequent ``build_default_brain`` calls pick it
    up and thread it into the ``spawn_worker`` tool.
    """
    if _MISSION_MANAGER_REF:
        _MISSION_MANAGER_REF[0] = manager
    else:
        _MISSION_MANAGER_REF.append(manager)


def set_kontrollierer(kontrollierer: Any) -> None:
    """Singleton setter for the Kontrollierer (mission orchestrator).

    Called by the server bootstrap (``_init_mission_stack``). Without this
    setter the voice path would dispatch a mission but nothing would trigger
    ``run_mission()`` — the mission would remain PENDING and the user would
    never hear a response.
    """
    if _KONTROLLIERER_REF:
        _KONTROLLIERER_REF[0] = kontrollierer
    else:
        _KONTROLLIERER_REF.append(kontrollierer)


def set_worker_bootstrap_failed(flag: bool) -> None:
    """Mark the worker-harness bootstrap as permanently broken for this process.

    Called from ``server.py::_init_mission_stack`` when the Mission-Stack
    bootstrap raised. spawn_worker reads this via
    ``is_worker_bootstrap_failed()`` and surfaces an honest "could not be
    initialized" message instead of the transient "not ready yet" the
    in-progress path returns.
    """
    _WORKER_BOOTSTRAP_FAILED[0] = bool(flag)


def is_worker_bootstrap_failed() -> bool:
    """Returns True iff the Mission-Stack bootstrap raised at startup."""
    return bool(_WORKER_BOOTSTRAP_FAILED[0])


def _register_runtime_manager(manager: Any) -> None:
    """Publish one Brain Manager and its public tool gateway for all surfaces."""
    try:
        from dodaios.brain.tool_gateway import BrainSupervisorToolGateway
        from dodaios.brain.workspace_tool import WorkspaceOrchestrationTool
        from dodaios.core import runtime_refs

        class WorkspaceGateway:
            async def run(self, args: dict[str, Any], *, trace_id: str = "") -> dict[str, Any]:
                # Resolve lazily, off the boot path and event loop. The runtime
                # keeps the durable receipt store; providers receive a protocol.
                import asyncio

                from dodaios.agentic_ide.orchestration import get_orchestrator

                orchestrator = await asyncio.to_thread(get_orchestrator)
                bus = getattr(manager, "_bus", None)
                if orchestrator.publish is None and bus is not None:
                    # New panes must reach the open workspace view at once.
                    orchestrator.publish = bus.publish
                return await orchestrator.run(args, trace_id=trace_id)

        async def session_tool(session_id: str) -> Any:
            # Compose the optional society hand lazily; no society import at boot.
            from dodaios.society.surface import coding_tool_for_session

            return await coding_tool_for_session(session_id)

        async def browser_tool(session_id: str) -> Any:
            from dodaios.society.surface import browser_tool_for_session

            return await browser_tool_for_session(session_id)

        async def session_tools(session_id: str, tools: dict[str, Any]) -> Any:
            from dodaios.society.surface import tools_for_cli_session

            return await tools_for_cli_session(session_id, tools, manager)

        runtime_refs.set_brain_manager(manager)
        runtime_refs.set_supervisor_tool_gateway(
            BrainSupervisorToolGateway(
                manager,
                session_tool=session_tool,
                browser_tool=browser_tool,
                session_tools=session_tools,
                workspace_tool=WorkspaceOrchestrationTool(WorkspaceGateway()),
            )
        )
    except Exception as exc:  # noqa: BLE001 - registration never blocks boot
        log.debug("Runtime supervisor gateway registration failed: %s", exc)


def _phase2_full_brain(
    tier: Literal["router"] = "router",
    bus: Any | None = None,
) -> Any:
    """Build the BrainManager in router tier.

    Wave-4 migration: previously there was also a ``"sub_jarvis"`` tier.
    The Sub-Jarvis tier was replaced by the Jarvis-Agent bridge (see
    docs/jarvis-agents-bridge.md §11). The heavy worker runs as an external
    subprocess via ``MissionManager`` from ``dodaios/missions/``.

    tier="router": RouterBrain system prompt + ROUTER_TOOLS + Haiku.
    """
    from dodaios.brain.manager import BrainManager
    from dodaios.core import config as cfg
    from dodaios.core.bus import EventBus
    from dodaios.memory import (
        CORE_MEMORY_FILENAME,
        CoreMemory,
        MessageRecorder,
        PersonStore,
        RecallStore,
        Soul,
        UserProfile,
        Workspace,
    )
    from dodaios.memory.curator import Curator
    from dodaios.safety import ApprovalWorkflow, RiskTierEvaluator, ToolExecutor

    config = cfg.load_config()
    if bus is None:
        bus = EventBus()

    cfg.DATA_DIR.mkdir(parents=True, exist_ok=True)
    core_memory = CoreMemory.load(cfg.DATA_DIR / CORE_MEMORY_FILENAME)
    recall = RecallStore(cfg.DATA_DIR / "jarvis.db")
    recorder = MessageRecorder(recall)
    recorder.attach(bus)

    workspace = Workspace.ensure(cfg.DATA_DIR / "workspace")
    user_profile: UserProfile | None
    soul: Soul | None
    people: PersonStore | None
    try:
        user_profile = UserProfile.load(workspace.user_path)
        soul = Soul.load(workspace.soul_path)
        people = PersonStore(workspace)
    except Exception as exc:  # noqa: BLE001
        log.warning("Workspace load failed: %s — continuing without profile", exc)
        user_profile = None
        soul = None
        people = None

    from dodaios.clis.risk_integration import make_cli_patterns_fn
    evaluator = RiskTierEvaluator(
        config.safety, extra_patterns_fn=make_cli_patterns_fn(),
    )
    approval = ApprovalWorkflow(bus)
    executor = ToolExecutor(
        bus, evaluator, approval,
        default_timeout_s=config.safety.tool_approval_timeout_s,
    )

    # HarnessManager for the internal harness fast path (computer-use /
    # local-action). NB: dispatch-to-harness is no longer an
    # LLM-visible router tool (removed 2026-06-28) — see the ROUTER_TOOLS header.
    from dodaios.harness.manager import HarnessManager
    harness_manager = HarnessManager(bus=bus)
    # Config honesty: warn (don't fail) if a [harness.openclaw] block is enabled
    # but the harness is unregistered — that block is inert (Welle-4 removal).
    warn_if_phantom_worker_harness(config, harness_manager)

    # Build tools — Wave 4: no sub-tier any more; the Jarvis-Agent worker runs
    # as an external subprocess via MissionManager. If a MissionManager is
    # already present in ``app.state`` (server bootstrap), we pass it to
    # ``spawn_worker``.
    # If not (e.g. standalone call via ``build_default_brain`` BEFORE the server
    # bootstrap ran), the tool is excluded from the set — the force-spawn in
    # BrainManager knows this and returns a setup message instead of silently crashing.
    mission_manager_ref: Any = _resolve_mission_manager()

    # Chunk B (jarvis-contacts): build the ContactStore once and share the SAME
    # instance with the contact tools (via the loader) and the BrainManager (for
    # the name-index render). None until Chunk A is merged — graceful no-op.
    contact_store: Any = _build_contact_store()

    tools = _load_tools_for_tier(
        tier,
        bus=bus,
        executor=executor,
        harness_manager=harness_manager,
        user_profile=user_profile,
        people=people,
        config=config,
        mission_manager=mission_manager_ref,
        contacts=contact_store,
    )
    local_action_tools = _load_local_action_tools(
        bus=bus,
        harness_manager=harness_manager,
        config=config,
    )

    # brain.primary normally overrides [brain.router].provider — except when it
    # would put text turns on the realtime voice key (see the helper).
    startup_override = _router_provider_override(config)

    # Build the router-tier BrainManager via from_tier_config
    manager = BrainManager.from_tier_config(
        tier,
        config=config,
        bus=bus,
        provider_override=startup_override,
        tools=tools,
        local_action_tools=local_action_tools,
        tool_executor=executor,
        core_memory=core_memory,
        recall=recall,
        user_profile=user_profile,
        soul=soul,
        people=people,
        contacts=contact_store,
    )

    # Context-aware readbacks (maintainer mandate: no fixed stock phrases). The
    # composer is built in fallback-only mode when the flash path is disabled, so
    # this never changes behavior unless [ack_brain] is on. Router tier only —
    # the CU/local-action readbacks all originate on this manager.
    try:
        manager._readback_composer = build_readback_composer(config)
    except Exception as exc:  # noqa: BLE001 — never block brain wiring on this
        log.warning("Readback-Composer wiring skipped: %s", exc)

    # Live-reload marker: refresh_tools() uses these attributes to reconstruct
    # a factory call identical to this one.
    manager._tier = tier

    # App-Control (2026-05-31): register the live BrainManager so the
    # ``switch-provider`` tool (and the ``describe-app-settings`` snapshot) can
    # reach it at execute-time for a live, no-restart provider switch. Mirrors
    # the MissionManager singleton pattern; a headless build registers itself too.
    _register_runtime_manager(manager)

    # Wire live-reload on BrainToolsChanged (CLI connect/disconnect).
    try:
        manager.attach_to_bus(bus)
    except Exception as exc:  # noqa: BLE001
        log.warning("attach_to_bus failed: %s", exc)

    cu_cfg = getattr(config, "computer_use", None)
    cu_enabled = bool(cu_cfg and cu_cfg.enabled)

    # Vision wiring (Wave-2 latency fix — decoupled). The single ``VisionEngine``
    # feeds TWO independent consumers:
    #   (a) the per-turn screenshot injector ``_vision_provider`` — the always-on
    #       token tax, gated on ``[brain.router.vision].enabled`` (OFF by default);
    #   (b) Computer-Use's on-demand capture (``vision_engine_for_cu``), needed
    #       whenever ``[computer_use].enabled`` so "klick auf X" works.
    # Build the engine when EITHER consumer needs it, but attach the continuously
    # refreshing ``_vision_provider`` ONLY for (a). Previously both were gated on
    # the single vision flag, so disabling the per-turn feed also killed
    # Computer-Use (factory:924 "Vision-Engine fehlt"). They are now independent.
    manager._vision_provider = None
    vision_engine_for_cu: Any | None = None
    if tier == "router":
        router_tier = getattr(config.brain, "router", None)
        vision_cfg = getattr(router_tier, "vision", None) if router_tier is not None else None
        per_turn_vision = _per_turn_vision_active(vision_cfg)
        if _needs_vision_engine(per_turn_vision=per_turn_vision, cu_enabled=cu_enabled):
            try:
                from dodaios.vision.engine import VisionEngine

                # Computer-Use capture strategy (Problem 1, 2026-06-28). The
                # [computer_use].monitor policy ("primary" default) drives the G8
                # MOVE-to-primary hook (ctx.monitor), but the screenshot CAPTURE
                # must FOLLOW the foreground/target window — pinning it to the
                # primary made CU film an EMPTY primary and "do nothing" whenever
                # the target app sat on a secondary monitor. Following the window
                # (consistent with _capture_monitor_geometry, which already does)
                # means CU works on main when the target is moved there and on the
                # secondary when a window can't be moved, instead of freezing. The
                # negative-X absolute-click fix makes secondary clicks land. "all"
                # still captures the whole virtual desktop.
                from dodaios.vision.screenshot import cu_capture_strategy  # noqa: PLC0415

                _cu_monitor = getattr(
                    getattr(config, "computer_use", None), "monitor", "primary",
                )
                engine = VisionEngine(
                    bus=bus, monitor_strategy=cu_capture_strategy(_cu_monitor),
                )
                vision_engine_for_cu = engine
                if per_turn_vision:
                    from dodaios.vision.context_provider import VisionContextProvider

                    manager._vision_provider = VisionContextProvider(
                        engine,
                        bus=bus,
                        refresh_interval_s=vision_cfg.refresh_interval_s,
                        max_staleness_s=vision_cfg.max_staleness_s,
                        capture_mode=vision_cfg.capture_mode,
                    )
                    log.info(
                        "VisionContextProvider instantiiert (interval=%ss, mode=%s)",
                        vision_cfg.refresh_interval_s,
                        vision_cfg.capture_mode,
                    )
                else:
                    log.info(
                        "Per-turn vision injection OFF — VisionEngine kept for "
                        "Computer-Use on-demand capture only (max-speed mode)."
                    )
            except Exception as exc:  # noqa: BLE001
                log.warning("Vision engine/provider could not be built: %s", exc)
                manager._vision_provider = None
                vision_engine_for_cu = None

    # Computer-Use runs the in-process screenshot/click/keyboard loop
    # (dodaios/harness/screenshot_only_loop.py) via the ComputerUseContext
    # wired below. Requires the router tier + a vision engine.
    if tier == "router" and cu_enabled and vision_engine_for_cu is not None:
        try:
            from dodaios.harness.computer_use_context import (
                ComputerUseContext,
                set_computer_use_context,
                subscribe_context_reload,
            )

            # Computer-Use tool set: Wave 4 — previously ``sub_tools``
            # (the Sub-Jarvis tier toolbox) was used as the base. After the
            # Jarvis-Agent-bridge migration we load all computer-use-relevant
            # tools directly from entry_points.
            cu_tools: dict[str, Any] = {}
            cu_tools.update({
                name: tool
                for name, tool in tools.items()
                if name in {"screenshot", "run_shell"}
            })
            # Action-registry actions need their corresponding tools in
            # the cu_tools dict — otherwise the brain plans actions that the
            # loop cannot execute. These tools are CU-specific and not in
            # ROUTER_TOOLS, so they are loaded directly from entry_points.
            from dodaios.core.entry_points import entry_points as _eps
            _CU_EXTRA = {
                # Verify / wait helpers already wired in earlier waves.
                "wait-for-ui-state",
                "read-visible-ui-state",
                "switch-window",
                # Primary action tools — without these every plan from the
                # CU loop otherwise fails with the historical error below:
                # "Tool '<name>' nicht im Computer-Use-Tool-Set verdrahtet".  # i18n-allow
                # action_registry.py:278-368 maps the corresponding action
                # names (type_text, click, hotkey, move_mouse, open_app) to
                # the tool.name attribute on these classes, so they must
                # be present in cu_tools.
                "type-text",
                "click",
                "hotkey",
                "move-mouse",
                "open-app",
                # Multi-step robustness primitives (Set-of-Marks ReAct loop):
                # click by UIA name (no coordinate guessing), mouse-wheel scroll
                # to reveal off-screen list items, and poll-until-element for
                # app-launch/load waits. Map to action_registry actions
                # click_element / scroll / wait_for_element.
                "click-element",
                "scroll",
                "wait-for-element",
            }
            for _ep in _eps(group="jarvis.tool"):
                if _ep.name not in _CU_EXTRA:
                    continue
                try:
                    _cls = _ep.load()
                    _inst = _cls()
                    if _inst.name not in cu_tools:
                        cu_tools[_inst.name] = _inst
                except Exception as _exc:  # noqa: BLE001
                    # WARNING, not debug: a CU tool that silently vanishes
                    # here makes every plan that names it fail at execute
                    # time with "tool not wired" — invisible at default log
                    # level for months (2026-07-06 forensic: click/
                    # click_element/move_mouse were dropped on every host
                    # without the OS-Level editable install).
                    log.warning(
                        "CU tool '%s' failed to load and is DROPPED from the "
                        "Computer-Use tool set: %s", _ep.name, _exc,
                    )
            # The `drag` action has no entry-point plugin (it was historically
            # handled inline); inject it directly so the CU loop routes drag
            # through the ToolExecutor for risk-tier / blacklist / audit parity
            # (audit #13). Best-effort: a load failure leaves the loop's inline
            # drag fallback in place.
            try:
                from dodaios.plugins.tool.drag import DragTool  # noqa: PLC0415

                cu_tools.setdefault("drag", DragTool())
            except Exception as _exc:  # noqa: BLE001
                log.warning(
                    "CU drag tool failed to load and is DROPPED from the "
                    "Computer-Use tool set: %s", _exc,
                )
            # Wave 3: optionally build the native Gemini computer_use engine.
            # Returns None unless [computer_use].prefer_native is on AND the
            # active provider is Gemini, so the default (hand-rolled) path is
            # unchanged. Any build/runtime failure inside the engine degrades
            # to the hand-rolled loop per-step.
            native_cu = None
            try:
                from dodaios.harness.native_computer_use import GeminiNativeCU
                native_cu = GeminiNativeCU.from_config(config)
                if native_cu is not None:
                    log.info("Computer-Use: native Gemini engine ENABLED (model=%s)",
                             native_cu.model)
            except Exception as _exc:  # noqa: BLE001 — never block CU bootstrap
                log.debug("native CU engine not built: %s", _exc)
            # Emergency Stop (deep-dive 2026-07-15, C-02): the CU harness
            # already registers its CancelScope token with ctx.kill_switch —
            # but nothing ever provided one, so the advertised global stop
            # (tray "Emergency stop", hotkey, voice kill phrase) never reached
            # a running mission. Bind the process-wide switch to THIS bus
            # (idempotent) so every KillRequested cancels active CU tokens.
            from dodaios.control import get_kill_switch  # noqa: PLC0415

            cu_kill_switch = get_kill_switch()
            if bus is not None:
                cu_kill_switch.bind(bus)
            set_computer_use_context(ComputerUseContext(
                vision_engine=vision_engine_for_cu,
                brain_manager=manager,
                tool_executor=executor,
                tools=cu_tools,
                bus=bus,
                kill_switch=cu_kill_switch,
                step_budget=cu_cfg.step_budget,
                per_step_timeout_s=cu_cfg.per_step_timeout_s,
                think_timeout_cap_s=getattr(cu_cfg, "think_timeout_cap_s", 10.0),
                image_max_bytes=getattr(cu_cfg, "image_max_bytes", 300_000),
                image_max_dimension=getattr(cu_cfg, "image_max_dimension", 2048),
                settle_scale=getattr(cu_cfg, "settle_scale", 1.0),
                fast_step_model=getattr(cu_cfg, "fast_step_model", ""),
                plan_model_override=cu_cfg.plan_model,
                verify_after_each_step=cu_cfg.verify_after_each_step,
                strict_verify=getattr(cu_cfg, "strict_verify", True),
                zoom_before_click=getattr(cu_cfg, "zoom_before_click", False),
                uia_click_fallback=getattr(cu_cfg, "uia_click_fallback", False),
                max_replans=cu_cfg.max_replans,
                announce_progress=getattr(cu_cfg, "announce_progress", False),
                native_cu=native_cu,
                monitor=getattr(cu_cfg, "monitor", "primary"),
                main_monitor=getattr(cu_cfg, "main_monitor", "primary"),
                coordinate_space=getattr(cu_cfg, "coordinate_space", "auto"),
                capture_scope=getattr(cu_cfg, "capture_scope", "window"),
                normalize_window=getattr(cu_cfg, "normalize_window", False),
            ))
            # Hot-reload: refresh the live context's step_budget / timeout /
            # replan knobs on ConfigReloaded so a voice-tunable change
            # ("setze Schrittlimit auf N" -> computer_use.step_budget) applies
            # to the next mission without an app restart (idempotent per bus).
            subscribe_context_reload(bus)
            # Screen indicator (yellow CU border + Esc-to-cancel): a bus
            # subscription only — the PySide6 sidecar spawns lazily on the
            # first CUControlStarted (AP-26).
            try:
                from dodaios.cu.indicator.controller import (  # noqa: PLC0415
                    wire_cu_indicator,
                )

                wire_cu_indicator(bus)
            except Exception as _ind_exc:  # noqa: BLE001
                log.warning("CU indicator not wired: %s", _ind_exc)
            log.info(
                "ComputerUseContext wired (tools=%s, step_budget=%d, "
                "verify=%s, max_replans=%d)",
                sorted(cu_tools.keys()),
                cu_cfg.step_budget,
                cu_cfg.verify_after_each_step,
                cu_cfg.max_replans,
            )
        except Exception as exc:  # noqa: BLE001
            log.warning("ComputerUseContext could not be set: %s", exc)
    elif tier == "router" and cu_cfg is not None and not cu_enabled:
        log.info("ComputerUseContext disabled ([computer_use].enabled = false)")
    elif tier == "router" and cu_enabled and vision_engine_for_cu is None:
        log.warning(
            "ComputerUseContext could not be wired up: "
            "[computer_use].enabled = true, but the vision engine is missing "
            "(check [brain.router.vision].enabled)"
        )

    # Router tier: inject system prompt
    from dodaios.brain.router import SYSTEM_PROMPT as ROUTER_SYSTEM_PROMPT
    manager._system_prompt_extra = ROUTER_SYSTEM_PROMPT

    # Curator: in Wave 4 this runs only in the router tier (the former
    # Sub-Jarvis tier is gone). Plan anchor remains: collect personal facts
    # from user turns.
    # B4 Soft-Disable (2026-05-17): gated behind
    # ``cfg.memory.legacy_curator.enabled`` (default False). The new
    # WikiCurator handles fact-extraction for the wiki vault; running both
    # in parallel produces two diverging notebooks (see
    # ``LegacyCuratorConfig`` docstring).
    legacy_enabled = bool(
        getattr(getattr(config.memory, "legacy_curator", None), "enabled", False)
    )
    if legacy_enabled and user_profile is not None and people is not None:
        try:
            fast_name = manager._active_name
            fast_brain = manager._get_brain(fast_name, manager._fast_model(fast_name))
            from dodaios.memory.curator import Curator
            manager._curator = Curator(
                brain=fast_brain,
                profile=user_profile,
                people=people,
                bus=bus,
            )
            log.info("Curator active for router tier (legacy_curator.enabled=true)")
        except Exception as exc:  # noqa: BLE001
            log.warning("Curator could not be initialized: %s", exc)
    elif not legacy_enabled:
        log.info(
            "Legacy-Curator soft-disabled (cfg.memory.legacy_curator.enabled=false) "
            "— wiki vault takes over fact extraction via WikiCurator/VoiceFactBridge"
        )

    # Soft-disabling the legacy curator left USER.md with no automatic writer
    # at all: the wiki took over fact extraction for the VAULT, but the
    # structured profile the Knowledge matrix renders is a different file, and
    # its only remaining path was the brain choosing to call ``update_profile``
    # mid-turn. Measured on a real box, that produced zero facts in 26 days.
    # The deterministic capture below is the floor under it — regex only, no
    # model, no provider, so it keeps the profile current even when the wiki
    # curator's provider is unavailable. The tool path stays and still catches
    # everything phrased less literally.
    if user_profile is not None and bus is not None:
        try:
            from dodaios.memory.profile_capture import ProfileCaptureBridge

            profile_capture = ProfileCaptureBridge(bus=bus, profile=user_profile)
            profile_capture.start()
            manager._profile_capture = profile_capture
        except Exception as exc:  # noqa: BLE001 — capture is never load-bearing
            log.warning("ProfileCaptureBridge could not be started: %s", exc)

    # B5 Agent C: WikiContextInjector — router-tier only.
    # Attempt to import Agent B's VaultSearch.  If the module is not yet
    # merged (ImportError), pass search=None so the injector is a silent no-op.
    if tier == "router":
        wiki_cfg = getattr(config, "wiki_context", None)
        wiki_enabled = bool(wiki_cfg and getattr(wiki_cfg, "enabled", True))
        if wiki_enabled:
            try:
                from dodaios.brain.wiki_context import WikiContextInjector
                from dodaios.memory.wiki.search import VaultSearch

                # Resolve the vault from [wiki_integration].vault_root — the
                # single source of truth shared with wiki-recall / wiki-page-read
                # / wiki_routes. The hardcoded project path is the last-resort
                # fallback only (see _resolve_wiki_vault_root).
                vault_path = _resolve_wiki_vault_root(config)
                search = VaultSearch(vault_path)
                # Warm the lazy SQLite connection off the critical path
                # (AP-26): the first per-turn search otherwise pays the
                # open+schema check against its own latency budget.
                import threading

                threading.Thread(
                    target=search.warm_up,
                    name="wiki-vault-warmup",
                    daemon=True,
                ).start()
                from dodaios.memory.wiki.semantic_search import get_active

                manager._wiki_injector = WikiContextInjector(
                    search=search,
                    # The provider returns None until the user switches
                    # semantic search on; nothing is loaded here.
                    semantic_search=get_active,
                    max_chars=getattr(wiki_cfg, "max_chars", 1500),
                    latency_budget_ms=getattr(wiki_cfg, "latency_budget_ms", 150),
                    min_keyword_length=getattr(wiki_cfg, "min_keyword_length", 3),
                    relevance_gate=bool(getattr(wiki_cfg, "relevance_gate", True)),
                    min_coverage=float(getattr(wiki_cfg, "min_coverage", 0.5)),
                    strict_min_coverage=float(
                        getattr(wiki_cfg, "strict_min_coverage", 0.75)
                    ),
                    min_relative_score=float(
                        getattr(wiki_cfg, "min_relative_score", 0.35)
                    ),
                )
                log.info(
                    "WikiContextInjector active (vault=%s, budget=%dms, gate=%s)",
                    vault_path,
                    getattr(wiki_cfg, "latency_budget_ms", 150),
                    "on" if getattr(wiki_cfg, "relevance_gate", True) else "off",
                )
            except ImportError:
                # Agent B's search module not yet merged — fallback to no-op.
                from dodaios.brain.wiki_context import WikiContextInjector
                manager._wiki_injector = WikiContextInjector(search=None)
                log.debug(
                    "WikiContextInjector in no-op mode: dodaios.memory.wiki.search "
                    "not available (Agent B not yet merged)"
                )
            except Exception as exc:  # noqa: BLE001
                log.warning("WikiContextInjector could not be initialised: %s", exc)
                from dodaios.brain.wiki_context import WikiContextInjector
                manager._wiki_injector = WikiContextInjector(search=None)

    manager.own_message_recorder(recorder, bus)
    return manager


def _legacy_full_brain(bus: Any | None = None) -> Any:
    """Legacy BrainManager path (before tiered routing) — only via JARVIS_BRAIN=legacy."""
    from dodaios.core.entry_points import entry_points

    from dodaios.brain.manager import BrainManager
    from dodaios.core import config as cfg
    from dodaios.core.bus import EventBus
    from dodaios.memory import (
        CORE_MEMORY_FILENAME,
        CoreMemory,
        MessageRecorder,
        PersonStore,
        RecallStore,
        Soul,
        UserProfile,
        Workspace,
    )
    from dodaios.memory.curator import Curator
    from dodaios.safety import ApprovalWorkflow, RiskTierEvaluator, ToolExecutor

    config = cfg.load_config()
    if bus is None:
        bus = EventBus()

    cfg.DATA_DIR.mkdir(parents=True, exist_ok=True)
    core_memory = CoreMemory.load(cfg.DATA_DIR / CORE_MEMORY_FILENAME)
    recall = RecallStore(cfg.DATA_DIR / "jarvis.db")
    recorder = MessageRecorder(recall)
    recorder.attach(bus)

    workspace = Workspace.ensure(cfg.DATA_DIR / "workspace")
    user_profile: UserProfile | None
    soul: Soul | None
    people: PersonStore | None
    try:
        user_profile = UserProfile.load(workspace.user_path)
        soul = Soul.load(workspace.soul_path)
        people = PersonStore(workspace)
    except Exception as exc:  # noqa: BLE001
        log.warning("Workspace load failed: %s", exc)
        user_profile = None
        soul = None
        people = None

    from dodaios.clis.risk_integration import make_cli_patterns_fn
    evaluator = RiskTierEvaluator(
        config.safety, extra_patterns_fn=make_cli_patterns_fn(),
    )
    approval = ApprovalWorkflow(bus)
    executor = ToolExecutor(
        bus, evaluator, approval,
        default_timeout_s=config.safety.tool_approval_timeout_s,
    )

    tools: dict[str, Any] = {}
    active_tools = {"open-app", "type-text", "run-shell", "search-web", "remember",
                    "dispatch-to-harness", "whoami", "cli-tools", "gmail", "vercel",
                    "google_calendar"}
    from dodaios.harness.manager import HarnessManager
    harness_manager = HarnessManager(bus=bus)

    for ep in entry_points(group="jarvis.tool"):
        if ep.name not in active_tools:
            continue
        try:
            cls = ep.load()
            if ep.name == "dispatch-to-harness":
                inst = cls(
                    bus=bus,
                    manager=harness_manager,
                    max_output_chars=config.harness.max_output_chars,
                )
            elif ep.name == "whoami":
                inst = cls(profile=user_profile, people=people)
            else:
                inst = cls()
            if getattr(inst, "is_virtual_loader", False):
                try:
                    expanded = inst.expand()
                except Exception as exc:  # noqa: BLE001
                    log.debug("virtual-loader '%s' expand() failed: %s", ep.name, exc)
                    continue
                for tool in expanded:
                    tools[tool.name] = tool
            else:
                tools[inst.name] = inst
        except Exception as exc:  # noqa: BLE001
            log.debug("Tool %s not loadable: %s", ep.name, exc)

    manager = BrainManager(
        config=config,
        bus=bus,
        core_memory=core_memory,
        recall=recall,
        tools=tools,
        tool_executor=executor,
        user_profile=user_profile,
        soul=soul,
        people=people,
    )

    # Keep the legacy/headless path on the same public supervisor-tool boundary
    # as the primary router factory.
    _register_runtime_manager(manager)

    manager._vision_provider = None
    router_tier = getattr(config.brain, "router", None)
    vision_cfg = getattr(router_tier, "vision", None) if router_tier is not None else None
    if vision_cfg is not None and getattr(vision_cfg, "enabled", False):
        try:
            from dodaios.vision.context_provider import VisionContextProvider
            from dodaios.vision.engine import VisionEngine

            engine = VisionEngine(bus=bus)
            manager._vision_provider = VisionContextProvider(
                engine,
                bus=bus,
                refresh_interval_s=vision_cfg.refresh_interval_s,
                max_staleness_s=vision_cfg.max_staleness_s,
                capture_mode=vision_cfg.capture_mode,
            )
        except Exception as exc:  # noqa: BLE001
            log.warning("VisionContextProvider could not be built: %s", exc)
            manager._vision_provider = None

    # B4 Soft-Disable (2026-05-17) — see the matching gate in
    # build_default_brain above for the rationale.
    legacy_enabled = bool(
        getattr(getattr(config.memory, "legacy_curator", None), "enabled", False)
    )
    if legacy_enabled and user_profile is not None and people is not None:
        try:
            fast_name = manager._active_name
            fast_brain = manager._get_brain(fast_name, manager._fast_model(fast_name))
            manager._curator = Curator(
                brain=fast_brain,
                profile=user_profile,
                people=people,
                bus=bus,
            )
            log.info("Curator active (legacy path, legacy_curator.enabled=true)")
        except Exception as exc:  # noqa: BLE001
            log.warning("Curator could not be initialized: %s", exc)

    # Same floor under USER.md as in build_default_brain — a profile that is
    # only maintained on one of the two brain-build paths reads as broken on
    # the other.
    if user_profile is not None and bus is not None:
        try:
            from dodaios.memory.profile_capture import ProfileCaptureBridge

            profile_capture = ProfileCaptureBridge(bus=bus, profile=user_profile)
            profile_capture.start()
            manager._profile_capture = profile_capture
        except Exception as exc:  # noqa: BLE001 — capture is never load-bearing
            log.warning("ProfileCaptureBridge could not be started: %s", exc)

    manager.own_message_recorder(recorder, bus)
    return manager


def _phase1_gemini_fallback() -> Any:
    from dodaios.brain.gemini_test_brain import GeminiTestBrain
    return GeminiTestBrain()


async def _echo_brain(text: str) -> str:
    return f"Echo: {text}"


def build_default_brain(
    *,
    tier: Literal["router"] = "router",
    allow_phase2: bool = True,
    bus: Any | None = None,
) -> Any:
    """Return a brain callback (async (str)->str) according to the fallback chain.

    Wave-4 migration: previously there were two tiers ``router`` and
    ``sub_jarvis``. The Sub-Jarvis tier was replaced by the Jarvis-Agent
    bridge — see docs/jarvis-agents-bridge.md §11.

    Args:
        tier: "router" — the Haiku delegator tier (the only tier remaining
            after Wave 4).
        allow_phase2: When ``False``, skips BrainManager and falls back
            immediately to the Phase-1 Gemini fallback. Intended for tests.
        bus: Optional ``EventBus``. ``None`` = own bus (voice-pipeline default).

    Control via ENV:
    - `JARVIS_BRAIN=echo`    → pure echo (no LLM)
    - `JARVIS_BRAIN=gemini`  → always GeminiTestBrain
    - `JARVIS_BRAIN=legacy`  → legacy BrainManager without tiered routing
    - unset / "full"         → Phase-5.5 tiered BrainManager
    """
    # Capability-coupling (ADR-0017): seed the CapabilityRegistry once, here in
    # the single authoritative brain entry point, so EVERY runtime (voice, REST,
    # headless) has a populated registry before the first turn. Without this the
    # registry stays empty and BrainManager._check_unsupported_intent rejects
    # every action utterance with the phrase below, pre-empting the provider:
    # "Das kann ich noch nicht ..."  # i18n-allow
    # deterministic force-spawn path (live bug 2026-05-25 — "Kannst du einen
    # Subagent spawnen"). seed_registry is idempotent (re-registration replaces
    # by id), so repeated brain builds AND the dynamic MCP registration in
    # dodaios.mcp.adapter coexist without clobbering each other.
    try:
        from dodaios.core.capabilities import get_registry
        from dodaios.core.capabilities_seed import seed_registry

        seed_registry(get_registry())
    except Exception as exc:  # noqa: BLE001 — a seed hiccup must not kill the brain build
        log.warning("CapabilityRegistry seed failed: %s", exc)

    # Boot-race fix (AD-S6, 2026-06-09 rebuild): the skill context used to be
    # set only late in desktop_app._start_speech_and_orb — the first voice
    # turn could build a system prompt WITHOUT the AVAILABLE SKILLS section
    # (RC2 of "Jarvis never calls a skill"). Set a minimal context here, at
    # the single authoritative brain entry point, when none exists yet. The
    # desktop app later re-sets it with the web server's shared registry —
    # an idempotent upgrade (set_skill_context also re-registers paired
    # capabilities). The empty tool_registry is fine: the instruction-skill
    # model never executes TOOL: lines through this runner.
    try:
        from dodaios.skills.bootstrap import ensure_user_skills_dir
        from dodaios.skills.prefs import load_state_overrides
        from dodaios.skills.registry import SkillRegistry
        from dodaios.skills.runner import SkillRunner
        from dodaios.skills.skill_context import (
            SkillContext,
            set_skill_context,
            try_get_skill_context,
        )

        if try_get_skill_context() is None:
            _skills_root = ensure_user_skills_dir()
            _registry = SkillRegistry(
                root=_skills_root,
                bus=bus,
                state_prefs_loader=load_state_overrides,
            )
            _registry.reload_sync()
            set_skill_context(
                SkillContext(
                    registry=_registry,
                    runner=SkillRunner(registry=_registry, tool_registry={}, bus=bus),
                )
            )
            log.info(
                "Skill context set at brain build time (%d skills from %s)",
                len(_registry.list()),
                _skills_root,
            )
    except Exception as exc:  # noqa: BLE001 — skills must never block boot
        log.warning("skill-context bootstrap at brain build failed: %s", exc)

    # Plugin<->Skill pairing (2026-06-07): after the static seed, register a
    # capability for every live paired skill so connected plugins resolve.
    # Placed after seed_registry so an explicit paired cap overrides the weak
    # MCP auto-cap for the same domain. Defensive: a missing skill context must
    # not block boot (cloud-first graceful degradation).
    try:
        from dodaios.skills.plugin_coupling import register_paired_capabilities
        from dodaios.skills.skill_context import try_get_skill_context

        _ctx = try_get_skill_context()
        if _ctx is not None:
            register_paired_capabilities(get_registry(), _ctx.registry.list())
    except Exception as exc:  # noqa: BLE001
        log.debug("paired-capability seed skipped: %s", exc)

    mode = (os.environ.get("JARVIS_BRAIN") or "").strip().lower()

    if mode == "echo":
        log.info("JARVIS_BRAIN=echo → Echo-Brain aktiv.")
        return _echo_brain

    if mode == "legacy":
        log.info("JARVIS_BRAIN=legacy → Legacy BrainManager (before tiered routing).")
        try:
            return _legacy_full_brain(bus=bus)
        except Exception as exc:  # noqa: BLE001
            log.warning("Legacy BrainManager could not be initialized: %s — falling back.", exc)
            try:
                return _phase1_gemini_fallback()
            except Exception as exc2:  # noqa: BLE001
                log.error("GeminiTestBrain fallback also failed: %s", exc2)
                return _echo_brain

    if mode == "gemini" or not allow_phase2:
        try:
            brain = _phase1_gemini_fallback()
            log.info("Brain stack: GeminiTestBrain (Phase-1b compat mode).")
            return brain
        except Exception as exc:  # noqa: BLE001
            log.warning("GeminiTestBrain not available: %s — falling back to echo.", exc)
            return _echo_brain

    # Default: full BrainManager with tier routing. No silent echo/test-brain
    # fallback in the production path: if the manager cannot be built, the UI
    # should show a genuine error state.
    try:
        brain = _phase2_full_brain(tier=tier, bus=bus)
        log.info(
            "Brain stack: BrainManager tier=%s active — provider=%s, tools=%d",
            tier,
            getattr(brain, "active_provider", "?"),
            len(getattr(brain, "_tools", {})),
        )
        return brain
    except Exception as exc:  # noqa: BLE001
        log.error("BrainManager (tier=%s) could not be initialized: %s", tier, exc)
        raise


# ----------------------------------------------------------------------
# Flash-Brain (Pre-Thinking Ack) factory helper
# ----------------------------------------------------------------------

def _flash_preferences_provider(jcfg: Any) -> Any:
    """A zero-arg callable returning the user's flash-tier preferences block.

    Wired into the ack preamble and the spawn announcement so the user's
    agent-instructions file is honored on action turns (where the spoken output
    comes from these flash tiers, not the deep brain). Reads the file fresh per
    call (via ``agent_instructions.render_for_flash``) so an edit applies without
    a restart, and degrades to ``""`` when no file is set.
    """
    from dodaios.brain import agent_instructions

    def _provide() -> str:
        try:
            return agent_instructions.render_for_flash(jcfg)
        except Exception:  # noqa: BLE001 — never break the flash call on a prefs fault
            return ""

    return _provide


def build_ack_brain(jcfg: Any | None = None) -> Any:
    """Build an AckGenerator from cfg.ack_brain, or return ``None`` when disabled.

    The Flash-Brain runs alongside the main Router-Brain on every user
    utterance and emits a single short acknowledgment within ~900 ms.
    See docs/superpowers/specs/2026-05-11-pre-thinking-ack-flash-brain-design.md.

    Returns ``None`` when:
    - ``[ack_brain].enabled = false`` in jarvis.toml (subsystem master off)
    - ``[ack_brain].preamble_enabled = false`` (the default since 2026-06-21 —
      the speculative preamble is retired; the grounded spawn announcer stays
      wired via ``build_spawn_announcer``)
    - the configured provider is missing from REGISTRY
    - construction of the provider or breaker raises

    Never raises — callers can treat the absence of an AckGenerator as
    "feature disabled" without an exception trail.
    """
    try:
        if jcfg is None:
            from dodaios.core.config import load_config
            jcfg = load_config()
        ack_cfg = getattr(jcfg, "ack_brain", None)
        if ack_cfg is None or not getattr(ack_cfg, "enabled", False):
            log.info("Flash-Brain: disabled in jarvis.toml — skipping wiring.")
            return None
        # The speculative pre-thinking preamble is gated by its own
        # sub-switch (default off, 2026-06-21). `enabled` stays the
        # subsystem master so the grounded spawn announcer keeps its LLM
        # path; only this blind preamble generator is retired here. With
        # no AckGenerator the pipeline's fire-and-forget preamble task
        # never spawns (pipeline.py guards on `_ack_brain is not None`).
        if not getattr(ack_cfg, "preamble_enabled", False):
            log.info(
                "Flash-Brain: pre-thinking preamble disabled "
                "([ack_brain].preamble_enabled=false) — spawn announcer unaffected."
            )
            return None

        from dodaios.brain.ack_brain import AckGenerator, CircuitBreaker

        provider = _build_flash_provider(jcfg, ack_cfg)
        if provider is None:
            return None
        breaker = CircuitBreaker(
            threshold=ack_cfg.circuit_breaker_threshold,
            cooldown_s=ack_cfg.circuit_breaker_cooldown_s,
        )
        # ack_cfg.provider is now the RESOLVED primary (follow_brain expanded).
        prefs_provider = _flash_preferences_provider(jcfg)
        fallback_gen = _build_ack_fallback(ack_cfg, preferences_provider=prefs_provider)
        ack_gen = AckGenerator(
            provider=provider,
            config=ack_cfg,
            breaker=breaker,
            fallback=fallback_gen,
            preferences_provider=prefs_provider,
        )
        log.info(
            "Flash-Brain: AckGenerator wired (provider=%s, timeout_ms=%d, fallback=%s).",
            ack_cfg.provider,
            ack_cfg.timeout_ms,
            getattr(fallback_gen, "_provider_name", None),
        )
        return ack_gen
    except Exception as exc:  # noqa: BLE001
        log.warning("Flash-Brain: build_ack_brain() failed: %s — disabling.", exc)
        return None


def _build_flash_provider(jcfg: Any, ack_cfg: Any) -> Any:
    """Construct the flash-LLM provider adapter for ``ack_cfg``, or ``None``.

    Shared by :func:`build_ack_brain` and :func:`build_spawn_announcer` so
    both flash consumers resolve providers identically. Handles the
    "follow_brain" meta-value: resolve to whatever ``brain.primary``
    currently points at, so the user does not have to keep two provider
    settings in sync. If the main brain is on a provider the Flash-Brain
    has no adapter for (openrouter, claude_api), fall back to the first
    REGISTRY family with a usable credential (AP-22 — a hardcoded literal
    fallback would brick this tier for every downloader whose only key is
    e.g. OpenAI). Mutates ``ack_cfg.provider`` to the resolved name so
    telemetry labels show the concrete provider.
    """
    from dodaios.brain.ack_brain.providers import REGISTRY

    provider_name = ack_cfg.provider
    if provider_name == "follow_brain":
        brain_cfg = getattr(jcfg, "brain", None)
        primary = getattr(brain_cfg, "primary", None) if brain_cfg else None
        # A primary on the realtime voice key does not pull flash composition
        # onto that key; the keyed fallback below picks another family first.
        from dodaios.brain.voice_key import bills_voice_key

        if primary and primary in REGISTRY and not bills_voice_key(jcfg, primary):
            log.info(
                "Flash-Brain: follow_brain -> %s (from brain.primary).",
                primary,
            )
            provider_name = primary
        else:
            fallback = _pick_keyed_flash_fallback(ack_cfg, jcfg)
            if fallback is None:
                log.warning(
                    "Flash-Brain: brain.primary=%r has no Flash adapter "
                    "(REGISTRY=%s) and no REGISTRY provider has a usable "
                    "credential; disabling Flash-Brain.",
                    primary, sorted(REGISTRY.keys()),
                )
                return None
            log.warning(
                "Flash-Brain: brain.primary=%r has no Flash adapter "
                "(REGISTRY=%s); falling back to keyed provider %r.",
                primary, sorted(REGISTRY.keys()), fallback,
            )
            provider_name = fallback
        ack_cfg.provider = provider_name
    provider_cls = REGISTRY.get(provider_name)
    if provider_cls is None:
        log.warning(
            "Flash-Brain: provider %r not in REGISTRY (have %s); disabled.",
            provider_name,
            sorted(REGISTRY.keys()),
        )
        return None
    provider_cfg = getattr(ack_cfg.providers, provider_name)
    return provider_cls(provider_cfg)


def _pick_keyed_flash_fallback(ack_cfg: Any, jcfg: Any = None) -> str | None:
    """First REGISTRY provider family with a usable credential, or ``None``.

    AP-21/AP-22: never hardcode a literal provider name as the fallback — a
    downloader whose only key is e.g. OpenAI must resolve to "openai", not a
    keyless "gemini". Iterates ``REGISTRY`` in its declared order (gemini,
    openai, ollama, ...) as the tie-break so an all-keyed setup keeps the
    historical default. A provider config with no ``api_key_secret`` field
    (local Ollama) needs no credential and is always considered usable.
    """
    from dodaios.brain.ack_brain.providers import REGISTRY
    from dodaios.brain.voice_key import bills_voice_key
    from dodaios.core.config import get_provider_secret, get_secret

    # A family on the realtime voice key is deferred (mandate 2026-09-29): the
    # next keyed family in REGISTRY order answers instead. It still comes back
    # before a keyless local provider, so a single-key install without a local
    # server keeps a working flash tier (AP-22).
    deferred: str | None = None
    for name in REGISTRY:
        provider_cfg = getattr(ack_cfg.providers, name, None)
        if provider_cfg is None:
            continue
        secret_name = getattr(provider_cfg, "api_key_secret", None)
        if secret_name is None:
            return deferred or name
        # The family resolver is the second probe so a credential that lives
        # only in a scoped slot of the same family (e.g. the Realtime card's
        # key) still marks the provider usable — the adapters resolve their
        # key through the same two-step lookup.
        if get_secret(secret_name) or get_provider_secret(name):
            if not bills_voice_key(jcfg, name):
                return name
            deferred = deferred or name
    return deferred


def _build_ack_fallback(ack_cfg: Any, preferences_provider: Any = None) -> Any:
    """Build the secondary failover AckGenerator, or ``None``.

    Wires ``[ack_brain].fallback_provider`` onto its OWN provider + circuit
    breaker so a busy primary never starves the ack (live bug 2026-06-18: the
    Gemini ack timed out while the Gemini deep brain was slow → 8 s of dead air).
    Best-effort: returns ``None`` (failover simply absent) when the fallback is
    unset, equal to the already-resolved primary, missing from REGISTRY, or
    unbuildable — it must never make the primary ack fail to wire. The returned
    generator has no fallback of its own, so delegation can never loop.
    """
    fb_name = getattr(ack_cfg, "fallback_provider", None)
    if not fb_name:
        return None
    if fb_name == ack_cfg.provider:
        log.info(
            "Flash-Brain: fallback_provider == primary (%s) — no failover wired.",
            fb_name,
        )
        return None
    try:
        from dodaios.brain.ack_brain import AckGenerator, CircuitBreaker
        from dodaios.brain.ack_brain.providers import REGISTRY

        provider_cls = REGISTRY.get(fb_name)
        if provider_cls is None:
            log.warning(
                "Flash-Brain: fallback_provider %r not in REGISTRY (have %s) — "
                "no failover wired.",
                fb_name,
                sorted(REGISTRY.keys()),
            )
            return None
        fb_provider = provider_cls(getattr(ack_cfg.providers, fb_name))
        # Own breaker + a config whose provider label is the fallback (and whose
        # own fallback is cleared, so the fallback generator never recurses).
        fb_cfg = ack_cfg.model_copy(
            update={"provider": fb_name, "fallback_provider": None}
        )
        fb_breaker = CircuitBreaker(
            threshold=ack_cfg.circuit_breaker_threshold,
            cooldown_s=ack_cfg.circuit_breaker_cooldown_s,
        )
        return AckGenerator(
            provider=fb_provider,
            config=fb_cfg,
            breaker=fb_breaker,
            preferences_provider=preferences_provider,
        )
    except Exception as exc:  # noqa: BLE001 — failover must never break wiring
        log.warning(
            "Flash-Brain: failover provider %r build failed: %s — no failover.",
            fb_name,
            exc,
        )
        return None


def _build_spawn_fallback(ack_cfg: Any) -> tuple[Any, Any]:
    """Build the spawn announcer's failover ``(provider, breaker)`` or ``(None, None)``.

    Mirrors :func:`_build_ack_fallback`, but yields a bare provider (the
    ``SpawnAnnouncementComposer`` owns the validate/pool logic, so it needs the
    provider directly, not a wrapping ``AckGenerator``). Returns ``(None, None)``
    — composer runs primary-only — when the failover is unset, equal to the
    already-resolved primary, missing from REGISTRY, or unbuildable. Must never
    break the announcer wiring.

    Call AFTER ``_build_flash_provider`` so ``ack_cfg.provider`` is the resolved
    primary (``follow_brain`` expanded) and the ``== primary`` check is accurate.
    """
    fb_name = getattr(ack_cfg, "fallback_provider", None)
    if not fb_name or fb_name == ack_cfg.provider:
        return None, None
    try:
        from dodaios.brain.ack_brain import CircuitBreaker
        from dodaios.brain.ack_brain.providers import REGISTRY

        provider_cls = REGISTRY.get(fb_name)
        if provider_cls is None:
            log.warning(
                "Spawn-Announcer: fallback_provider %r not in REGISTRY (have %s)"
                " — no failover wired.",
                fb_name,
                sorted(REGISTRY.keys()),
            )
            return None, None
        fb_provider = provider_cls(getattr(ack_cfg.providers, fb_name))
        fb_breaker = CircuitBreaker(
            threshold=ack_cfg.circuit_breaker_threshold,
            cooldown_s=ack_cfg.circuit_breaker_cooldown_s,
        )
        log.info("Spawn-Announcer: failover wired (provider=%s).", fb_name)
        return fb_provider, fb_breaker
    except Exception as exc:  # noqa: BLE001 — failover must never break wiring
        log.warning(
            "Spawn-Announcer: failover provider %r build failed: %s — no failover.",
            fb_name,
            exc,
        )
        return None, None


def build_spawn_announcer(jcfg: Any | None = None) -> Any:
    """Build the ``SpawnAnnouncementComposer`` for the ``spawn_worker`` tool.

    Never raises and never returns ``None``: when the flash-LLM path is
    unavailable (``[ack_brain].enabled = false``, ``spawn_announcements =
    false``, missing adapter, construction error) the composer is returned
    in fallback-only mode — the spoken spawn confirmation is then drawn
    from the curated bilingual no-repeat pool, so the user always hears an
    acknowledgement (AD-OE6).

    The composer gets its OWN provider instance and circuit breaker. The
    breaker state is intentionally not shared with the pre-thinking
    AckGenerator (built later in ``desktop_app``): both protect the same
    provider class, but their call sites have different latency stakes and
    a shared mutable singleton across the two build paths would couple the
    desktop-app wiring to the brain factory for marginal gain.
    """
    from dodaios.brain.ack_brain.spawn_announcement import (
        SpawnAnnouncementComposer,
    )

    def _live_agent_brand() -> str:
        # Read fresh per spawn so a wake-word change re-brands the spoken
        # announcement without a restart; resolution never raises upstream
        # (the composer falls back to the neutral brand on any failure).
        from dodaios.brain.assistant_name import agent_brand
        from dodaios.core.config import load_config

        return agent_brand(load_config())

    try:
        if jcfg is None:
            from dodaios.core.config import load_config
            jcfg = load_config()
        ack_cfg = getattr(jcfg, "ack_brain", None)
        if (
            ack_cfg is None
            or not getattr(ack_cfg, "enabled", False)
            or not getattr(ack_cfg, "spawn_announcements", True)
        ):
            log.info(
                "Spawn-Announcer: flash path disabled — fallback pool only."
            )
            return SpawnAnnouncementComposer(brand_provider=_live_agent_brand)

        from dodaios.brain.ack_brain import CircuitBreaker

        provider = _build_flash_provider(jcfg, ack_cfg)
        if provider is None:
            return SpawnAnnouncementComposer(brand_provider=_live_agent_brand)
        breaker = CircuitBreaker(
            threshold=ack_cfg.circuit_breaker_threshold,
            cooldown_s=ack_cfg.circuit_breaker_cooldown_s,
        )
        log.info(
            "Spawn-Announcer: LLM composition wired (provider=%s).",
            ack_cfg.provider,
        )
        # Failover on a separate provider/key so a dead primary flash provider
        # degrades to the live secondary, not to the canned pool (2026-06-21
        # regression: gemini 429 with no spawn-path failover -> stock phrases).
        fb_provider, fb_breaker = _build_spawn_fallback(ack_cfg)
        return SpawnAnnouncementComposer(
            provider=provider,
            config=ack_cfg,
            breaker=breaker,
            fallback_provider=fb_provider,
            fallback_breaker=fb_breaker,
            preferences_provider=_flash_preferences_provider(jcfg),
            brand_provider=_live_agent_brand,
        )
    except Exception as exc:  # noqa: BLE001
        log.warning(
            "build_spawn_announcer() failed: %s — fallback pool only.", exc
        )
        return SpawnAnnouncementComposer(brand_provider=_live_agent_brand)


def build_readback_composer(jcfg: Any | None = None) -> Any:
    """Build the ``ReadbackComposer`` for the deterministic action-path readbacks.

    The engine behind the maintainer's "no fixed stock phrases" mandate: the CU
    outcome/dispatch readbacks, budget guards, and tool-failed line are phrased
    fresh for the situation by a bounded flash call, with the EXISTING canned
    line as the instant fallback.

    Never raises and never returns ``None``: when the flash path is unavailable
    (``[ack_brain].enabled = false``, ``readback_generation = false``, missing
    adapter, construction error) the composer is returned in fallback-only mode,
    so the call sites still emit the canned line (AD-OE6, zero behavior change).
    Mirrors :func:`build_spawn_announcer` — own provider + breaker plus a
    separate-provider failover so a dead primary degrades to the live secondary,
    not straight to the canned table.
    """
    from dodaios.voice.contextual_readback import ReadbackComposer

    try:
        if jcfg is None:
            from dodaios.core.config import load_config
            jcfg = load_config()
        ack_cfg = getattr(jcfg, "ack_brain", None)
        if (
            ack_cfg is None
            or not getattr(ack_cfg, "enabled", False)
            or not getattr(ack_cfg, "readback_generation", True)
        ):
            log.info("Readback-Composer: flash path disabled — fallback-only mode.")
            return ReadbackComposer()

        from dodaios.brain.ack_brain import CircuitBreaker

        provider = _build_flash_provider(jcfg, ack_cfg)
        if provider is None:
            return ReadbackComposer()
        breaker = CircuitBreaker(
            threshold=ack_cfg.circuit_breaker_threshold,
            cooldown_s=ack_cfg.circuit_breaker_cooldown_s,
        )
        # Failover on a separate provider/key (built AFTER _build_flash_provider
        # so ack_cfg.provider is the resolved primary). Reuses the spawn-path
        # bare-provider failover builder — the composer owns its validate logic.
        fb_provider, fb_breaker = _build_spawn_fallback(ack_cfg)
        log.info(
            "Readback-Composer: LLM composition wired (provider=%s).",
            ack_cfg.provider,
        )
        return ReadbackComposer(
            provider=provider,
            config=ack_cfg,
            breaker=breaker,
            fallback_provider=fb_provider,
            fallback_breaker=fb_breaker,
            preferences_provider=_flash_preferences_provider(jcfg),
        )
    except Exception as exc:  # noqa: BLE001
        log.warning(
            "build_readback_composer() failed: %s — fallback-only mode.", exc
        )
        return ReadbackComposer()


def _router_provider_override(config: Any) -> str | None:
    """The provider that overrides ``[brain.router].provider`` at boot, or None.

    Provider-override logic: if the user has switched to a different provider
    via voice/UI ("switch to gemini" -> brain.primary="gemini" persisted in
    jarvis.toml) while [brain.router].provider still points elsewhere, we
    prefer brain.primary. That is the global master selection that should
    apply to all tiers.

    The realtime voice call owns its key (user mandate 2026-09-29: the GPT-Live
    key pays for the voice call and its thinking model only). While voice runs
    realtime the Brain tab is hidden, so a ``brain.primary`` left on that key's
    family is not a choice anyone can see; it must not pull text turns onto the
    voice budget when the router tier names another provider. A single-key
    install (no other router provider) keeps working on the key.
    """
    from dodaios.brain.voice_key import bills_voice_key

    primary = config.brain.primary
    tier_cfg = getattr(config.brain, "router", None)
    tier_provider = tier_cfg.provider if tier_cfg else None
    if (
        bills_voice_key(config, primary)
        and tier_provider
        and not bills_voice_key(config, tier_provider)
    ):
        log.info(
            "Router stays on [brain.router].provider=%s: brain.primary=%s bills "
            "the realtime voice key.",
            tier_provider, primary,
        )
        return None
    if primary and primary != tier_provider:
        log.info(
            "Startup override: brain.primary=%s overrides [brain.router].provider=%s",
            primary, tier_provider,
        )
        return primary
    return None