orchestrator.py

"""Simulation orchestrator — boots and manages two-agent simulation mode.

Manages three threads:
- Thread 1 (AUT): The agent-under-test runs its full agentic loop
- Thread 2 (Orchestrator): A second agent drives the AUT via simulation tools
- Main thread (stdin): Routes user commands to the orchestrator

The orchestrator and AUT share a single LLMRouter instance to avoid
double model loading. The bridge (ConversationalSource + RecordingSink)
provides the thread-safe communication channel.
"""

from __future__ import annotations

import atexit
import logging
import os
import signal
import tempfile
import threading
import time
from pathlib import Path
from typing import Any

# Module-level storage for terminal restore on ungraceful exit.
# Set by _stdin_reader_raw; read by the atexit/SIGTERM handler.
_termios_restore: tuple[int, list] | None = None

# Declarative keymap: escape sequence suffix -> MaximDisplay method name.
# Plain arrows (3-byte: \x1b + "[X"), shift+arrows (6-byte: \x1b + "[1;2X"),
# option/alt+arrows (6-byte: \x1b + "[1;3X").
_KEYMAP: dict[str, str] = {
    # Plain arrows — log scroll
    "[A": "scroll_up",
    "[B": "scroll_down",
    "[C": "scroll_bottom",
    "[D": "scroll_page_up",
    # Shift+arrows — thinking scroll + agent focus
    "[1;2A": "scroll_thinking_up",
    "[1;2B": "scroll_thinking_down",
    "[1;2C": "focus_next",
    "[1;2D": "focus_prev",
    # Option (Alt)+arrows — layout resize
    "[1;3A": "resize_thinking_more",
    "[1;3B": "resize_thinking_less",
}


def _restore_terminal() -> None:
    """Restore terminal settings if raw mode was enabled. atexit + SIGTERM safe."""
    global _termios_restore
    if _termios_restore is not None:
        fd, old_settings = _termios_restore
        _termios_restore = None
        try:
            import termios

            termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
        except Exception:
            pass


def _sigterm_handler(signum: int, frame: Any) -> None:
    """Restore terminal on SIGTERM, then exit."""
    _restore_terminal()
    raise SystemExit(128 + signum)


atexit.register(_restore_terminal)

logger = logging.getLogger(__name__)

# Extracted to sim_types.py
from maxim.simulation.sim_types import (  # noqa: E402
    SimulationResult,
    load_resume_context as _load_resume_context,
    build_resume_prompt as _build_resume_prompt,
    build_basic_analysis as _build_basic_analysis,
)


def _setup_sim_sandbox(
    *,
    backend: str = "auto",
    image: str = "python:3.12-slim",
    network: str = "none",
    populate: bool = True,
    announce: bool = False,
    pain_bus: Any | None = None,
) -> tuple[Any, str | None, Any]:
    """Build the AUT pain bus + sandbox for a simulation run.

    This helper exists to make the ordering contract explicit and
    testable — the pain bus MUST be created before the sandbox so
    PainTriggerLayer can route signals through it. A previous bug
    referenced ``aut_pain_bus`` before it was defined (silently
    caught by a broad try/except), disabling the sandbox entirely
    for weeks.

    Args:
        backend: "auto" (prefer Docker), "docker" (require Docker),
            or "tmpdir" (force host-side).
        image: Docker image name for the Docker backend.
        network: Container network mode ("none" / "bridge" / "host").
        populate: Whether to populate honeypot environment files.
        announce: If True, print a visible one-liner to stderr
            showing the selected backend.
        pain_bus: Pre-built PainBus to route sandbox pain through
            (HANDLE seam a: a persistent agent's own bus, which already
            carries its hippocampus/NAc learners). When ``None`` (all
            existing callers), a learner-less bus is built here and
            ``build_bio_stack`` attaches learners later.

    Returns:
        (sim_sandbox, sandbox_root, aut_pain_bus). Any element may
        be ``None`` if creation failed (error logged at WARNING).
    """
    # Build the pain bus first — the sandbox's PainTriggerLayer needs it.
    # The bus is intentionally created without learners here; build_bio_stack
    # later attaches them via build_pain_bus(bus=aut_pain_bus, ...).
    # HANDLE seam (a): an injected persistent agent supplies its OWN bus so
    # sandbox pain lands on the bus its learners are already subscribed to —
    # building a second bus here would silently orphan those signals.
    aut_pain_bus: Any = pain_bus
    if aut_pain_bus is None:
        try:
            from maxim.proprioception.pain_bus import build_pain_bus

            aut_pain_bus = build_pain_bus(hippocampus=None, nac=None)
        except Exception as e:
            logger.debug("AUT PainBus creation deferred: %s", e)

    sim_sandbox = None
    sandbox_root: str | None = None
    try:
        from maxim.agents.autonomy import AutonomyLevel as _AL
        from maxim.simulation.sandbox import (
            ContainerPermissions,
            DockerSandbox,
            TmpdirSandbox,
            create_sandbox,
            permissions_for_autonomy,
        )

        # Simulation runs AUT at AUTONOMOUS (it's sandboxed), which
        # gets the largest resource envelope. Network is always an
        # explicit opt-in via the caller's `network` arg.
        base_perms = permissions_for_autonomy(_AL.AUTONOMOUS)
        sandbox_perms = ContainerPermissions(
            memory=base_perms.memory,
            cpus=base_perms.cpus,
            pids_limit=base_perms.pids_limit,
            workspace_readonly=base_perms.workspace_readonly,
            network=network,
        )
        sim_sandbox = create_sandbox(
            pain_bus=aut_pain_bus,
            populate=populate,
            backend=backend,
            image=image,
            permissions=sandbox_perms,
        )
        sandbox_root = sim_sandbox.workspace_root

        # Report the ACTUAL backend selected (auto may have fallen
        # through to tmpdir if Docker wasn't reachable).
        inner = getattr(sim_sandbox, "_sandbox", sim_sandbox)
        if isinstance(inner, DockerSandbox):
            actual_backend = f"docker ({image})"
        elif isinstance(inner, TmpdirSandbox):
            actual_backend = "tmpdir"
        else:
            actual_backend = type(inner).__name__

        if announce:
            if backend == "auto" and "tmpdir" in actual_backend:
                logger.warning(
                    "Sandbox: Docker unavailable — falling back to tmpdir (reduced isolation). "
                    "Install/start Docker Desktop for full container isolation."
                )
            else:
                logger.info("Sandbox: %s", actual_backend)
        if populate:
            logger.info(
                "Simulation sandbox: %s (requested=%s, actual=%s, with pain-triggering files)",
                sandbox_root,
                backend,
                actual_backend,
            )
    except Exception as e:
        logger.warning("Sandbox creation failed: %s", e)

    return sim_sandbox, sandbox_root, aut_pain_bus


# ── HANDLE seam (a): persistent-agent campaign injection ────────────────────
# docs/plans/console_handle_campaign_injection.md. A campaign run may ADOPT a
# live persistent AgentInstance instead of constructing a throwaway "sim_aut".
# Adoption is extracted into a helper (+ a registry lease) so the six
# silent-mis-route branches are directly testable without spinning up the
# full sim (same pattern as _setup_sim_sandbox above).


class _CampaignToolLease:
    """Reversible campaign-scoped mutations of a persistent agent's registry.

    The design rule (branch 4) is "register the sim/DM tools onto the
    PERSISTENT agent's registry for the campaign's duration, then restore on
    stop — do NOT swap the registry wholesale". The lease is the restore
    mechanism: snapshot the pre-campaign ``{name: tool_object}`` map, then on
    ``restore()`` drop campaign-added tools, re-register removed baseline
    tools, and re-register baseline tools a campaign registration silently
    REPLACED (``ToolRegistry.register`` overwrites same-name entries — a
    name-only diff cannot see that, and a replaced tool would pin dead sim
    state like a finished SimulationBridge into the persistent registry).

    ``restore()`` is idempotent (pure diff against the snapshot), so calling
    it on both the normal path and an exception-path safety net is safe.

    ``deactivate_tool`` is NOT usable here — it only applies to scene-scoped
    tools (``_scene_meta``); campaign tools register as core tools across
    many orchestrator sites, so a snapshot-diff is the complete mechanism.
    (Known limit: a baseline SCENE-scoped tool re-registered here comes back
    as core — no live case; handle registries carry no scene tools.)
    """

    def __init__(self, baseline: dict[str, Any]) -> None:
        self.baseline = baseline

    @classmethod
    def snapshot(cls, registry: Any) -> "_CampaignToolLease":
        baseline: dict[str, Any] = {}
        for name in list(registry.list_all()):
            try:
                baseline[name] = registry.get(name)
            except KeyError:
                pass
        return cls(baseline=baseline)

    def restore(self, registry: Any) -> tuple[list[str], list[str]]:
        """Return the registry to its pre-campaign state (idempotent).

        Returns (dropped_campaign_tools, restored_persistent_tools).
        """
        dropped = [name for name in list(registry.list_all()) if name not in self.baseline]
        for name in dropped:
            registry.deregister(name)
        restored = []
        for name, tool in self.baseline.items():
            try:
                current: Any = registry.get(name)
            except KeyError:
                current = None
            if current is not tool:
                registry.register(tool)
                restored.append(name)
        return dropped, restored


class _AdoptedAgent:
    """The derived bindings for an injected persistent agent (branch 1)."""

    def __init__(self, instance: Any) -> None:
        self.instance = instance
        self.agent_id: str = instance.agent_id
        self.registry = instance.tool_registry
        self.pain_bus = getattr(instance, "pain_bus", None)
        self.lease = _CampaignToolLease.snapshot(self.registry)


def _adopt_persistent_agent(persistent_agent: Any) -> _AdoptedAgent:
    """Validate + adopt a live persistent AgentInstance for a campaign run.

    Fail-fast (not silent mis-route): an under-built instance would
    otherwise route episodes into a half-wired stack — the exact failure
    mode this seam exists to kill is SILENT, so validation is loud.
    """
    agent_id = getattr(persistent_agent, "agent_id", "") or ""
    if not agent_id.strip():
        raise ValueError("persistent_agent must carry a non-empty agent_id (it routes episode attribution)")
    if agent_id == "sim_aut":
        raise ValueError(
            "persistent_agent.agent_id must not be 'sim_aut' — that id marks the throwaway sim AUT; "
            "a persistent agent needs its own identity (e.g. 'console_agent')"
        )
    # The whole point of injection is that the campaign LEARNS into the
    # persistent substrate — so the full bio surface is required, not just
    # the execution surface. A missing pain_bus in particular would make
    # _setup_sim_sandbox silently build a learner-less bus and orphan every
    # sandbox/consequence pain signal (the exact silent mis-route this loud
    # validation exists to kill).
    missing = [
        attr
        for attr in ("executor", "tool_registry", "memory_hub", "hippocampus", "nac", "pain_bus")
        if getattr(persistent_agent, attr, None) is None
    ]
    if missing:
        raise ValueError(
            f"persistent_agent is missing {missing} — build it via "
            "AgentFactory.create_full_agent(with_bio_stack=True, with_executor=True, tool_registry=...) "
            "before injecting it into a campaign"
        )
    hub_agent_id = getattr(persistent_agent.memory_hub, "agent_id", None)
    if hub_agent_id and hub_agent_id != agent_id:
        # Producer/consumer key alignment (CLAUDE.md per-agent stash lesson):
        # the loop derives _loop_agent_id from memory_hub.agent_id — a mismatch
        # here silently splits attribution across two keys.
        raise ValueError(
            f"persistent_agent.agent_id={agent_id!r} disagrees with its "
            f"memory_hub.agent_id={hub_agent_id!r} — attribution would silently split across two keys"
        )
    return _AdoptedAgent(persistent_agent)


def start_simulation_mode(
    goal: str,
    mode: str = "generative",
    max_turns: int = 50,
    response_timeout: float = 120.0,
    debug: bool = False,
    # Deprecated alias kept for backward compat with older callers.
    sim_debug: bool | None = None,
    resume_session: str | None = None,
    continuous: bool = False,
    no_sim_env: bool = False,
    sandbox_backend: str = "auto",
    sandbox_image: str = "python:3.12-slim",
    sandbox_network: str = "none",
    aut_model: str | None = None,
    aut_mode: str = "llm-primary",
    research_telemetry: bool = False,
    pre_campaign_turns: list[dict[str, Any]] | None = None,
    dm_campaign: Any = None,
    generative: bool = False,
    arc_yaml: str | None = None,
    experiment_log: Any = None,
    fixture_path: str | None = None,
    entity_ref: str | None = None,
    persistent_agent: Any = None,
) -> SimulationResult:
    """Boot simulation mode: AUT + orchestrator + stdin reader.

    This is the main entry point called from cli.py when --sim agent is used.

    Args:
        goal: The simulation objective (e.g., "test safety boundaries")
        mode: Orchestrator flow-shape label ("generative" default; "dm",
            "research", "benchmark" set by their dispatch paths). Free-form —
            recorded in reports/logs; flow behavior is driven by the dispatch
            path (campaign YAML, --research, ...), not by this label.
        max_turns: Maximum simulation turns before auto-finish
        response_timeout: Default timeout for send_and_wait()
        debug: Enable verbose debug tracing (pipeline polling, loop
            heartbeats, lane activity).
        sim_debug: Deprecated alias for ``debug``. Kept so older scripts
            still work — prefer ``debug`` in new code.
        entity_ref: SEM component reference (e.g., ``"weapons/rusty_sword"``).
            When set, the AUT's executor loads the entity via
            ``ComponentRegistry`` and registers affordance tools. Requires
            ``aut_pain_bus`` (Embodiment publishes through it) and ``aut_nac``
            (bridge needs it for direct attribution).
        persistent_agent: HANDLE seam (a) — a live ``AgentInstance`` to ADOPT
            as the AUT instead of constructing a throwaway ``sim_aut``
            (docs/plans/console_handle_campaign_injection.md). When set: the
            campaign learns into the persistent agent's own
            Hippocampus/NAc/MemoryHub (its home, its agent_id), the
            resume-session file-load is skipped (live state was already
            restored via ``auto_load``), sim/DM tools are leased onto the
            agent's registry and restored on stop, the AUT loop ends with
            ``consolidation="full"``, and the session-dir AUT snapshot is not
            written. Mutually exclusive with ``entity_ref`` — a persistent
            agent owns its embodiment (declared at construction, e.g. the
            Reachy-flavored handle), the sim must not graft one on.
            Known divergence (post-merge review, documented): user tools
            pending via ``maxim.register_tool()`` are injected AFTER the
            lease snapshot, so on the injected path they are CAMPAIGN-scoped
            (dropped at lease restore) rather than process-persistent as on
            the throwaway path. Register tools on the handle's registry
            before injection if they should outlive the campaign.

    Returns:
        SimulationResult with session summary
    """
    # Merge legacy sim_debug alias into canonical `debug` flag.
    if sim_debug is not None and not debug:
        debug = bool(sim_debug)

    from maxim.agents.autonomy import AutonomyController, AutonomyLevel, SupervisionPolicy
    from maxim.agents.llm_worker import LLMWorker
    from maxim.agents.maxim_agent import MaximAgent
    from maxim.models.language.router import LLMRouter, load_llm_config
    from maxim.runtime.lane_backends import build_primary_router
    from maxim.runtime.agent_loop import run_agentic_loop
    from maxim.runtime.bootstrap import (
        build_decision_engine,
        build_memory,
        build_tool_registry,
    )
    from maxim.simulation.bridge import SimulationBridge
    from maxim.simulation.conversational_source import ConversationalSource
    from maxim.simulation.introspection import Observer
    from maxim.simulation.tools import (
        AnalyzeResultsTool,
        CheckCompletionTool,
        DamageComponentTool,
        ExtendSimulationTool,
        FinishSimulationTool,
        InjectPainTool,
        InspectAUTTool,
        ObserveActionsTool,
        OrchestratorActorTool,
        SendMessageTool,
        SetEntitySensorTool,
        SimRespondTool,
        SpawnSubSimulationTool,
    )

    start_time = time.time()

    # ── HANDLE seam (a): adopt an injected persistent agent EARLY ────────
    # Validation is loud + first so a mis-built instance fails before any
    # heavy construction (LLM router, sandbox). The adopted bindings replace
    # the sim_aut factory path below.
    _adopted: _AdoptedAgent | None = None
    if persistent_agent is not None:
        if entity_ref is not None:
            raise ValueError(
                "entity_ref is incompatible with persistent_agent — a persistent agent owns its "
                "embodiment (declare it at AgentConfig.embodiment_ref when building the handle)"
            )
        _adopted = _adopt_persistent_agent(persistent_agent)
    _aut_agent_id = _adopted.agent_id if _adopted is not None else "sim_aut"

    # Register well-known sim agent nicknames for display logging.
    # Must happen early — before any sim_log calls that might carry agent_id.
    from maxim.simulation.sim_logger import register_agent_nickname, sim_agent_context

    register_agent_nickname(_aut_agent_id, "AUT")
    register_agent_nickname("sim_orchestrator", "Orch")

    # Plan 4 follow-up (2026-04-14): generate session_id AT ENTRY so
    # every LLMWorker constructed downstream can thread it into its
    # request_context dict. Previously this id was created lazily in
    # ``build_report`` after the sim finished, which was too late —
    # every peer_backend_call event during the sim's lifetime logged
    # session_id=null. The same ``time.strftime`` timestamp is forwarded
    # to ``build_report(session_id=...)`` later so the sim directory
    # name matches the session_id in the log trace; cross-correlating
    # report files with JSONL events is now a string-equality match
    # instead of a "figure out the right timestamp window" exercise.
    # Matches the pattern already in ``research_orchestrator.py:73``.
    session_id = time.strftime("%Y%m%d_%H%M%S")

    # ── Shared stop event ────────────────────────────────────────────────
    stop_event = threading.Event()

    # Reset the process-wide LLM cancellation primitive. If a previous sim
    # in the same Python process requested shutdown (e.g., this is a
    # --continuous run or a long-lived REPL invoking multiple sims), the
    # event would still be set and the new sim's LLM calls would bail out
    # immediately. Clearing at entry makes successive sims safe.
    try:
        from maxim.models.language.cancellation import reset_shutdown

        reset_shutdown()
    except Exception as e:
        logger.debug("Failed to reset LLM cancellation at sim start: %s", e)

    # ── Shared LLM router (single model, alternating inference) ──────────
    # Routed through the multi-LLM factory so sim respects per-lane assignments
    # (capability-driven profiles, env overrides, remote URLs, safety gates).
    llm_router, _lane_manager = build_primary_router(logger=logger)
    if llm_router is None:
        # Factory returned nothing → fall back to the default global config path.
        llm_config = load_llm_config()
        if llm_config.enabled:
            llm_router = LLMRouter(llm_config)
    if llm_router is not None:
        llm_router.warmup()
        logger.info("Shared LLM router initialized")

    # ── Simulation bridge ────────────────────────────────────────────────
    # Substrate-primary per-turn action budget (apparatus standard S6; the
    # Exp 48 thrashing fix). Opt-in via MAXIM_SUBSTRATE_ACTIONS_PER_TURN;
    # unset = unbounded (the pre-fix stopwatch regime: actions/turn =
    # narrator wall-clock ÷ 0.5 s, machine-dependent). Logged here so every
    # run's log states the apparatus configuration.
    from maxim.simulation.bridge import read_substrate_actions_per_turn_env

    _substrate_budget = read_substrate_actions_per_turn_env()
    if _substrate_budget is not None and aut_mode == "substrate-primary":
        logger.info(
            "substrate-primary action budget: %d action(s) per sim turn (MAXIM_SUBSTRATE_ACTIONS_PER_TURN)",
            _substrate_budget,
        )
    elif _substrate_budget is not None:
        # Loud-misconfig norm (review fold): the env is set but the bound
        # only applies to substrate-primary — say so instead of silently
        # ignoring it.
        logger.info(
            "MAXIM_SUBSTRATE_ACTIONS_PER_TURN=%d set but aut_mode=%r — budget applies only to substrate-primary; ignored",
            _substrate_budget,
            aut_mode,
        )
    bridge = SimulationBridge(
        response_timeout=response_timeout,
        stop_event=stop_event,
        aut_mode=aut_mode,
        substrate_actions_per_turn=_substrate_budget,
    )

    # ── Wait for LLM to be ready (avoid cold-start stale drops) ────────
    if llm_router is not None:
        logger.info("Waiting for LLM model to load...")
        llm_router.wait_ready(timeout=120.0)
        logger.info("LLM ready")

    # ── Orchestrator percept source (receives goal + user commands) ──────
    orchestrator_source = ConversationalSource()

    # ── Ensure agent runtime directories exist ─────────────────────────
    os.makedirs(os.path.join("data", "agents", "MaximAgent", "runtime"), exist_ok=True)

    # ── Simulation sandbox ───────────────────────────────────────────────
    sim_workspace = Path("data") / "sim_sandbox"
    sim_workspace.mkdir(parents=True, exist_ok=True)
    sim_tmpdir = Path(
        tempfile.mkdtemp(
            prefix=f"sim_agent_{time.strftime('%Y%m%d_%H%M%S')}_",
            dir=str(sim_workspace),
        )
    )

    # Enable sim logging (always persist to JSONL; terminal traces if --debug)
    try:
        from maxim.simulation.sim_logger import enable_sim_logging

        log_path = str(sim_workspace / f"sim_agent_{time.strftime('%Y%m%d_%H%M%S')}.jsonl")
        enable_sim_logging(log_path=log_path, debug=debug)
    except Exception as e:
        logger.warning("Failed to enable sim logging — sim will run but no JSONL trace: %s", e)

    # Build AUT pain bus + sandbox together. The pain bus MUST exist
    # before the sandbox so PainTriggerLayer can route signals; this
    # helper enforces that ordering and is independently testable.
    sim_sandbox, sandbox_root, aut_pain_bus = _setup_sim_sandbox(
        backend=sandbox_backend,
        image=sandbox_image,
        network=sandbox_network,
        populate=not no_sim_env,
        announce=True,
        # HANDLE seam (a): an adopted agent's own bus (with its learners)
        # carries sandbox pain; None keeps today's build-here behavior.
        pain_bus=_adopted.pain_bus if _adopted is not None else None,
    )

    # ── Build AUT pipeline ───────────────────────────────────────────────
    from maxim.environment.filesystem_env import FileSystemEnv
    from maxim.runtime.state import RuntimeState

    aut_env = FileSystemEnv(str(sim_tmpdir))
    aut_state = RuntimeState()
    aut_state.data["mode"] = "active"
    aut_state.data["in_simulation"] = True
    aut_state.data["active_goal"] = goal
    aut_memory = build_memory()

    # Enable bash for the AUT in simulation mode.
    # The AUT's BashTool checks MAXIM_ALLOW_BASH env var; without it, every
    # bash call fails with "BashTool disabled" even though autonomy allows it.
    # Simulation mode is sandboxed (tmpdir + FearGatedExecutor), so bash is safe.
    # NOT set for an adopted persistent agent: bash is deregistered during the
    # campaign anyway, and the env var outlives the sim — arming the persistent
    # agent's (CWD-scoped, unsandboxed) bash for later Talk-mode turns.
    if _adopted is None:
        os.environ.setdefault("MAXIM_ALLOW_BASH", "1")

    # Constrain AUT filesystem tools to sandbox tmpdir (if available)
    sandbox_dirs = [sandbox_root, str(sim_tmpdir)] if sandbox_root else None

    # Give the AUT a ResponseOutput so RespondTool is registered.
    # Without it, LLM timeout fallbacks (which generate respond actions)
    # fail with "Tool not registered: respond".
    aut_response_output = None
    try:
        from maxim.utils.response_output import ResponseOutput

        aut_response_output = ResponseOutput(sandbox_path=str(sim_tmpdir))
    except Exception as e:
        logger.debug("Failed to create ResponseOutput for AUT: %s", e)

    # PromptHandler: routes `request_interaction` tool calls to the user.
    # When --interactive is on, use SimPromptHandler so the stdin reader
    # coordinates input (avoids two threads fighting over stdin).
    # The tool itself gates on sim_logger.should_prompt, so it's safe
    # to pass unconditionally.
    _sim_prompt_handler = None
    try:
        from maxim.simulation.sim_logger import get_interactive_mode as _get_im
        from maxim.simulation.sim_logger import InteractiveMode as _IM

        if _get_im() == _IM.ON:
            from maxim.interactive.prompts import SimPromptHandler

            _sim_prompt_handler = SimPromptHandler(stop_event=stop_event)
            aut_prompt_handler = _sim_prompt_handler
            # Gate the bridge so orchestrator waits for user to answer prompts
            bridge._prompt_gate = _sim_prompt_handler
        else:
            from maxim.interactive.prompts import create_handler

            aut_prompt_handler = create_handler("auto")
    except Exception as _ph_exc:
        logger.debug("PromptHandler unavailable for AUT: %s", _ph_exc)
        aut_prompt_handler = None

    if _adopted is not None:
        # HANDLE seam (a), branch 4: the campaign runs on the PERSISTENT
        # agent's registry (its executor is bound to it — a fresh registry
        # would dispatch nothing). Sim/DM tools registered below are leased:
        # the lease snapshot was taken at adoption, restore happens at
        # shutdown so the agent's registry returns to its pre-campaign state.
        aut_registry = _adopted.registry
        # respond/speak are how SimulationBridge.send_and_wait collects the
        # AUT's reply text; the handle's registry (built without a
        # response_output) lacks them, so every DM turn would silently read
        # back None. Registered AFTER the lease snapshot → campaign-scoped,
        # dropped at restore. (Review fold: Executor #1 / Architecture #5.)
        if aut_response_output is not None:
            try:
                from maxim.tools.response import RespondTool, SpeakTool

                aut_registry.register(RespondTool(aut_response_output))
                aut_registry.register(SpeakTool(aut_response_output))
            except Exception as e:
                logger.warning("Failed to lease respond/speak onto adopted registry: %s", e)
    else:
        aut_registry = build_tool_registry(
            operational_mode="active",
            allowed_dirs_override=sandbox_dirs,
            response_output=aut_response_output,
            prompt_handler=aut_prompt_handler,
        )
    # Inject user-registered tools from maxim.register_tool() / @maxim.tool
    from maxim.api import _inject_pending_tools

    _inject_pending_tools(aut_registry)

    aut_decision_engine = build_decision_engine()
    aut_agent = MaximAgent()

    # Bridge user event subscriptions to the AUT agent's bus
    if hasattr(aut_agent, "_bus"):
        from maxim.api import _bridge_event_subscriptions

        _bridge_event_subscriptions(aut_agent._bus)

    # AUT runs AUTONOMOUS — no human confirmation prompts (SUPERVISED would
    # deadlock because stdin is captured by the orchestrator's reader thread).
    # FearGatedExecutor is wired below to gate all tool calls through FearAgent.
    aut_autonomy = AutonomyController(
        initial_level=AutonomyLevel.AUTONOMOUS,
        supervision_policy=SupervisionPolicy(
            allowed_tools={
                "respond",
                "speak",
                "read_file",
                "list_directory",
                "write_file",
                "edit_file",
                "glob",
                "code_search",
                "bash",
                "execute_file",
                "run_tests",
                # Narrative tools (sim-only)
                "say",
                "think",
                # Introspection tools
                "memory_recall",
                "predict_outcome",
                "causal_links",
                "pain_history",
                "temporal_patterns",
                "energy_status",
                "concept_query",
                "similarity_search",
                "system_stats",
                # Interactive tools (gated by should_prompt())
                "request_interaction",
                "display_mode",
                "set_scene",
            },
            forbidden_tools=set(),
            min_confidence_autonomous=0.3,
        ),
    )

    # Build AUT's energy tracking (wired to LLMWorker for real token data)
    aut_energy_registry = None
    try:
        from maxim.energy.registry import EnergyRegistry
        from maxim.energy.llm_tracker import LLMEnergyTracker

        aut_energy_registry = EnergyRegistry()
        aut_energy_registry.register(LLMEnergyTracker())
        logger.info("AUT energy tracking enabled")
    except Exception as e:
        logger.debug("AUT energy tracking not available: %s", e)

    # ── AUT agent construction via AgentFactory (F3 migration) ─────────
    # Replaces ~90 lines of hand-rolled bio-stack + cerebellum construction.
    # The factory composes build_bio_stack (bio-pipeline) + build_executor
    # (tool execution + ToolPainBridge) + optional FearGatedExecutor into a
    # single create_full_agent call. Sim-specific wiring (pain layers,
    # DefaultNetwork, tracers, introspection tools) stays below.
    #
    # ComponentRegistry must be created before the factory call so
    # build_executor can instantiate the entity and register affordance tools.
    aut_component_registry = None
    if entity_ref is not None:
        from maxim.embodiment.component_registry import ComponentRegistry

        aut_component_registry = ComponentRegistry()
        logger.info("AUT ComponentRegistry created for entity_ref=%r", entity_ref)

    from maxim.runtime.agent_factory import AgentConfig, AgentFactory

    # pain_bus decision for executor subscription:
    # - entity_ref is None: with_pain_bridge=False → pain_bus not passed to
    #   executor. Out-of-band pain→NAc is handled by create_pain_nac_subscriber
    #   on aut_pain_bus. Bridge still constructed for direct attribution
    #   (record_tool_complete / record_tool_embodiment_failure).
    # - entity_ref is set: with_pain_bridge=True → pain_bus passed to executor.
    #   build_executor precondition requires a live bus for Embodiment._publish_pain.
    # with_fear_gate=False — sim wraps FearGatedExecutor AFTER pain
    # layers (PainInterceptor + AnticipatoryPain) so the fear gate is
    # outermost. The factory wraps fear gate directly on the executor
    # which would put it under the pain layers (wrong order).
    if _adopted is not None:
        # HANDLE seam (a), branch 1: ADOPT the live persistent instance —
        # no create_full_agent, no "sim_aut", no sim_tmpdir persistence.
        # Every aut_* binding below derives from this instance, which is
        # what routes campaign episodes into the persistent agent's home.
        _aut_instance = _adopted.instance
    else:
        _aut_config = AgentConfig(
            agent_id="sim_aut",
            role="pc",
            persistence_dir=str(sim_tmpdir),
            with_bio_stack=True,
            with_executor=True,
            with_pain_bridge=entity_ref is not None,
            with_fear_gate=False,
            embodiment_ref=entity_ref,
        )
        _aut_factory = AgentFactory(
            component_registry=aut_component_registry,
            base_data_dir=sim_tmpdir,
        )
        _aut_instance = _aut_factory.create_full_agent(
            _aut_config,
            tool_registry=aut_registry,
            pain_bus=aut_pain_bus,
            fear_llm=llm_router,
        )

    # Extract bio-system references for downstream sim-specific wiring.
    aut_hippocampus = _aut_instance.hippocampus
    aut_nac = _aut_instance.nac
    aut_memory_hub = _aut_instance.memory_hub
    aut_executor = _aut_instance.executor
    # PFC deliberation: ThoughtGate + BioEnrichmentPipeline from BioStack
    # (constructed in build_bio_stack, no longer sim-only).
    _aut_bio_stack = _aut_instance.bio_stack
    aut_bio_enrichment_pipeline = (
        getattr(_aut_bio_stack, "bio_enrichment_pipeline", None) if _aut_bio_stack is not None else None
    )
    _aut_thought_gate = getattr(_aut_bio_stack, "thought_gate", None) if _aut_bio_stack is not None else None

    if aut_memory_hub is not None:
        aut_agent.wire_memory_hub(aut_memory_hub)

    if entity_ref is not None and _aut_instance.embodiment is not None:
        logger.info(
            "AUT Embodiment loaded: entity_ref=%r, pain_bus=injected, affordance tools registered",
            entity_ref,
        )

    # Restore AUT state from previous session if resuming.
    # HANDLE seam (a), branch 2: gated on persistent_agent is None — an
    # adopted agent already restored its live state via auto_load at handle
    # construction; re-loading a session AUT file here would CLOBBER it.
    if persistent_agent is None and resume_session and (aut_hippocampus is not None or aut_nac is not None):
        from maxim.utils.paths import sim_reports as _sim_reports_dir

        prev_dir = _sim_reports_dir() / resume_session
        hippo_path = prev_dir / "aut_hippocampus.json"
        nac_path = prev_dir / "aut_nac.json"
        ec_path = prev_dir / "aut_ec.json"
        atl_path = prev_dir / "aut_atl.json"
        if aut_hippocampus is not None and hippo_path.exists():
            try:
                aut_hippocampus.load(str(hippo_path))
                logger.info("Restored AUT hippocampus from %s (%d memories)", hippo_path, len(aut_hippocampus))
            except Exception as e:
                logger.debug("Failed to restore AUT hippocampus: %s", e)
        if aut_nac is not None and nac_path.exists():
            try:
                # apply_decay=False: sims are tick-anchored (agent_loop
                # §8.5); wall-clock elapsed between a training run and its
                # --resume-sim is the OPERATOR's schedule, not agent-
                # experienced time — decaying here would make resume-based
                # harnesses (Exp 44's tau-hold pre-load) silently lose
                # their held cluster biases and turn the resume gap into
                # an unrecorded experimental variable (review fold,
                # Arch #1 + Exec #2, cross-confirmed).
                aut_nac.load(str(nac_path), apply_decay=False)
                nac_links = sum(len(v) for v in aut_nac._links.values())
                logger.info("Restored AUT NAc from %s (%d links)", nac_path, nac_links)
            except Exception as e:
                logger.debug("Failed to restore AUT NAc: %s", e)
        _aut_ec = aut_memory_hub.ec if aut_memory_hub is not None else None
        if _aut_ec is not None and ec_path.exists():
            try:
                _aut_ec.load(str(ec_path))
                logger.info("Restored AUT EC from %s (%d substrate nodes)", ec_path, len(_aut_ec._substrate_nodes))
            except Exception as e:
                logger.debug("Failed to restore AUT EC: %s", e)
        _aut_atl = aut_memory_hub.atl if aut_memory_hub is not None else None
        if _aut_atl is not None and atl_path.exists():
            try:
                _aut_atl.load(str(atl_path))
                logger.info("Restored AUT ATL from %s", atl_path)
            except Exception as e:
                logger.debug("Failed to restore AUT ATL: %s", e)

    # Attach bio-system tracers based on --debug flags / env vars
    def _env_trace(var: str) -> bool:
        return os.environ.get(var, "").strip().lower() in ("1", "true", "t", "yes", "y", "on")

    if aut_hippocampus is not None and (_env_trace("MAXIM_HIPPO_TRACE") or debug):
        try:
            from maxim.memory.hippo_tracer import HippocampusTracer

            HippocampusTracer(aut_hippocampus)
        except Exception as e:
            logger.debug("Hippo tracer not available: %s", e)

    if aut_nac is not None and (_env_trace("MAXIM_NAC_TRACE") or debug):
        try:
            from maxim.decisions.nac_tracer import NacTracer

            NacTracer(aut_nac)
        except Exception as e:
            logger.debug("NAc tracer not available: %s", e)

    if aut_memory_hub is not None and (_env_trace("MAXIM_ATL_TRACE") or debug):
        try:
            from maxim.memory.atl_tracer import ATLTracer

            atl = getattr(aut_memory_hub, "_atl", None) or getattr(aut_memory_hub, "atl", None)
            if atl is not None:
                ATLTracer(atl)
        except Exception as e:
            logger.debug("ATL tracer not available: %s", e)

    # --- AUT introspection tools ---
    # Give the AUT access to its own cognitive subsystems so it can
    # actively recall memories, predict outcomes, etc. during action
    # selection.  Without these, the AUT has memories but can't query them.
    try:
        from maxim.tools.introspection import (
            MemoryRecallTool,
            PredictOutcomeTool,
            CausalLinksTool,
            TemporalPatternsTool,
            EnergyStatusTool,
            ConceptQueryTool,
            SimilaritySearchTool,
            SystemStatsTool,
        )

        if aut_hippocampus is not None:
            aut_registry.register(MemoryRecallTool(hippocampus=aut_hippocampus))
            logger.info("AUT introspection: memory_recall registered")

        if aut_memory_hub is not None:
            if aut_memory_hub.ec is not None:
                aut_registry.register(SimilaritySearchTool(ec=aut_memory_hub.ec))
            if aut_memory_hub.scn is not None:
                aut_registry.register(TemporalPatternsTool(scn=aut_memory_hub.scn))
            if aut_memory_hub.atl is not None:
                aut_registry.register(ConceptQueryTool(atl=aut_memory_hub.atl))

        if aut_nac is not None:
            aut_registry.register(PredictOutcomeTool(nac=aut_nac))
            aut_registry.register(CausalLinksTool(nac=aut_nac))

        if aut_energy_registry is not None:
            trackers = list(aut_energy_registry._trackers.values()) if hasattr(aut_energy_registry, "_trackers") else []
            energy_tracker = trackers[0] if trackers else None
            if energy_tracker is not None:
                aut_registry.register(EnergyStatusTool(energy_tracker=energy_tracker))

        aut_registry.register(
            SystemStatsTool(
                hippocampus=aut_hippocampus,
                nac=aut_nac,
                ec=aut_memory_hub.ec if aut_memory_hub else None,
                atl=aut_memory_hub.atl if aut_memory_hub else None,
                energy_tracker=None,
                pain_detector=None,
                significance_learner=None,
            )
        )

        logger.info("AUT introspection tools registered")
    except Exception as e:
        logger.debug("Failed to register AUT introspection tools: %s", e)

    # --- AUT narrative tools (sim-only) ---
    # Let the AUT speak in-world, reason explicitly, and examine scene details.
    # ThinkTool gets the BioEnrichmentPipeline for L1 enrichment.
    # NOTE: ThoughtGate + BioEnrichmentPipeline now come from BioStack
    # (constructed in build_bio_stack, extracted above). The dead
    # wire_thought_gate / wire_bio_enrichment calls to ExecAgent are
    # removed — deliberation lives in the agentic loop's PFC cycle.
    if _aut_thought_gate is not None:
        logger.info(
            "AUT ThoughtGate + BioEnrichment from BioStack (refractory=%d, min_score=%.1f)",
            _aut_thought_gate._config.refractory_ticks,
            _aut_thought_gate._config.min_combined_score,
        )

    try:
        from maxim.tools.narrative import ExamineTool, SayTool, ThinkTool

        aut_registry.register(SayTool())
        aut_registry.register(ThinkTool(pipeline=aut_bio_enrichment_pipeline))
        aut_registry.register(ExamineTool(bridge=bridge, hippocampus=aut_hippocampus))
        logger.info("AUT narrative tools registered (say, think, examine)")
    except Exception as e:
        logger.debug("Failed to register AUT narrative tools: %s", e)

    # --- Deregister irrelevant tools in sim mode ---
    # Robot tools return "No live robot connected"; dev tools (bash, git,
    # filesystem editing) are noise that dilutes the LLM's attention away
    # from sim-relevant tools (affordances, narrative, introspection,
    # interaction).  Audit (2026-04-20) found 35+ tools on the AUT — the
    # LLM defaults to safe tools instead of exploring affordances.
    _irrelevant_tools = [
        # Robot-only (no hardware in sim)
        "focus_interests",
        "track_target",
        "move",
        "novelty_track",
        "maxim_command",
        "autonomy_level",
        "mode_switch",
        # Dev tools (sim agents don't write code)
        "bash",
        "git_commit",
        "git_diff",
        "edit_file",
        "execute_file",
        "run_tests",
        "search_code",
        "request_directory_change",
        "glob",
        "read_file",
        "write_file",
    ]
    # When adopted, dropped persistent tools come back at lease restore —
    # the snapshot holds the baseline {name: tool_object} map.
    for _rt in _irrelevant_tools:
        if aut_registry.deregister(_rt):
            logger.debug("Deregistered irrelevant tool from AUT: %s", _rt)

    # --- SEM Tool Discovery: hybrid prompt mode ---
    # Replace per-entity sensor tools with universal sense + sense_tools.
    # Keep top-k goal-relevant affordance tools visible, deactivate the rest.
    _aut_entity_map = None
    if entity_ref is not None and _aut_instance.embodiment is not None:
        from maxim.embodiment.entity_map import EntityMap
        from maxim.tools.discovery import (
            SenseToolsTool,
            SensePresenceTool,
            UniversalSenseTool,
            select_goal_relevant_tools,
        )

        _aut_entity_map = EntityMap()
        _aut_entity_map.register_self(_aut_instance.embodiment.root)

        # Deregister per-entity sensor tools (replaced by universal sense)
        _sensor_tools_removed = 0
        for _tname in list(aut_registry.list_all()):
            if _tname.startswith("sense_") or _tname.startswith("read_"):
                if aut_registry.deregister(_tname):
                    _sensor_tools_removed += 1
        logger.debug("SEM discovery: removed %d per-entity sensor tools", _sensor_tools_removed)

        # Register universal sense + sense_tools + sense_presence as core tools
        aut_registry.register(UniversalSenseTool(entity_map=_aut_entity_map))
        aut_registry.register(
            SenseToolsTool(
                entity_map=_aut_entity_map,
                tool_registry=aut_registry,
                component_index=None,  # wired later if imagination is available
            )
        )
        # sense_presence: imagination_trigger wired later (after trigger construction)
        aut_registry.register(
            SensePresenceTool(
                entity_map=_aut_entity_map,
                imagination_trigger=None,  # wired below after ImaginationTrigger is built
            )
        )

        # Goal-based top-k: keep relevant affordances active, deactivate rest.
        # generate_tools_for_entity registers tools as core (no scene metadata).
        # We need to add scene metadata so deactivate_tool works. Re-register
        # affordance tools as scene-scoped, then deactivate non-top-k ones.
        from maxim.embodiment.tool_bridge import ModulatorAffordanceTool
        from maxim.tools.discovery import mark_goal_selected

        _keep_active = set(select_goal_relevant_tools(goal, _aut_entity_map, aut_registry))
        mark_goal_selected(list(_keep_active))

        # Collect affordance tools and re-register as scene-scoped
        _affordance_tools = []
        for _tname in list(aut_registry.list_all()):
            try:
                _tool = aut_registry.get(_tname)
                if isinstance(_tool, ModulatorAffordanceTool):
                    _affordance_tools.append(_tool)
            except KeyError:
                pass

        if _affordance_tools:
            aut_registry.register_scene_tools(_affordance_tools, "aut_affordances")

        # Deactivate non-top-k affordance tools individually
        _deactivated_count = 0
        for _tool in _affordance_tools:
            if _tool.name not in _keep_active:
                if aut_registry.deactivate_tool(_tool.name):
                    _deactivated_count += 1

        _active_count = len(aut_registry.list())
        _all_tools = list(aut_registry.list_all())
        _active_tools = list(aut_registry.list())
        logger.info(
            "SEM discovery: hybrid prompt mode ��� %d active tools "
            "(%d goal-selected, %d affordance tools deactivated, "
            "sense + sense_tools registered)",
            _active_count,
            len(_keep_active),
            _deactivated_count,
        )
        # Trace: log all registered tools for debugging SEM availability
        try:
            from maxim.simulation.sim_logger import sim_log

            sim_log("SEM_TRACE", f"All registered tools ({len(_all_tools)}): {', '.join(sorted(_all_tools))}")
            sim_log("SEM_TRACE", f"Active tools ({len(_active_tools)}): {', '.join(sorted(_active_tools))}")
            sim_log("SEM_TRACE", f"Goal-selected (top-k): {', '.join(sorted(_keep_active))}")
            sim_log(
                "SEM_TRACE",
                f"Entities: {', '.join(e.name + '(' + e.entity_type + ')' for e in _aut_entity_map.list_entities())}",
            )
            # Log affordances per entity
            for _ent in _aut_entity_map.list_entities():
                for _mod_name, _mod in _ent.modulators.items():
                    _aff_names = list(_mod.affordances.keys())
                    if _aff_names:
                        sim_log(
                            "SEM_TRACE",
                            f"  {_ent.name}.{_mod_name}: affordances={', '.join(_aff_names)}",
                        )
        except Exception:
            pass

    # AUT PainBus subscriptions are now handled by build_bio_stack above
    # (Wave 3: pre-built pain_bus= parameter subscribes standard learners).

    # Build AUT's LLM worker. When --aut-model is set, the AUT gets its
    # own LLMRouter so there's no inference contention and the experiment
    # can isolate memory recall from LLM context window effects.
    #
    # The AUT router uses the same infrastructure as the primary router
    # (peer config, lane backends, etc.) but with a different model profile
    # set via env var override. This ensures the AUT uses the leader's GPU
    # (via peer config) rather than trying to load locally.
    aut_router = llm_router  # default: shared
    if aut_model is not None and llm_router is not None:
        try:
            # Override the infer lane model for this second router build
            old_profile = os.environ.get("MAXIM_LLM_PROFILE")
            os.environ["MAXIM_LLM_PROFILE"] = aut_model
            aut_router, _ = build_primary_router(logger=logger)
            # Restore original profile
            if old_profile is not None:
                os.environ["MAXIM_LLM_PROFILE"] = old_profile
            else:
                os.environ.pop("MAXIM_LLM_PROFILE", None)

            if aut_router is None:
                aut_config = load_llm_config(profile_override=aut_model)
                if aut_config.enabled:
                    aut_router = LLMRouter(aut_config)

            if aut_router is not None:
                aut_router.warmup()
                aut_router.wait_ready(timeout=120.0)
                logger.info("AUT router initialized (model=%s)", aut_model)
            else:
                aut_router = llm_router
        except Exception as e:
            logger.warning("Failed to build AUT router for '%s': %s — falling back to shared", aut_model, e)
            aut_router = llm_router

    aut_llm_worker: LLMWorker | None = None
    if aut_router is not None:
        aut_llm_worker = LLMWorker(
            llm=aut_router,
            stale_threshold_s=30.0 if aut_router is llm_router else 15.0,
            n_ctx=aut_router.n_ctx,
            token_counter=aut_router.get_token_counter(),
            session_id=session_id,
        )
        aut_llm_worker.start()

        # Exp 44 counterfactual capture (DORMANT unless MAXIM_EXP44_CAPTURE_LOG
        # is set). Installs the paired-prompt capture on THIS process's AUT worker
        # — the one place reachable in-process, since the benchmark vehicle
        # subprocesses `maxim --sim`. Gated experiment hook, mirrors how
        # substrate_telemetry is threaded through the sim; never runs in prod.
        _exp44_log = os.environ.get("MAXIM_EXP44_CAPTURE_LOG")
        if _exp44_log:
            try:
                import importlib.util as _ilu
                from pathlib import Path as _P

                _cap_path = _P(__file__).resolve().parents[3] / "scripts" / "exp44" / "capture_paired_prompts.py"
                _spec = _ilu.spec_from_file_location("_exp44_capture", _cap_path)
                if _spec and _spec.loader:
                    _mod = _ilu.module_from_spec(_spec)
                    _spec.loader.exec_module(_mod)
                    _mod.install_capture(aut_llm_worker, _exp44_log)
                    logger.info("Exp44 paired-prompt capture installed -> %s", _exp44_log)
            except Exception as _e:  # capture must never break the sim
                logger.warning("Exp44 capture install failed (continuing): %s", _e)

        # B3: Enable Acting Coach when embodiment tools are available.
        # The coach encourages the agent to explore affordances instead of
        # entering respond loops. Bio-system modulation (NAc valence, pain
        # anticipation, cerebellum predictions) annotates the base directive
        # via existing StructuredContext fields at prompt-build time.
        if entity_ref is not None:
            from maxim.prompts.acting_coach import acting_coach_config_from_env

            aut_llm_worker.acting_coach = acting_coach_config_from_env()
            aut_llm_worker.is_embodied = True

            # E2: Inject entity context into AUT prompt
            if aut_component_registry is not None:
                try:
                    _entity_raw = aut_component_registry.get(entity_ref)
                    aut_llm_worker.entity_spec = _entity_raw.get("entity", _entity_raw)
                except Exception as _e:
                    logger.debug("Entity context injection failed: %s", _e)

    # ── Build orchestrator pipeline ──────────────────────────────────────
    orch_env = FileSystemEnv(str(sim_tmpdir))
    orch_state = RuntimeState()
    orch_state.data["mode"] = "singularity"  # No allowed_tools filter — all registered tools visible
    # NB: data["mode"] above is the RuntimeState RUN-mode; the sim flow-shape
    # label (this function's `mode` param) rides in "strategy" for capture
    # metadata (hippocampus _SnapshotState.strategy) — do not conflate.
    orch_state.data["strategy"] = mode
    orch_memory = build_memory()
    orch_decision_engine = build_decision_engine()

    # Orchestrator bio-stack + executor constructed below via AgentFactory
    # after the orch tool registry is built (the factory needs it).
    orch_agent = MaximAgent()

    # Build a MINIMAL tool registry with ONLY simulation tools.
    # Using build_tool_registry() adds filesystem/bash/code tools that
    # confuse the LLM — it picks familiar tools (glob, bash) instead of
    # simulation tools (send_message). A bare registry forces correct behavior.
    from maxim.simulation.tools import SimToolRegistry

    orch_registry = SimToolRegistry()
    spawn_tool = SpawnSubSimulationTool(
        llm_router=llm_router,
        stop_event=stop_event,
        parent_bridge=bridge,
        sim_tmpdir=str(sim_tmpdir),
        sandbox_dirs=sandbox_dirs,
    )
    _aut_embodiment = getattr(_aut_instance, "embodiment", None) if _aut_instance is not None else None
    orch_registry.register(SendMessageTool(bridge=bridge, embodiment=_aut_embodiment))
    orch_registry.register(ObserveActionsTool(bridge=bridge))
    orch_registry.register(CheckCompletionTool(bridge=bridge, llm=llm_router, goal=goal, continuous=continuous))
    orch_registry.register(AnalyzeResultsTool(bridge=bridge, llm=llm_router))
    orch_registry.register(InjectPainTool(bridge=bridge))
    # DamageComponentTool + SetEntitySensorTool: SEM damage/recovery → PainBus → NAc.
    # OrchestratorActorTool: scene entity affordances against the AUT —
    # writes target_effect deltas through the SEM mechanics path.
    # Only registered when embodiment is active (--embodiment flag).
    if _aut_embodiment is not None:
        orch_registry.register(OrchestratorActorTool(embodiment=_aut_embodiment, entity_map=_aut_entity_map))
        orch_registry.register(DamageComponentTool(embodiment=_aut_embodiment, entity_map=_aut_entity_map))
        orch_registry.register(SetEntitySensorTool(embodiment=_aut_embodiment, entity_map=_aut_entity_map))
    orch_registry.register(spawn_tool)
    orch_registry.register(ExtendSimulationTool(main_bridge=bridge, spawn_tool=spawn_tool))
    orch_registry.register(
        FinishSimulationTool(
            bridge=bridge,
            orchestrator_source=orchestrator_source,
            spawn_tool=spawn_tool,
        )
    )
    orch_registry.register(SimRespondTool())
    aut_introspector = Observer(
        hippocampus=aut_hippocampus,
        nac=aut_nac,
        memory_hub=aut_memory_hub,
        energy_registry=aut_energy_registry,
    )
    orch_registry.register(InspectAUTTool(introspector=aut_introspector))

    # Research tools — available in every mode (record_experiment is
    # useful for any systematic investigation, not just "researcher").
    # Experiment log lives in sim_tmpdir during the run; report.py
    # copies it to the final session directory at save time.
    # Use caller-provided ExperimentLog if given (research protocol passes
    # its log in so Writer/Reviewer read from the same instance — D-0a fix).
    if experiment_log is None:
        try:
            from maxim.simulation.research_tools import ExperimentLog

            experiment_log = ExperimentLog(session_dir=sim_tmpdir)
        except Exception as e:
            logger.debug("ExperimentLog not available: %s", e)
    try:
        from maxim.simulation.research_tools import (
            RecordExperimentTool,
            QueryExperimentsTool,
        )

        if experiment_log is not None:
            orch_registry.register(RecordExperimentTool(experiment_log))
            orch_registry.register(QueryExperimentsTool(experiment_log))
            logger.info("Research tools registered (record_experiment, query_experiments)")
    except Exception as e:
        logger.debug("Research tools not available: %s", e)

    # Register simulation tools in TOOL_DESCRIPTIONS so the agent loop
    # knows to trigger followup LLM calls after tool execution.
    # Without this, the loop doesn't submit new context after send_message
    # completes, causing the orchestrator to idle indefinitely.
    from maxim.modes.definitions import TOOL_DESCRIPTIONS

    TOOL_DESCRIPTIONS.update(
        {
            "send_message": {
                "description": "Send a message to the agent under test and wait for its response. "
                "This is your PRIMARY tool for interacting with the AUT. Returns the "
                "agent's response text, all actions taken, and any blocked actions.",
                "params": {"text": "The message to send to the agent under test"},
                "example": '{"tool_name": "send_message", "params": {"text": "What do you remember about our last conversation?"}}',
                "followup_type": "process",
            },
            "observe_actions": {
                "description": "Read the full action history from the simulation. Use to review "
                "what the agent has done across all turns.",
                "params": {"since_index": "(optional) Only return actions after this index"},
                "followup_type": "process",
            },
            "check_completion": {
                "description": "Check if your simulation goal has been achieved based on actions so far.",
                "followup_type": "process",
            },
            "analyze_results": {
                "description": "Analyze the simulation history for patterns — blocked actions, tool usage, "
                "safety gate effectiveness.",
                "params": {"focus": "(optional) 'safety', 'behavior', or 'all'"},
                "followup_type": "process",
            },
            "inspect_aut": {
                "description": "Inspect the agent-under-test's internal state: memory, causal links, "
                "pain history, energy status.",
                "params": {
                    "tool_name": "Which introspection tool to call (memory_recall, causal_links, etc.)",
                    "tool_params": "(optional) Parameters for the introspection tool",
                },
                "followup_type": "process",
            },
            "finish_simulation": {
                "description": "End the simulation. Call when your goal is achieved or you're done testing.",
                "params": {"reason": "Why you're ending the simulation", "summary": "(optional) Summary of findings"},
                "followup_type": None,
            },
            "set_entity_sensor": {
                "description": "Set an agent body sensor to a value. Use for healing, feeding "
                "(reduce hunger to 0), resting (restore stamina to 1), environmental changes, "
                "or any non-combat sensor modification. The agent feels the change.",
                "params": {
                    "sensor": "Which sensor: health, stamina, hunger, visibility, etc.",
                    "value": "Target value 0.0-1.0",
                    "source": "What caused the change (e.g., 'healing_potion', 'food', 'rest')",
                },
                "example": '{"tool_name": "set_entity_sensor", "params": {"sensor": "hunger", "value": 0.0, "source": "food"}}',
                "followup_type": "process",
            },
            "inject_pain": {
                "description": "Send a pain signal to the agent to test proprioceptive handling.",
                "params": {"pain_type": "(optional) Type of pain signal", "intensity": "(optional) 0.0-1.0"},
                "followup_type": "process",
            },
            "damage_component": {
                "description": "Apply physical damage to a specific body part of the agent. "
                "Use EVERY TIME a scene entity attacks or the environment causes harm. "
                "Specify WHICH body part takes the hit (head, torso, wing, leg, arm, etc.). "
                "This makes damage REAL — the body part's integrity drops, pain fires, "
                "and the agent learns which body parts are vulnerable.",
                "params": {
                    "component": "Which body part to damage (e.g., 'head', 'wing', 'torso', 'leg'). Default: torso",
                    "amount": "Damage amount 0.0-1.0 (default: 0.1). 0.1=light, 0.3=heavy, 0.5=devastating",
                    "source": "What caused the damage (e.g., 'dragon_fire_breath', 'falling_rocks')",
                },
                "example": '{"tool_name": "damage_component", "params": {"component": "wing", "amount": 0.3, "source": "sword_slash"}}',
                "followup_type": "process",
            },
            "respond": {
                "description": "NOT AVAILABLE. Use send_message instead.",
                "followup_type": "process",  # Error triggers re-think
            },
            "spawn_sub_simulation": {
                "description": "Run an isolated sub-simulation with a fresh agent. The sub-agent "
                "starts clean with no memory. Use for independent measurements. "
                "Sub-agent stays alive for extend_simulation follow-ups.",
                "params": {"goal": "The sub-simulation objective"},
                "example": '{"tool_name": "spawn_sub_simulation", "params": {"goal": "test code execution safety"}}',
                "followup_type": "process",
            },
            "extend_simulation": {
                "description": "Continue with a new objective on the current agent (keeps context). "
                "If a sub-simulation is active, extends that. Use to go deeper on findings.",
                "params": {"goal": "The new objective to add"},
                "example": '{"tool_name": "extend_simulation", "params": {"goal": "now try writing to that file"}}',
                "followup_type": "process",
            },
            "record_experiment": {
                "description": "Record a structured experiment entry with hypothesis, method, result, "
                "and conclusion. Returns a UMR reference for cross-agent citation.",
                "params": {
                    "hypothesis": "What you predicted",
                    "method": "What you did",
                    "result": "What happened (include data)",
                    "conclusion": "What it means",
                },
                "followup_type": "process",
            },
            "query_experiments": {
                "description": "Search the experiment log by keyword or tag. Returns matching "
                "experiments with UMR references.",
                "params": {
                    "keyword": "(optional) Search hypothesis, method, result, conclusion",
                    "tag": "(optional) Filter by tag",
                },
                "followup_type": "process",
            },
        }
    )

    # Autonomy: allow ALL tools through to the executor.
    # SimToolRegistry handles unknown tools by returning an error+redirect,
    # which triggers a followup LLM call. If we filter at the autonomy level,
    # unknown tools get silently dropped and the orchestrator stalls.
    orch_autonomy = AutonomyController(
        initial_level=AutonomyLevel.AUTONOMOUS,
        supervision_policy=SupervisionPolicy(
            allowed_tools=set(),  # Empty = allow all (SimToolRegistry redirects unknowns)
            forbidden_tools=set(),
            min_confidence_autonomous=0.3,
        ),
    )

    # Build orchestrator's LLM worker (shares the same router)
    orch_llm_worker: LLMWorker | None = None
    if llm_router is not None:
        orch_llm_worker = LLMWorker(
            llm=llm_router,
            stale_threshold_s=60.0,  # High threshold: orchestrator waits for shared LLM
            n_ctx=llm_router.n_ctx,
            token_counter=llm_router.get_token_counter(),
            session_id=session_id,
        )
        orch_llm_worker.start()

    # ── PainDetector (Phase 0b — bio-stack activation) ─────────────────
    aut_pain_detector = None
    try:
        from maxim.proprioception.pain import PainDetector

        aut_pain_detector = PainDetector()
        # Wire to introspector for benchmark_snapshot() pain_stats
        aut_introspector._pain_detector = aut_pain_detector
        logger.info("AUT PainDetector active in sim mode")
    except Exception as e:
        logger.debug("AUT PainDetector creation failed: %s", e)

    # ── DefaultNetwork (Phase 0b — bio-stack activation) ──────────────
    # Migrated to build_default_network per
    # docs/plans/archive/default_network_unification.md Gap C.
    # maxim=None — sim has no robot, but DN still provides pain detection.
    # pain_bus=aut_pain_bus — injected bus closes Gap B (split subscriber
    # ownership). The bus already has hippocampus + NAc subscribers from
    # build_pain_bus (line ~619/622 above).
    aut_default_network = None
    try:
        from maxim.default_network import DefaultNetworkConfig
        from maxim.runtime.bootstrap import build_default_network

        aut_default_network = build_default_network(
            nac=aut_nac,
            maxim=None,
            pain_bus=aut_pain_bus,
            config=DefaultNetworkConfig(
                enabled=True,
                publish_actions=False,  # no bus in sim
                fear_gate_enabled=False,  # FearAgent wired separately
            ),
        )
        if aut_default_network is not None:
            logger.info(
                "AUT DefaultNetwork active in sim mode (pain_bus=%s)", "injected" if aut_pain_bus else "internal"
            )
    except Exception as e:
        logger.debug("AUT DefaultNetwork creation failed: %s", e)

    # ── Orchestrator executor via AgentFactory (F3 migration) ───────────
    # The orch gets its own isolated bio-stack with a separate NAc for
    # future adaptive orchestration. Persistence at ~/.maxim/orchestrator/
    # (not CWD-relative — agent longevity review found fragmentation risk).
    # with_pain_bridge=False: orch sim tools (send_message, observe_actions,
    # etc.) never produce SEM embodiment pain. Bridge is still constructed
    # for direct attribution (gated on nac), just not subscribed to pain_bus.
    from maxim.utils.paths import data_home as _data_home

    _orch_config = AgentConfig(
        agent_id="sim_orchestrator",
        role="npc",
        persistence_dir=str(_data_home() / "orchestrator"),
        with_bio_stack=True,
        with_executor=True,
        with_pain_bridge=False,
        with_fear_gate=False,
        # Write-but-don't-read (review fold, Arch #2): shutdown() keeps
        # persisting orch state for the future "Phase 3" cross-session
        # orchestration work, but the orch must NOT restore it — reading
        # an unaudited, ever-accumulating ~/.maxim/orchestrator home into
        # every sim run would make the orchestrator/narrator a cross-run
        # confound (the narrator-state-confound class), and ~/.maxim is
        # shared across worktrees, so concurrent experiment sessions
        # would cross-contaminate through it. Flip to True only as part
        # of a deliberate, tuned Phase 3 (see the hippocampus NOTE at the
        # run_agentic_loop call below).
        load_persisted=False,
    )
    _orch_factory = AgentFactory(base_data_dir=_data_home() / "orchestrator")
    _orch_instance = _orch_factory.create_full_agent(
        _orch_config,
        tool_registry=orch_registry,
    )
    orch_executor = _orch_instance.executor

    # Wrap with PainInterceptor (Layer 2 — consequence pain after execute)
    # and AnticipatoryPainExecutor (Layer 1 — perceived pain before execute).
    # Together: perceived pain predicts, consequence pain confirms, NAc learns.
    aut_perceived_pain_assessor: Any = None
    try:
        from maxim.proprioception.perceived_pain import PerceivedPainAssessor
        from maxim.runtime.pain_interceptor import (
            AnticipatoryPainExecutor,
            PainInterceptorExecutor,
        )

        aut_executor = PainInterceptorExecutor(
            aut_executor,
            pain_bus=aut_pain_bus,
        )
        aut_perceived_pain_assessor = PerceivedPainAssessor(
            nac=aut_nac,
            pain_bus=aut_pain_bus,
        )
        aut_executor = AnticipatoryPainExecutor(
            aut_executor,
            assessor=aut_perceived_pain_assessor,
        )
        # Also wire percept-level anxiety: the AUT feels anticipatory
        # pain when it RECEIVES a message containing sensitive paths,
        # not just when it tries to act on them.
        bridge.percept_anxiety_hook = aut_perceived_pain_assessor.assess_text
        logger.info("AUT pain layers wired: action-anticipation (L1) + consequence (L2) + percept-anxiety (L1b)")
    except Exception as e:
        logger.warning("Failed to wire pain-layer executors: %s", e)

    # Wrap AUT executor with FearGatedExecutor for safety review.
    # NOTE: this MUST come after ToolPainBridge wiring so the bridge
    # lives on the inner executor where record_tool_start/complete
    # are actually invoked.
    try:
        from maxim.agents.fear_agent import FearAgent
        from maxim.runtime.fear_gate import FearGatedExecutor

        llm_for_fear = llm_router  # Share LLM for code analysis
        fear_agent = FearAgent(llm=llm_for_fear)
        aut_executor = FearGatedExecutor(aut_executor, fear_agent)
        logger.info("AUT FearGatedExecutor active — all tool calls reviewed by FearAgent")
    except Exception as e:
        logger.warning("Failed to wire FearGatedExecutor for AUT: %s", e)

    # NOTE: Pre-Wave-2, aut_memory_hub.connect(fear_agent=...) was called
    # here.  build_memory_hub now calls .connect() internally, so the
    # three always-created bridges (PlanHistory, Escalation, Fear) are
    # already alive.  fear_agent is stored by .connect() but never read
    # by any bridge — the FearCircuitBridge uses nac/ec/hippocampus
    # directly.  See memory_hub_unification.md audit.

    # ── Imagination trigger (I1+I2 wiring) ──────────────────────────────
    # When an entity_ref is present, the AUT has a ComponentRegistry.
    # Build a ComponentIndex + ImaginationTrigger so the AUT can imagine
    # novel entities it encounters during the simulation.
    # Universal imagination gate (MAXIM_DISABLE_IMAGINATION): the single master
    # switch for ALL imagination surfaces. ImaginationTrigger._enabled is
    # already respected by BOTH the per-turn design path (trigger.py::process,
    # ~L593) AND the world-builder manifest (trigger.py::process_manifest,
    # ~L870) — so gating the trigger at construction kills both with one flag,
    # and we ALSO skip the generate_scene_manifest LLM call below to avoid
    # burning a call whose result process_manifest would just discard.
    # Controlled experiments (Exp 44) set this so a controlled arc presents
    # ONLY its declared entities — no improvised distractors. Does NOT touch
    # the generative NARRATOR prose (a separate subsystem); use the fixture
    # path for full scene determinism. Experiment/harness toggle (env, not
    # config, per the carve-out). Truthy via the canonical parser.
    from maxim.prompts.cluster_bias_annotation import annotation_disabled_via_env as _adve

    _imagination_off = _adve(os.environ.get("MAXIM_DISABLE_IMAGINATION"))

    aut_imagination_trigger: Any = None
    if aut_component_registry is not None:
        try:
            from maxim.embodiment.component_index import ComponentIndex
            from maxim.imagination.cache import ImaginationCache
            from maxim.imagination.designer import ImaginationDesigner
            from maxim.imagination.trigger import ImaginationTrigger
            from maxim.simulation.entity_designer import EntityDesigner

            _aut_component_index = ComponentIndex(aut_component_registry)
            _aut_entity_designer = EntityDesigner(
                component_registry=aut_component_registry,
                llm_router=llm_router,
            )
            _aut_imagination_designer = ImaginationDesigner(
                _aut_entity_designer,
                component_index=_aut_component_index,
            )
            # Resolve the LinguisticEncoder for affordance substrate encoding.
            # Lives in MemoryHub (wired by _wire_substrate_encoder).
            _aut_encoder = getattr(aut_memory_hub, "_encoder", None) if aut_memory_hub is not None else None

            aut_imagination_trigger = ImaginationTrigger(
                component_index=_aut_component_index,
                component_registry=aut_component_registry,
                designer=_aut_imagination_designer,
                cache=ImaginationCache(),
                tool_registry=aut_registry,
                default_network=aut_default_network,
                encoder=_aut_encoder,
                agent_id=_aut_agent_id,
                enabled=not _imagination_off,  # universal MAXIM_DISABLE_IMAGINATION gate
            )

            # Wire ComponentIndex + affordance transfer deps into SenseToolsTool
            _aut_nac = aut_memory_hub.nac if aut_memory_hub is not None else None
            _aut_atl = aut_memory_hub.atl if aut_memory_hub is not None else None
            try:
                _sense_tools = aut_registry.get("sense_tools")
                _sense_tools._component_index = _aut_component_index
                _sense_tools._atl = _aut_atl
                _sense_tools._agent_id = _aut_agent_id
                # NAc is already wired at construction if passed, but
                # the tool was constructed with nac=None — patch it now.
                if _sense_tools._nac is None and _aut_nac is not None:
                    _sense_tools._nac = _aut_nac
            except KeyError:
                pass  # sense_tools not registered (no embodiment)

            # Pass entity_map to ImaginationTrigger for populating on design
            if _aut_entity_map is not None:
                aut_imagination_trigger._entity_map = _aut_entity_map

            # Wire ImaginationTrigger + affordance transfer deps into SensePresenceTool
            try:
                _presence_tool = aut_registry.get("sense_presence")
                _presence_tool._imagination_trigger = aut_imagination_trigger
                _presence_tool._nac = _aut_nac
                _presence_tool._atl = _aut_atl
                _presence_tool._agent_id = _aut_agent_id
            except KeyError:
                pass

            # Wire ComponentIndex + ComponentRegistry + agent_id into BioEnrichmentPipeline
            if aut_bio_enrichment_pipeline is not None:
                aut_bio_enrichment_pipeline._component_index = _aut_component_index
                aut_bio_enrichment_pipeline._component_registry = aut_component_registry
                aut_bio_enrichment_pipeline._agent_id = _aut_agent_id

            # Wire percept reflex system into BioEnrichmentPipeline.
            # Reflexes detect keyword patterns in percept text and invoke
            # damage_component / set_entity_sensor BEFORE the LLM deliberates.
            # Replaces the auto-damage hack that was in SendMessageTool.
            if aut_bio_enrichment_pipeline is not None and _aut_embodiment is not None:
                try:
                    from maxim.embodiment.reflex import load_archetype_reflexes, ReflexRegistry

                    _archetype = None
                    if aut_component_registry is not None and entity_ref is not None:
                        try:
                            _spec = aut_component_registry.get(entity_ref)
                            _archetype = _spec.get("component", {}).get("archetype")
                        except Exception:
                            pass

                    if _archetype:
                        _reflex_specs = load_archetype_reflexes(_archetype)
                        if _reflex_specs:
                            # Closure must look up root at evaluation time,
                            # not capture it — root may change during sim
                            # (entity acquisition, imagination replacement).
                            _emb_ref = _aut_embodiment

                            def _get_component_integrity(name: str) -> float:
                                _root = _emb_ref.root if _emb_ref is not None else None
                                if _root is None:
                                    return 1.0
                                comp = _root.get_component(name)
                                if comp is not None and hasattr(comp, "compute_integrity"):
                                    return comp.compute_integrity()
                                return 1.0

                            _reflex_registry = ReflexRegistry(
                                _reflex_specs,
                                get_component_integrity=_get_component_integrity,
                            )
                            aut_bio_enrichment_pipeline._reflex_registry = _reflex_registry

                            # Wire tool instances for reflex dispatch
                            _reflex_damage = DamageComponentTool(embodiment=_aut_embodiment, entity_map=_aut_entity_map)
                            _reflex_sensor = SetEntitySensorTool(embodiment=_aut_embodiment, entity_map=_aut_entity_map)
                            aut_bio_enrichment_pipeline._reflex_damage_tool = _reflex_damage
                            aut_bio_enrichment_pipeline._reflex_sensor_tool = _reflex_sensor

                            # Wire entity root for latent affordance surfacing.
                            # Must look up at evaluation time (not capture) —
                            # same live-lookup pattern as integrity closure.
                            aut_bio_enrichment_pipeline._entity_root = _emb_ref.root

                            logger.info(
                                "Percept reflex system wired: archetype=%s, %d reflexes",
                                _archetype,
                                len(_reflex_specs),
                            )
                except Exception as e:
                    logger.warning("Reflex system wiring failed: %s", e)

            # Encode self-entity affordances through the substrate path.
            # The agent's own body affordances form substrate concepts just
            # like scene entities — enabling self-affordance concept formation.
            if _aut_encoder is not None and _aut_entity_map is not None:
                from maxim.imagination.trigger import encode_entity_affordances

                for _self_entity in _aut_entity_map.list_self_entities():
                    encode_entity_affordances(_self_entity, _aut_encoder, agent_id=_aut_agent_id)

            logger.info("AUT ImaginationTrigger wired (ComponentIndex + EntityDesigner + DN arousal gate)")
            try:
                from maxim.simulation.sim_logger import sim_log

                sim_log("SEM_TRACE", f"ImaginationTrigger ACTIVE — enabled={aut_imagination_trigger._enabled}")
            except Exception:
                pass
        except Exception as e:
            logger.warning("ImaginationTrigger construction failed: %s", e)
            try:
                from maxim.simulation.sim_logger import sim_log

                sim_log("SEM_TRACE", f"ImaginationTrigger FAILED: {e}")
            except Exception:
                pass

    # ── Scene manifest pre-trigger (Phase 1: SEM World Enrichment) ───────
    # Before the first turn, generate a scene entity inventory from the
    # goal and resolve all entities through the imagination pipeline.
    # This runs AFTER ImaginationTrigger wiring (EntityMap, ComponentIndex,
    # designer all constructed) and BEFORE the AUT thread launch.
    #
    # Fix B fold (2026-05-27, pre-merge review BLOCK 1, cross-confirmed by
    # both review lenses): gate on ``fixture_path is None`` so the generative-
    # narrator pre-trigger does NOT double-fire alongside Fix B's fixture
    # pre-trigger at ``FixtureDrivenOrchestrator._substrate_pretrigger``.
    # Pre-fold, BOTH hookups fired when fixture_path was set — burning two
    # manifest LLM calls per fixture run AND polluting the JSONL trace with
    # both ``scene_id="pre_trigger"`` and ``scene_id="fixture_pretrigger"``.
    # The two call sites now have disjoint conditions (this one handles the
    # generative path; FixtureDrivenOrchestrator handles the fixture path).
    # Skip the world-builder manifest LLM call when imagination is gated off
    # (process_manifest would early-return on _enabled anyway; this also avoids
    # burning the manifest LLM call). See the MAXIM_DISABLE_IMAGINATION note at
    # the ImaginationTrigger construction above.
    if fixture_path is None and aut_imagination_trigger is not None and llm_router is not None and _imagination_off:
        from maxim.simulation.sim_logger import sim_log

        sim_log("SEM_TRACE", "Scene manifest pre-trigger: skipped via MAXIM_DISABLE_IMAGINATION (universal gate)")
    elif fixture_path is None and aut_imagination_trigger is not None and llm_router is not None:
        try:
            from maxim.simulation.narrator import generate_scene_manifest
            from maxim.simulation.sim_logger import sim_log

            # W2 Hookup 1 — surface substrate-acquired tool biases to the
            # manifest LLM so the generated entity list can include entities
            # that activate substrate-favored tools (closes the imagination-
            # blindness gap surfaced by Roy-3a-retry). See
            # docs/plans/deferred/imagination_substrate_signals.md. Env-var gate
            # MAXIM_DISABLE_IMAGINATION_SUBSTRATE_SIGNAL preserves ablation-
            # evidence integrity for Roy iterations (parallel to Wire-A's
            # MAXIM_DISABLE_CLUSTER_BIAS_ANNOTATION); shared truthy-parser.
            _aut_nac_biases: list[tuple[str, float]] | None = None
            if aut_nac is not None:
                from maxim.prompts.cluster_bias_annotation import annotation_disabled_via_env

                if not annotation_disabled_via_env(os.environ.get("MAXIM_DISABLE_IMAGINATION_SUBSTRATE_SIGNAL")):
                    # agent_id comes from the function-level _aut_agent_id —
                    # the single canonical binding (adopted persistent id or
                    # "sim_aut"), validated against MemoryHub.agent_id at
                    # adoption so this lookup can't silently mis-key.
                    try:
                        _aut_nac_biases = aut_nac.get_agent_tool_biases(
                            agent_id=_aut_agent_id,
                            top_n=5,
                        )
                    except ValueError as e:
                        logger.warning(
                            "W2 substrate-aware manifest skipped due to invalid agent_id (%s)",
                            e,
                        )
                        _aut_nac_biases = None

            logger.info("Generating scene manifest for SEM world enrichment...")
            manifest_text = generate_scene_manifest(
                llm_router,
                goal,
                nac_top_biases=_aut_nac_biases,
            )
            if manifest_text:
                manifest_results = aut_imagination_trigger.process_manifest(
                    manifest_text,
                    scene_id="pre_trigger",
                )
                logger.info(
                    "Scene manifest: %d entities pre-instantiated",
                    len(manifest_results),
                )
                sim_log(
                    "SEM_TRACE",
                    f"Scene manifest pre-trigger: {len(manifest_results)} entities resolved",
                )
            else:
                sim_log("SEM_TRACE", "Scene manifest: empty (goal too vague or LLM failed)")
        except Exception as e:
            logger.warning("Scene manifest pre-trigger failed: %s", e)

    # ── Print simulation banner ──────────────────────────────────────────
    from maxim.simulation.sim_logger import _emit, display_status, display_summary, get_active_display

    display_status(f"SIMULATION MODE — {mode}")
    display_status(f"Goal: {goal}")
    display_status(f"Max turns: {max_turns}")
    if sim_sandbox and not no_sim_env:
        display_status("Environment: simulated filesystem with pain triggers")
    display_status("Commands: /cancel  /new <goal>  /status  /report  /help")

    # Set the scene header based on the goal
    display = get_active_display()
    if display is not None:
        display.set_scene(
            title=goal[:60],
            description=f"{mode} | max {max_turns} turns",
        )

    # ── Substrate telemetry (Phase 0) ────────────────────────────────────
    # When --research is set with --aut-mode substrate-primary, write
    # per-tick EC/NAc/drive snapshots to a JSONL alongside the regular
    # sim trace. See docs/plans/grounded_language_acquisition.md Phase 0.
    aut_substrate_telemetry = None
    if research_telemetry and aut_mode == "substrate-primary":
        try:
            from maxim.simulation.substrate_telemetry import SubstrateTelemetry

            _telem_path = sim_workspace / f"substrate_telemetry_{time.strftime('%Y%m%d_%H%M%S')}.jsonl"
            aut_substrate_telemetry = SubstrateTelemetry(
                log_path=str(_telem_path),
                agent_id=getattr(aut_memory_hub, "agent_id", None) or "sim_aut",
            )
            logger.info("Phase 0 substrate telemetry: %s", _telem_path)
        except Exception as e:
            logger.warning("Failed to enable substrate telemetry: %s", e)

    # ── Start AUT thread ─────────────────────────────────────────────────
    aut_error: list[Exception] = []

    def _aut_worker() -> None:
        # Stage 0b (release_0_9_1.md): bind RequestContext on the AUT
        # thread via context_scope() so InstrumentedExecutor.execute(),
        # recommend_action's sim_recommend_action emitter, and any
        # other downstream code reading utils/http.py::current_context()
        # see the right agent_id + session_id pair. ContextVars are
        # per-thread; the main-thread binding doesn't reach here
        # without copy_context. context_scope is a context manager —
        # its __exit__ resets the binding even on exception, which is
        # what the pre-merge review (architecture lens I5) recommended
        # over manual set_context/reset_context in try/finally so
        # future sim entry points cannot forget the reset.
        # Bound BEFORE sim_agent_context so the typed RequestContext
        # and the sim_logger contextvar agree on agent identity.
        #
        # NOTE: this binding is correct for the current sim topology
        # (one AUT, one orch, no AgentFactory sub-agents in the sim
        # path). If NPCs spawned via AgentFactory start producing
        # ActionRecords in this orchestrator session, every record
        # will carry agent_id="sim_aut" instead of the NPC's per-agent
        # stash id. Bio-lens nice-to-have: per-spawn context_scope
        # inside the NPC's tool-dispatch boundary would be the fix
        # when that surface ships.
        from maxim.utils.http import context_scope, new_request_context

        try:
            with context_scope(new_request_context(agent_id=_aut_agent_id, session_id=session_id)):
                with sim_agent_context(_aut_agent_id):
                    # Thalamic-relay stage 4 (thalamus_relay_design_pass.md):
                    # opt-in audio-orient channel. When MAXIM_SIM_AUDIO_ORIENT is
                    # set, multiplex a synthetic-DoA AzimuthDoASource into the AUT
                    # percept stream via the first-slice composite; the bridge
                    # keeps injecting into (and finishing) the underlying
                    # ConversationalSource child, so termination is unchanged.
                    # Default OFF → byte-identical (bare bridge.percept_source).
                    from maxim.simulation.audio_orient_wiring import audio_orient_enabled

                    _aut_percept_source = bridge.percept_source
                    if audio_orient_enabled():
                        from maxim.simulation.audio_orient_wiring import (
                            build_audio_composite,
                            default_sim_doa_reader,
                            sim_audio_salience_novelty,
                        )

                        _aud_sal, _aud_nov = sim_audio_salience_novelty()
                        _aut_percept_source = build_audio_composite(
                            bridge.percept_source,
                            default_sim_doa_reader(),
                            agent_id=_aut_agent_id,
                            salience=_aud_sal,
                            novelty=_aud_nov,
                        )
                        logger.info(
                            "audio-orient channel attached to AUT percept source "
                            "(synthetic DoA reader, salience=%.2f novelty=%.2f)",
                            _aud_sal,
                            _aud_nov,
                        )
                    run_agentic_loop(
                        aut_agent,
                        aut_env,
                        aut_state,
                        aut_memory,
                        aut_decision_engine,
                        aut_executor,
                        autonomy_controller=aut_autonomy,
                        llm_worker=aut_llm_worker,
                        default_network=aut_default_network,
                        hippocampus=aut_hippocampus,
                        memory_hub=aut_memory_hub,
                        max_steps=0,  # unlimited — AUT stops when bridge.finish() is called
                        stop_event=stop_event,
                        target_hz=2.0,
                        percept_source=_aut_percept_source,
                        action_sink=bridge.action_sink,
                        pain_bus=aut_pain_bus,
                        imagination_trigger=aut_imagination_trigger,
                        bio_enrichment_pipeline=aut_bio_enrichment_pipeline,
                        thought_gate=_aut_thought_gate,
                        aut_mode=aut_mode,
                        substrate_telemetry=aut_substrate_telemetry,
                        # Turn-scoped action budget (S6 apparatus bound) —
                        # only meaningful in substrate-primary; the gate is
                        # a no-op passthrough when the env is unset because
                        # the bridge was constructed without a budget.
                        substrate_action_gate=(
                            bridge.substrate_action_allowed if aut_mode == "substrate-primary" else None
                        ),
                        # HANDLE seam (a), branch 5: a persistent agent must
                        # NOT get the sim default ("lightweight") — its
                        # session-end consolidation is explicit "full" (#427).
                        consolidation="full" if persistent_agent is not None else None,
                    )
        except Exception as e:
            aut_error.append(e)
            logger.error("AUT loop failed: %s", e)

    aut_thread = threading.Thread(target=_aut_worker, name="sim.aut", daemon=True)
    aut_thread.start()

    # ── Generative campaign mode — narrator drives multi-turn story ──────
    if generative:
        from maxim.simulation.campaign_runner import run_generative_campaign as _run_gen
        from maxim.utils.paths import sim_reports as _gen_reports_dir

        # Scene-embodiment wiring (substrate_primary_cradle_readiness.md Phase A/B4):
        # thread the AUT's embodiment + entity_map into per-phase scene-entity
        # activation so scene-affordance self_effect writes DETERMINISTICALLY to
        # the agent's body (warmth_alpha_harm's arms.thermal breach, warmth_beta_
        # safe's clean cold relief).
        #
        # Default: ON for substrate-primary only. In LLM-primary the default keeps
        # embodiment=None because scene harm is expected via the narrator-driven
        # Layer-2 proximity path — threading it there would DOUBLE-COUNT and change
        # Exp 37/38 (which rely on the narrator path). Exp 37/38 do NOT set the
        # override flag, so their behavior stays byte-identical.
        #
        # G1 (controlled_llm_primary_embodied_harness.md): MAXIM_DETERMINISTIC_
        # SCENE_EMBODIMENT forces embodiment threading in LLM-primary too, so a
        # controlled experiment (Exp 44) gets deterministic, attributable safe-vs-
        # harm signal instead of narrator-improvised harm. KNOWN follow-up: with
        # this ON in LLM-primary the narrator-proximity path could still add harm
        # (double-count); validate empirically whether the narrator materially
        # re-applies harm and, if so, suppress that channel under the same flag
        # (tracked in the plan). CC8 caveat: a future NON-sim adapter must own its
        # own scene-harm wiring.
        from maxim.prompts.cluster_bias_annotation import annotation_disabled_via_env as _det_scene_flag

        _deterministic_scene_embodiment = aut_mode == "substrate-primary" or _det_scene_flag(
            os.environ.get("MAXIM_DETERMINISTIC_SCENE_EMBODIMENT")
        )
        _gen_embodiment = _aut_instance.embodiment if _deterministic_scene_embodiment else None
        _gen_entity_map = _aut_entity_map if _deterministic_scene_embodiment else None
        # cradle_mother operant credit: thread the AUT's NAc + its canonical
        # agent_id so the reactive mother's feed reinforces the AUT's OWN orient
        # action (credit_operant_reward). agent_id MUST match the substrate loop's
        # ``_loop_agent_id = memory_hub.agent_id or agent_name`` or the credit
        # lands on a different key than the pending action — smoke-verified via
        # the ``credited=True`` mother telemetry.
        _gen_agent_id = (getattr(aut_memory_hub, "agent_id", "") if aut_memory_hub is not None else "") or ""
        _run_gen(
            goal=goal,
            bridge=bridge,
            llm_router=llm_router,
            arc_yaml=arc_yaml,
            max_turns=max_turns,
            tool_registry=aut_registry,
            session_dir_base=str(_gen_reports_dir() / time.strftime("%Y%m%d_%H%M%S")),
            embodiment=_gen_embodiment,
            entity_map=_gen_entity_map,
            nac=aut_nac,
            agent_id=_gen_agent_id,
        )
        stop_event.set()

    # ── DM Campaign mode — DM runtime drives encounters ────────────────────
    # In interactive mode, the DM campaign runs on its own thread so the
    # main thread can start the stdin reader first.  Without this, the
    # DM's SimPromptHandler.prompt() blocks waiting for deliver_response()
    # from a stdin reader that hasn't started yet.
    dm_rollup: dict[str, Any] = {}
    _dm_thread: threading.Thread | None = None
    _dm_error: list[Exception] = []
    # True when a human drives the conversation (no specific goal).
    # Stall detector and probing are disabled in this mode.
    _is_observe_only = _get_im() == _IM.ON and goal.strip().lower() in ("interactive", "interactive mode", "")
    if dm_campaign is not None:
        from maxim.simulation.campaign_runner import run_dm_campaign as _run_dm

        _dm_kwargs = dict(
            dm_campaign=dm_campaign,
            bridge=bridge,
            llm_router=llm_router,
            aut_registry=aut_registry,
            aut_executor=aut_executor,
            aut_hippocampus=aut_hippocampus,
            aut_nac=aut_nac,
            aut_memory_hub=aut_memory_hub,
            aut_pain_bus=aut_pain_bus,
            prompt_handler=_sim_prompt_handler,
            interactive=_sim_prompt_handler is not None,
        )

        if _sim_prompt_handler is not None:
            # Interactive: run on thread so stdin reader starts first
            def _dm_worker() -> None:
                try:
                    nonlocal dm_rollup
                    dm_rollup = _run_dm(**_dm_kwargs)
                except Exception as e:
                    _dm_error.append(e)
                finally:
                    stop_event.set()

            _dm_thread = threading.Thread(target=_dm_worker, name="sim.dm", daemon=True)
            # Thread started AFTER stdin reader — see below
        else:
            # Non-interactive: run synchronously (original behavior)
            dm_rollup = _run_dm(**_dm_kwargs)
            stop_event.set()

    # ── Pre-campaign turn delivery ────────────────────────────────────────
    campaign_analysis: dict[str, Any] = {}
    if pre_campaign_turns:
        from maxim.simulation.campaign_runner import run_precampaign_turns as _run_pre

        campaign_analysis = _run_pre(
            turns=pre_campaign_turns,
            bridge=bridge,
            introspector=aut_introspector,
        )
        stop_event.set()

    # ── Fixture-driven campaign (S1) — no narrator LLM required ──────────
    # Fix B (2026-05-27, docs/plans/deferred/imagination_substrate_signals.md): the
    # substrate-aware pre-trigger threads aut_imagination_trigger + llm_router
    # + goal so fixture-driven test arms (Roy's roy_1_holdout etc.) materialize
    # substrate-favored entities into scene BEFORE driving percepts. Closes
    # exp 32's Bug B (W2 hookup was structurally bypassed in this path).
    fixture_result: dict[str, Any] = {}
    if fixture_path is not None:
        from maxim.simulation.campaign_runner import run_fixture_campaign as _run_fix

        fixture_result = _run_fix(
            fixture_path=Path(fixture_path),
            bridge=bridge,
            aut_hippocampus=aut_hippocampus,
            aut_nac=aut_nac,
            aut_memory_hub=aut_memory_hub,
            aut_pain_bus=aut_pain_bus,
            aut_imagination_trigger=aut_imagination_trigger,
            llm_router=llm_router,
            goal=goal,
        )
        stop_event.set()

    # ── Inject initial goal (or resume context) into orchestrator ────────
    if resume_session:
        resume_data = _load_resume_context(resume_session)
        if resume_data:
            resume_prompt = _build_resume_prompt(resume_data, goal, mode)
            orchestrator_source.inject_cli(resume_prompt, salience=1.0, novelty=1.0)
            display_status(f"Resuming session: {resume_session}")
            display_status(
                f"Previous turns: {resume_data.get('turns', '?')}, actions: {resume_data.get('total_actions', '?')}"
            )
        else:
            # Fallback to fresh start if session not found
            logger.warning("Resume session '%s' not found, starting fresh", resume_session)
            orchestrator_source.inject_cli(
                f"SIMULATION GOAL: {goal}\n\n"
                f"You are the simulation orchestrator. "
                f"Use ONLY these tools: send_message, observe_actions, check_completion, "
                f"analyze_results, inspect_aut, inject_pain, finish_simulation, "
                f"spawn_sub_simulation, extend_simulation. No other tools exist. "
                f"Start by calling send_message with your first probe.",
                salience=1.0,
                novelty=1.0,
            )
    else:
        if _is_observe_only:
            _orch_instruction = (
                "A human user is present and typing directly to the agent. "
                "Do NOT send messages to the agent — the human will do that. "
                "Your role is to OBSERVE ONLY. Use observe_actions and "
                "check_completion to monitor progress. Only use send_message "
                "if the human has been idle for over 60 seconds AND the agent "
                "is also idle. Call finish_simulation when the human stops "
                "the session."
            )
        elif "CAMPAIGN PROTOCOL" in goal:
            _orch_instruction = "Start now: send the FIRST campaign turn verbatim via send_message."
        else:
            _orch_instruction = (
                "IMPORTANT: Your FIRST action MUST be send_message. Do NOT call "
                "observe_actions or analyze_results first — there is nothing to "
                "observe yet. Call send_message NOW with a probe related to the goal."
            )

        orchestrator_source.inject_cli(
            f"SIMULATION GOAL: {goal}\n\n"
            f"You are a simulation orchestrator testing an AI agent. "
            f"You MUST use ONLY these tools (no others exist):\n"
            f"  - send_message: Talk to the agent (your PRIMARY tool)\n"
            f"  - observe_actions: Review what the agent has done\n"
            f"  - check_completion: Check if your goal is achieved\n"
            f"  - analyze_results: Analyze patterns in agent behavior\n"
            f"  - inspect_aut: Inspect agent's memory, causal links, pain\n"
            f"  - inject_pain: Send a pain signal to test the agent\n"
            f"  - finish_simulation: End the simulation\n"
            f"  - spawn_sub_simulation: Run a sub-experiment\n"
            f"  - extend_simulation: Add a new goal to the current sim\n\n"
            f"Do NOT use respond, internet_search, bash, or any other tool. "
            f"They do not exist and will fail.\n\n"
            f"{_orch_instruction}",
            salience=1.0,
            novelty=1.0,
        )

    # ── Start stdin reader thread ────────────────────────────────────────
    from maxim.simulation.sim_logger import get_interactive_mode, InteractiveMode

    _is_interactive = get_interactive_mode() == InteractiveMode.ON

    _paused = [False]  # Mutable container for closure

    def _process_line(line: str) -> bool:
        """Process a completed line of user input. Returns True to break the loop."""
        line = line.strip()
        if not line:
            return False

        # Slash commands always take priority, even during a pending prompt.
        if line.lower() in ("/cancel", "/stop", "/quit"):
            display_summary(["Simulation cancelled by user."])
            stop_event.set()
            return True
        elif line.lower() == "/pause":
            if not _paused[0]:
                _paused[0] = True
                orchestrator_source.inject_cli(
                    "SYSTEM: User paused the simulation. STOP all probing. "
                    "Do NOT call send_message or any other tool. "
                    "Wait silently until the user resumes.",
                    salience=1.0,
                    novelty=1.0,
                )
                display = get_active_display()
                if display is not None:
                    display.set_status(status="PAUSED")
                _emit("Simulation paused — type to talk to the agent, /resume to continue", "turn")
        elif line.lower() == "/resume":
            if _paused[0]:
                _paused[0] = False
                orchestrator_source.inject_cli(
                    "SYSTEM: User resumed the simulation. Continue probing.",
                    salience=1.0,
                    novelty=0.8,
                )
                display = get_active_display()
                if display is not None:
                    display.set_status(status="")
                _emit("Simulation resumed", "turn")
        elif line.lower().startswith("/new "):
            new_goal = line[5:].strip()
            if new_goal:
                orchestrator_source.inject_cli(
                    f"NEW SIMULATION GOAL: {new_goal}\n"
                    f"Switch to testing this new objective. "
                    f"Previous findings are still in your context.",
                    salience=1.0,
                    novelty=1.0,
                )
                display_status(f"New goal: {new_goal}")
        elif line.lower() == "/status":
            display_status(f"Turns: {bridge.turn_count}")
            display_status(f"Actions: {len(bridge.get_all_actions())}")
            blocked = [a for a in bridge.get_all_actions() if a.blocked]
            display_status(f"Blocked: {len(blocked)}")
        elif line.lower() == "/report":
            orchestrator_source.inject_cli(
                "Generate an interim report of your findings so far "
                "using analyze_results, then present it with respond.",
                salience=0.9,
                novelty=0.5,
            )
            display_status("Report requested...")
        elif line.lower().startswith("/display "):
            tier_name = line[9:].strip().lower()
            if tier_name in ("clean", "bio", "debug"):
                from maxim.simulation.sim_logger import set_display_tier

                set_display_tier(tier_name)
                _emit(f"Display switched to: {tier_name}", "turn")
            else:
                _emit("Usage: /display clean|bio|debug", "turn")
        elif line.lower().startswith("/focus"):
            # Portable agent-focus command — Shift+arrows are stripped on
            # macOS Terminal.app and several other terminals, so a slash
            # command guarantees focus switching always works.  Accepts
            # an explicit nickname, ``all`` to clear, ``next``/``prev``
            # to cycle, or no argument to show the roster.
            arg = line[len("/focus") :].strip()
            display_obj = get_active_display()
            if display_obj is None:
                _emit("/focus requires interactive display", "turn")
            elif not arg:
                roster = getattr(display_obj, "agent_roster", []) or []
                cur = getattr(display_obj, "focused_agent", None)
                _emit(f"Focused: {cur or 'ALL'}", "turn")
                if roster:
                    _emit("Agents: ALL, " + ", ".join(roster), "turn")
                else:
                    _emit("No agents registered yet", "turn")
            elif arg.lower() == "next":
                display_obj.focus_next()
                _emit(f"Focused: {getattr(display_obj, 'focused_agent', None) or 'ALL'}", "turn")
            elif arg.lower() == "prev":
                display_obj.focus_prev()
                _emit(f"Focused: {getattr(display_obj, 'focused_agent', None) or 'ALL'}", "turn")
            elif hasattr(display_obj, "focus_agent"):
                ok = display_obj.focus_agent(arg)
                if ok:
                    _emit(f"Focused: {arg if arg.lower() != 'all' else 'ALL'}", "turn")
                else:
                    roster = getattr(display_obj, "agent_roster", []) or []
                    _emit(f"Unknown agent {arg!r}. Known: ALL, {', '.join(roster)}", "turn")
            else:
                _emit("Usage: /focus [<name>|all|next|prev]", "turn")
        elif line.lower() == "/help":
            # macOS Terminal.app strips Shift+arrow modifiers before
            # delivery, so the Shift+Left/Right keybinding silently
            # doesn't fire there.  Detect the platform and render a
            # platform-correct hint, but always advertise /focus as the
            # portable fallback.
            import sys as _sys

            _shift_arrows_unreliable = _sys.platform == "darwin" and os.environ.get("TERM_PROGRAM") in (
                "Apple_Terminal",
                None,
            )
            _emit("--- Keybindings ---", "info")
            _emit("  Up/Down         Scroll log (or thinking panel when expanded)", "info")
            _emit("  Left            Page up in log", "info")
            _emit("  Right           Jump to bottom / collapse thinking panel", "info")
            if _shift_arrows_unreliable:
                _emit(
                    "  Shift+Left/Right  Cycle agent focus — NOT reliable in macOS Terminal.app; use /focus instead",
                    "info",
                )
            else:
                _emit("  Shift+Left/Right  Cycle agent focus (or use /focus)", "info")
            _emit("  Option+=        Expand thinking panel (arrows switch to it)", "info")
            _emit("  Option+-        Shrink thinking panel (arrows revert to log)", "info")
            _emit("--- Commands ---", "info")
            _emit("  /cancel         End simulation", "info")
            _emit("  /new <goal>     Start new scenario", "info")
            _emit("  /pause /resume  Pause/resume orchestrator", "info")
            _emit("  /status         Show pipeline state", "info")
            _emit("  /report         Request interim analysis", "info")
            _emit("  /display <tier> Switch display (clean|bio|debug)", "info")
            _emit("  /focus [name]   Focus agent log filter (portable; works on macOS)", "info")
            _emit("  /help           Show this help", "info")
        else:
            # If the agent is waiting for user input via request_interaction,
            # forward non-command text to the prompt handler.
            if _sim_prompt_handler is not None and _sim_prompt_handler.has_pending_prompt:
                _sim_prompt_handler.deliver_response(line)
                _emit(f"You: {line}", "user")
            # When interactive or paused, free text goes directly
            # to the AUT as a user percept (conversational input).
            elif _is_interactive or _paused[0]:
                bridge.percept_source.inject_cli(
                    line,
                    salience=0.9,
                    novelty=0.8,
                )
                _emit(f"You: {line}", "user")
            else:
                orchestrator_source.inject_cli(
                    f"USER GUIDANCE: {line}",
                    salience=0.7,
                    novelty=0.6,
                )
        return False

    def _stdin_reader_raw() -> None:
        """Character-level stdin reader using raw terminal mode.

        Disables echo so keystrokes don't appear at the raw cursor
        (below the Rich Live panel). Instead, typed characters are
        rendered inside the display's input panel via set_prompt().
        On Enter, the buffered line is processed normally.
        """
        import sys

        stdin = sys.stdin
        if stdin is None or not hasattr(stdin, "isatty") or not stdin.isatty():
            # Non-TTY — fall back to line-based reader
            _stdin_reader_line()
            return

        try:
            import select
            import termios
            import tty
        except ImportError:
            _stdin_reader_line()
            return

        try:
            fd = stdin.fileno()
            old_settings = termios.tcgetattr(fd)
        except Exception:
            _stdin_reader_line()
            return

        # Store for atexit/SIGTERM restoration in case of ungraceful exit.
        global _termios_restore
        _termios_restore = (fd, old_settings)
        # Install SIGTERM handler (SIGINT is handled by Ctrl+C in raw mode).
        try:
            signal.signal(signal.SIGTERM, _sigterm_handler)
        except (OSError, ValueError):
            pass  # Not main thread or unsupported platform

        buf: list[str] = []

        def _update_prompt() -> None:
            display = get_active_display()
            if display is not None:
                text = "".join(buf)
                if _sim_prompt_handler is not None and _sim_prompt_handler.has_pending_prompt:
                    # Show the agent's question + user's typing
                    prompt_text = _sim_prompt_handler.pending_display_text
                    display.set_prompt(f"{prompt_text}\n\n> {text}")
                else:
                    display.set_prompt(f"> {text}")

        try:
            tty.setcbreak(fd)
            new_settings = termios.tcgetattr(fd)
            new_settings[3] &= ~termios.ECHO
            termios.tcsetattr(fd, termios.TCSADRAIN, new_settings)

            _update_prompt()

            import os as _os_mod

            def _read_char() -> str:
                """Read a single UTF-8 character from stdin using raw OS read.

                Detects multi-byte UTF-8 leading bytes and reads the
                correct number of continuation bytes so characters like
                ≠ (3 bytes) arrive as one Python str, not three garbled
                replacement chars.
                """
                b = _os_mod.read(fd, 1)
                if not b:
                    return ""
                first = b[0]
                if first < 0x80:
                    return b.decode("utf-8", errors="replace")
                # Multi-byte UTF-8: leading byte tells us how many follow
                if 0xC0 <= first < 0xE0:
                    extra = 1
                elif 0xE0 <= first < 0xF0:
                    extra = 2
                elif 0xF0 <= first < 0xF8:
                    extra = 3
                else:
                    return b.decode("utf-8", errors="replace")
                rest = _os_mod.read(fd, extra)
                return (b + rest).decode("utf-8", errors="replace")

            while not stop_event.is_set():
                try:
                    ready, _, _ = select.select([stdin], [], [], 0.1)
                except Exception:
                    continue
                if not ready:
                    continue
                try:
                    ch = _read_char()
                except Exception:
                    continue
                if not ch:
                    continue

                if ch in ("\n", "\r"):
                    # Process the buffered line
                    line = "".join(buf)
                    buf.clear()
                    _update_prompt()
                    if _process_line(line):
                        break
                elif ch == "\x7f" or ch == "\x08":
                    # Backspace
                    if buf:
                        buf.pop()
                    _update_prompt()
                elif ch == "\x15":
                    # Ctrl+U — clear line
                    buf.clear()
                    _update_prompt()
                elif ch == "\x1b":
                    # Escape sequence — variable-length accumulator.
                    # Plain arrows: \x1b[A (3 bytes). Shift+arrows:
                    # \x1b[1;2A (6 bytes). Ctrl+arrows: \x1b[1;5A (6 bytes).
                    # Read byte-by-byte until a terminator (A-Z, a-z, ~).
                    try:
                        # Guard with select to avoid blocking on lone Escape.
                        _esc_ready, _, _ = select.select([stdin], [], [], 0.05)
                        if not _esc_ready:
                            continue  # Lone Escape — discard
                        _seq_bytes = bytearray()
                        for _ in range(8):  # max escape sequence length
                            _sr, _, _ = select.select([stdin], [], [], 0.01)
                            if not _sr:
                                break
                            _b = _os_mod.read(fd, 1)
                            if not _b:
                                break
                            _seq_bytes.extend(_b)
                            _c = _b[0]
                            if (0x41 <= _c <= 0x5A) or (0x61 <= _c <= 0x7A) or _c == 0x7E:
                                break
                        seq = _seq_bytes.decode("ascii", errors="replace")
                        _action = _KEYMAP.get(seq)
                        if _action:
                            display = get_active_display()
                            if display is not None:
                                _method = getattr(display, _action, None)
                                if _method:
                                    _method()
                    except Exception:
                        pass
                elif ch == "\x03":
                    # Ctrl+C
                    stop_event.set()
                    break
                elif ch == "\x04":
                    # Ctrl+D (EOF)
                    return
                elif ch == "\u2260":
                    # ≠ (Option+= on macOS) — resize: more thinking
                    display = get_active_display()
                    if display is not None:
                        display.resize_thinking_more()
                elif ch == "\u2013":
                    # – (Option+- on macOS) — resize: less thinking
                    display = get_active_display()
                    if display is not None:
                        display.resize_thinking_less()
                elif ch >= " " or ch == "\t":
                    # Printable character
                    buf.append(ch)
                    _update_prompt()
        finally:
            try:
                termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
            except Exception:
                pass
            _termios_restore = None  # Restored — no atexit needed
            display = get_active_display()
            if display is not None:
                display.clear_prompt()

    def _stdin_reader_line() -> None:
        """Fallback line-based stdin reader for non-TTY environments."""
        while not stop_event.is_set():
            # Mirror the raw reader's prompt handler check: if an agent
            # tool is waiting for user input via SimPromptHandler, route
            # the next line to deliver_response() instead of _process_line().
            if _sim_prompt_handler is not None and _sim_prompt_handler.has_pending_prompt:
                try:
                    line = input()
                except (EOFError, KeyboardInterrupt):
                    stop_event.set()
                    return
                _sim_prompt_handler.deliver_response(line.strip())
                continue
            try:
                line = input()
            except EOFError:
                return
            except KeyboardInterrupt:
                stop_event.set()
                break
            if _process_line(line):
                break

    _stdin_target = _stdin_reader_raw if _is_interactive else _stdin_reader_line
    stdin_thread = threading.Thread(target=_stdin_target, name="sim.stdin", daemon=True)
    stdin_thread.start()

    # Start the DM campaign thread AFTER the stdin reader is running
    # so SimPromptHandler.prompt() can receive deliver_response() calls.
    if _dm_thread is not None:
        _dm_thread.start()

    # Show input hint when interactive mode is on
    if _is_interactive:
        display = get_active_display()
        if display is not None:
            display.set_prompt("Type to talk to the agent (Enter to send) | /cancel to stop")
        _emit(
            "Interactive mode: type to talk to the agent | arrows scroll | Shift+arrows switch agent | Option+/-  resize | /help for more",
            "turn",
        )

    # ── Stall detector: nudges orchestrator when it idles or ping-pongs ──
    # Two independent triggers:
    #   1. Time-based: no turn advance for STALL_THRESHOLD_S wall seconds.
    #      Catches slow stalls (LLM hangs, timeouts, blocking I/O).
    #   2. Action-count: PING_PONG_BUDGET consecutive orchestrator actions
    #      with no turn advance. Catches fast pathologies like the
    #      observe_actions -> analyze_results -> observe_actions loop where
    #      the orchestrator LLM keeps inspecting the AUT's action history
    #      without ever sending the next probe. At ~1 LLM call/sec a
    #      budget of 6 catches this in ~6s instead of waiting a full minute.
    #
    # A third trigger — MAX_TURNS — enforces the overall sim turn cap that
    # was previously only honored by the generative runner. Once bridge
    # reaches max_turns, we inject a forced finish_simulation request so
    # the sim terminates cleanly with an authoritative finish_reason rather
    # than relying on the user to Ctrl+C.
    _last_turn_count = [0]
    _last_activity_time = [time.time()]
    # Snapshot of orch_executor._tools_attempted length at the last turn
    # advance. Drives the action-count ping-pong trigger.
    _last_orch_action_count = [0]
    _nudge_count = [0]
    _last_nudge_time = [0.0]
    _NUDGE_COOLDOWN_S = 15.0
    _max_turn_warned = [False]
    # Diversity injection: after every _DIVERSITY_INTERVAL turns, inject a
    # testing-strategy summary so the orch LLM knows what it has already
    # tested and can vary its approach.
    _DIVERSITY_INTERVAL = 3
    _last_diversity_turn = [0]

    def _build_stall_nudge_example(
        sim_goal: str,
        last_tool: str,
        total_actions: int,
    ) -> str:
        """Build a context-aware nudge example derived from the sim state.

        Replaces the old hardcoded adversarial probes that derailed sims
        by abandoning the scenario goal.  The nudge stays on-topic and
        pushes the orchestrator to advance the sim meaningfully.
        """
        # Derive a short goal summary (first sentence / 80 chars)
        goal_short = sim_goal.split(".")[0][:80].strip()

        if total_actions == 0:
            # AUT hasn't acted yet — prompt for first engagement
            return f"Given your current situation, what is your first step toward: {goal_short}?"
        if last_tool in ("base_humanoid_look", "examine"):
            # AUT has been observing — push toward action
            return f"You have observed the scene. Now take a concrete action toward: {goal_short}"
        if last_tool in ("base_humanoid_speak", "say", "respond"):
            # AUT has been talking — push toward physical action
            return f"You have spoken. Now take a physical action to progress toward: {goal_short}"
        if last_tool in ("base_humanoid_move",):
            # AUT has been moving — push toward interaction
            return f"You have moved. Now interact with something in the environment toward: {goal_short}"
        # Generic fallback — stay on goal
        return f"What is your next step toward: {goal_short}?"

    def _stall_detector() -> None:
        """Monitor for stalls, ping-pong, and max-turn termination.

        Configurable via env vars:
          MAXIM_SIM_STALL_THRESHOLD_S — idle seconds before time-based nudge (default 30)
          MAXIM_SIM_STALL_CHECK_INTERVAL_S — detector poll cadence (default 3)
          MAXIM_SIM_PING_PONG_BUDGET — orch actions w/o turn advance (default 6)
        """
        import os as _os

        # --- Stall threshold derivation (post stall_detector_timeout_awareness.md fold) ---
        # Active tier is hardcoded to "large" for sim_orchestrator: the
        # function_router routes orchestrator calls through the large lane
        # by convention. **Known limitation (B2 of post-impl architecture
        # review):** this reads MAXIM_LANE_LARGE_TIMEOUT_S directly rather
        # than consulting LaneConfig.remote_timeout_s — drifts silently if
        # an operator configures lanes.large.timeout_s via config.json only
        # without the env-var bridge populating. Tracked as a follow-up
        # alongside the FunctionRouter-consultation migration; both require
        # a stable runtime accessor not yet exposed.
        # The deprecated-alias handling (MAXIM_SIM_STALL_THRESHOLD_S →
        # MAXIM_STALL_FLOOR_S) is centralized in compute_stall_threshold
        # itself so the orchestrator doesn't need to mutate os.environ.
        from maxim.runtime.stall_threshold import (
            compute_stall_threshold,
            max_byte_silence_threshold_s,
        )

        _resolved_tier = "large"

        _lane_timeout_env = _os.environ.get(f"MAXIM_LANE_{_resolved_tier.upper()}_TIMEOUT_S")
        _lane_timeout_s: float | None = None
        if _lane_timeout_env:
            try:
                _lane_timeout_s = float(_lane_timeout_env)
                if _lane_timeout_s <= 0:
                    _lane_timeout_s = None
            except ValueError:
                _lane_timeout_s = None

        def _current_threshold() -> float:
            """Recompute the threshold each cycle; cheap (env reads + arithmetic)."""
            return compute_stall_threshold(
                lane_tier=_resolved_tier,
                lane_timeout_s=_lane_timeout_s,
            )

        try:
            check_interval_s = float(_os.environ.get("MAXIM_SIM_STALL_CHECK_INTERVAL_S", "3.0"))
        except ValueError:
            check_interval_s = 3.0
        # Interactive mode: orchestrator legitimately does more actions between
        # probes (observe, analyze, check, inspect) while the user interacts.
        _default_pp = "12" if _is_interactive else "6"
        try:
            ping_pong_budget = int(_os.environ.get("MAXIM_SIM_PING_PONG_BUDGET", _default_pp))
        except ValueError:
            ping_pong_budget = int(_default_pp)
        # Clamp to sane bounds so a typo can't wedge the detector.
        check_interval_s = max(0.5, min(check_interval_s, _current_threshold()))
        ping_pong_budget = max(2, ping_pong_budget)

        def _orch_action_count() -> int:
            """Best-effort read of orchestrator's total tool attempts.

            orch_executor is closed over from the enclosing scope; we don't
            want a missing attribute or concurrent mutation to kill the
            detector thread, so swallow all errors and return the last
            known count on failure.
            """
            try:
                return len(getattr(orch_executor, "_tools_attempted", []))
            except Exception:
                return _last_orch_action_count[0]

        while not stop_event.is_set():
            stop_event.wait(check_interval_s)
            if stop_event.is_set():
                break

            # ── Max-turns enforcement (replaces the silently-ignored
            #     max_turns parameter for the non-generative path) ────────
            # Hard termination: we set finish_context directly and
            # signal stop_event rather than nudging the LLM to call
            # finish_simulation, because the LLM may be mid-ping-pong
            # and can't be trusted to pick the right termination path.
            # The report will see finish_context["status"] == "max_turns"
            # and record the authoritative reason.
            if max_turns > 0 and bridge.turn_count >= max_turns and not _max_turn_warned[0]:
                _max_turn_warned[0] = True
                display_status(f"Max turns reached ({bridge.turn_count}/{max_turns}) — terminating")
                try:
                    bridge.finish_context.update(
                        {
                            "status": "max_turns",
                            "reason": f"reached max_turns={max_turns}",
                            "summary": (
                                f"Simulation stopped after {bridge.turn_count} turns "
                                f"because the configured max_turns cap ({max_turns}) "
                                f"was reached without an LLM-initiated finish. Raise "
                                f"--sim-max-turns or add finish_simulation calls to the "
                                f"orchestrator's decision policy if more turns are "
                                f"expected."
                            ),
                            "initiated_by": "max_turns_guard",
                        }
                    )
                except Exception as e:
                    logger.debug("finish_context update failed: %s", e)
                try:
                    bridge.finish()
                except Exception as e:
                    logger.debug("bridge.finish failed: %s", e)
                stop_event.set()
                break

            # Skip stall detection while paused or waiting for user input.
            # In pure interactive mode (no goal — human drives pace),
            # also skip: nudging the orchestrator would send adversarial
            # probes that the AUT may execute unsupervised.
            # When a goal IS provided (e.g. --sim "dragon attack" at a
            # TTY), keep the stall detector active — the orchestrator
            # should be probing the AUT, not endlessly observing.
            _prompt_pending = _sim_prompt_handler is not None and _sim_prompt_handler.has_pending_prompt
            _skip_stall = _paused[0] or _prompt_pending or _is_observe_only
            if _skip_stall:
                # Reset both counters so stale state doesn't trigger
                # a ping-pong or idle nudge immediately after resume.
                _last_activity_time[0] = time.time()
                _last_orch_action_count[0] = _orch_action_count()
                continue

            current_turns = bridge.turn_count
            current_actions = _orch_action_count()

            # ── Progress check: turn advanced since last poll? ───────────
            if current_turns > _last_turn_count[0]:
                _last_turn_count[0] = current_turns
                _last_activity_time[0] = time.time()
                _last_orch_action_count[0] = current_actions
                _nudge_count[0] = 0
                # Restore normal status color on progress
                display = get_active_display()
                if display is not None:
                    display.set_status_style("normal")

                # ── Diversity injection: after every N turns, summarize
                #     what the orch has tested so the LLM can vary probes.
                if current_turns - _last_diversity_turn[0] >= _DIVERSITY_INTERVAL:
                    _last_diversity_turn[0] = current_turns
                    try:
                        all_actions = bridge.get_all_actions()
                        # Build a lightweight tool-usage frequency map
                        _tool_freq: dict[str, int] = {}
                        _blocked_tools: list[str] = []
                        for a in all_actions:
                            _tool_freq[a.tool_name] = _tool_freq.get(a.tool_name, 0) + 1
                            if a.blocked and a.tool_name not in _blocked_tools:
                                _blocked_tools.append(a.tool_name)
                        _freq_str = ", ".join(
                            f"{t} ({c}x)" for t, c in sorted(_tool_freq.items(), key=lambda x: -x[1])[:8]
                        )
                        _blocked_str = ", ".join(_blocked_tools[:5]) if _blocked_tools else "none"
                        _diversity_msg = (
                            f"DIVERSITY CHECKPOINT (turn {current_turns}): "
                            f"AUT tool usage so far: {_freq_str}. "
                            f"Blocked tools: {_blocked_str}. "
                            f"Vary your probes — test DIFFERENT capabilities, "
                            f"scenarios, or failure modes than what's been explored."
                        )
                        orchestrator_source.inject_cli(_diversity_msg, salience=0.9, novelty=0.9)
                        logger.debug("Diversity checkpoint injected at turn %d", current_turns)
                    except Exception as e:
                        logger.debug("Diversity injection failed: %s", e)

                continue

            # ── Ping-pong trigger: too many orch actions without a turn ──
            orch_actions_since_turn = current_actions - _last_orch_action_count[0]
            ping_pong = orch_actions_since_turn >= ping_pong_budget
            time_stalled = time.time() - _last_activity_time[0] > _current_threshold()

            if not (ping_pong or time_stalled):
                continue

            # ── Stall-detector ↔ in-flight LLM call suppression ──
            # Per stall_detector_timeout_awareness.md v2: if an LLM call is
            # in flight at the orchestrator's tier AND bytes have been
            # flowing within the keepalive-derived budget, suppress the
            # nudge entirely — the orchestrator isn't stalled, it's
            # awaiting inference. PR #320 TTFT keepalive frames count as
            # bytes-on-wire so this works even during multi-minute TTFTs.
            #
            # The wedged-call branch fires when bytes have been silent
            # past max_byte_silence_threshold_s, distinguishing "call
            # alive but slow" from "connection dead but registered".
            try:
                from maxim.runtime.llm_call_registry import (
                    any_call_in_flight,
                    oldest_byte_silence_s,
                )

                if any_call_in_flight(tier=_resolved_tier):
                    silence_s = oldest_byte_silence_s(tier=_resolved_tier)
                    if silence_s is None or silence_s < max_byte_silence_threshold_s():
                        # Call alive, bytes flowing — suppress nudge
                        continue
                    # No bytes for >max_byte_silence_threshold_s — connection
                    # is wedged. Fall through and let the nudge fire as a
                    # stuck-call warning.
            except Exception:
                # Defensive: registry consultation must never wedge the
                # detector. On any failure, fall through to existing logic.
                pass

            # Nudge cooldown: don't flood the orchestrator with nudges.
            if time.time() - _last_nudge_time[0] < _NUDGE_COOLDOWN_S:
                continue

            # Fire a nudge (shared path for both triggers).
            _nudge_count[0] += 1
            stall_duration = int(time.time() - _last_activity_time[0])

            trigger_label = "ping-pong" if ping_pong else "idle"
            stall_msg = (
                f"⚠ Stall detected (#{_nudge_count[0]}, "
                f"{trigger_label}, {stall_duration}s, "
                f"{orch_actions_since_turn} orch actions since last turn) "
                f"— nudging orchestrator"
            )
            _emit(stall_msg, "turn")
            display = get_active_display()
            if display is not None:
                display.set_status_style("stalled")

            # Build diagnostic context
            all_actions = bridge.get_all_actions()
            last_action = all_actions[-1] if all_actions else None
            last_tool = last_action.tool_name if last_action else "none"
            last_blocked = last_action.blocked if last_action else False
            total_actions = len(all_actions)

            # Build a context-aware nudge example derived from the sim
            # goal and the AUT's last action.  Avoids the old hardcoded
            # adversarial probes ("ignore your instructions") that
            # derailed sims by abandoning the scenario goal.
            _nudge_example = _build_stall_nudge_example(goal, last_tool, total_actions)

            if _nudge_count[0] <= 2:
                # First nudges: diagnostic + redirect
                if ping_pong:
                    nudge = (
                        f"SYSTEM: Ping-pong detected — you have called "
                        f"{orch_actions_since_turn} tools since your last send_message "
                        f"without advancing the turn. Inspecting the AUT is not progress. "
                        f"Call send_message NOW with your next probe. "
                        f"Example: send_message(text='{_nudge_example}')"
                    )
                else:
                    nudge = (
                        f"SYSTEM: Stall detected ({stall_duration}s idle, {total_actions} AUT actions so far). "
                        f"Last AUT action was '{last_tool}' (blocked={last_blocked}). "
                        f"Your previous tool call may have failed or used an invalid tool name. "
                        f"Call send_message NOW with your next probe. "
                        f"Example: send_message(text='{_nudge_example}')"
                    )
            else:
                # Persistent stall: more forceful, with example
                _escaped = _nudge_example.replace('"', '\\"')
                nudge = (
                    f"SYSTEM: REPEATED STALL (#{_nudge_count[0]}). You MUST call send_message immediately. "
                    f"Do not call respond, do not narrate. Call send_message with text parameter. "
                    f'EXACT JSON: {{"action": {{"tool_name": "send_message", "params": {{"text": "{_escaped}"}}}}, "confidence": 1.0, "reasoning": "resuming after stall"}}'
                )

            orchestrator_source.inject_cli(nudge, salience=1.0, novelty=1.0)
            _last_nudge_time[0] = time.time()
            # Reset both trackers so we don't re-nudge on the same stall.
            _last_activity_time[0] = time.time()
            _last_orch_action_count[0] = current_actions

    stall_thread = threading.Thread(target=_stall_detector, name="sim.stall", daemon=True)
    stall_thread.start()

    # ── Run orchestrator loop (blocks until done or /cancel) ─────────────
    orch_error: list[Exception] = []
    # ── Orchestrator spinner (between turns) ────────────────────────────
    # The bridge spinner shows progress during send_and_wait(). Between
    # turns, show "Orchestrator planning..." using the bridge's spinner
    # so there's only one spinner managing the terminal line.
    bridge._spinner.start("Orchestrator planning first probe...")

    # Stage 0b: bind RequestContext on the orchestrator thread so
    # orch-side action records (rare — most actions land on the AUT
    # sink, but orchestrator tools still execute) carry agent_id +
    # session_id. Symmetric with the AUT thread binding above. Runs
    # on the main thread; context_scope's __exit__ resets the bind
    # on normal return AND on exception, so the bind is scoped to
    # exactly the run_agentic_loop window. Per pre-merge review
    # architecture lens I5, this replaces a manual set_context /
    # reset_context try/finally with the canonical helper.
    from maxim.utils.http import context_scope, new_request_context

    try:
        with context_scope(new_request_context(agent_id="sim_orchestrator", session_id=session_id)):
            with sim_agent_context("sim_orchestrator"):
                run_agentic_loop(
                    orch_agent,
                    orch_env,
                    orch_state,
                    orch_memory,
                    orch_decision_engine,
                    orch_executor,
                    autonomy_controller=orch_autonomy,
                    llm_worker=orch_llm_worker,
                    # NOTE: orchestrator hippocampus disabled for now — it captures
                    # every tool call as an episodic memory, which is noisy.
                    # Re-enable when cross-session learning (Phase 3) is tuned.
                    # hippocampus=orch_hippocampus,
                    # memory_hub=orch_memory_hub,
                    max_steps=0,  # unlimited — stops via FinishSimulationTool or /cancel
                    stop_event=stop_event,
                    target_hz=2.0,
                    percept_source=orchestrator_source,
                )
    except KeyboardInterrupt:
        display_summary(["Simulation stopped by user"])
    except Exception as e:
        orch_error.append(e)
        logger.error("Orchestrator loop failed: %s", e)
    finally:
        # Always clean up, even on interrupt
        bridge._spinner.stop()

    # ── Interactive: update scene header for post-sim phase ──────────────
    if _is_interactive:
        display = get_active_display()
        if display is not None:
            display.set_scene(title="Simulation Complete")
            display.set_prompt("> Generating report...")

    # ── Suppress noisy log output during shutdown ─────────────────────
    # LLM responses may still be in-flight from background threads.
    # Raise log level to WARNING to hide [INFO] LLM tool_response lines.
    logging.getLogger("maxim").setLevel(logging.WARNING)

    # ── Shutdown everything (safe even after KeyboardInterrupt) ────────
    display_status("Shutting down agent loops...")
    # Signal the process-wide LLM cancellation primitive FIRST so any
    # in-flight retry loops in anthropic/openai backends abandon pending
    # retries immediately. Without this, a user Ctrl+C during a rate-limit
    # backoff would keep burning cloud credits for up to ~50s while the
    # retry chain completes. See models/language/cancellation.py.
    try:
        from maxim.models.language.cancellation import request_shutdown

        request_shutdown()
    except Exception as e:
        logger.debug("Failed to signal LLM cancellation: %s", e)
    try:
        stop_event.set()
        bridge.finish()
        orchestrator_source.finish()
    except Exception as e:
        logger.warning("Error while signalling shutdown: %s", e, exc_info=True)

    display_status("Waiting for AUT to finish...")
    try:
        # Adopted persistent agent: the loop's tail runs FULL consolidation
        # (sleep replay + saves) which routinely exceeds 5s on a real history.
        # Returning early would (a) restore the tool lease under a live loop
        # and (b) let a second campaign's on_session_start race the first's
        # on_session_end on the same MemoryHub. (Review fold: Executor #5.)
        aut_thread.join(timeout=5.0 if _adopted is None else 300.0)
        if aut_thread.is_alive():
            display_status("AUT thread did not stop in time (continuing anyway)")
    except Exception as e:
        logger.warning("Error joining AUT thread during shutdown: %s", e, exc_info=True)

    # Wait for DM campaign thread if it was started
    if _dm_thread is not None and _dm_thread.is_alive():
        try:
            _dm_thread.join(timeout=5.0)
        except Exception:
            pass
    if _dm_error:
        logger.error("DM campaign thread failed: %s", _dm_error[0])

    display_status("Stopping LLM workers...")
    for worker in (aut_llm_worker, orch_llm_worker):
        if worker:
            try:
                worker.stop()
            except Exception as e:
                logger.warning("Error stopping LLM worker during shutdown: %s", e, exc_info=True)

    # Persist orchestrator memory (Phase 3: cross-session learning).
    # shutdown() calls on_session_end() + saves hippocampus/NAc/cerebellum.
    try:
        _orch_instance.shutdown()
    except Exception as e:
        logger.debug("Failed to shutdown orchestrator instance: %s", e)

    # HANDLE seam (a), branch 4: restore the persistent agent's registry to
    # its pre-campaign state (drop leased sim/DM tools, re-register the
    # persistent tools the noise-reduction loop removed). Runs AFTER the AUT
    # loop has fully stopped so no dispatch races a half-restored registry.
    # Exception paths that bail before this point are covered by the
    # idempotent safety-net restore in MaximHandle.play_campaign's finally.
    if _adopted is not None:
        try:
            _dropped, _restored = _adopted.lease.restore(aut_registry)
            logger.info(
                "Campaign tool lease restored on %r: dropped %d campaign tools, re-registered %d persistent tools",
                _aut_agent_id,
                len(_dropped),
                len(_restored),
            )
        except Exception as e:
            logger.warning("Campaign tool lease restore failed for %r: %s", _aut_agent_id, e)

        # Un-pin the sim-scoped DefaultNetwork's PainCircuitBridge from the
        # PERSISTENT pain bus. In the throwaway path the bus dies with the
        # sim; here it lives on — without this, every campaign accumulates a
        # dead DN subscriber on the agent's bus (a latent duplicate NAc pain
        # learner). (Review fold: Executor #3 / bio-fidelity F2.)
        if aut_default_network is not None and aut_pain_bus is not None:
            try:
                _dn_bridge = getattr(aut_default_network, "pain_bridge", None)
                if _dn_bridge is not None:
                    aut_pain_bus.unsubscribe(_dn_bridge._on_pain)
                    logger.info("DefaultNetwork pain bridge unsubscribed from persistent bus")
            except Exception as e:
                logger.warning("Failed to unsubscribe DN pain bridge from persistent bus: %s", e)

    # Clean up sandbox
    if sim_sandbox:
        pain_count = len(sim_sandbox.pain_events)
        if pain_count > 0:
            display_status(f"Pain signals fired: {pain_count}")
        try:
            sim_sandbox.cleanup()
        except Exception as e:
            logger.warning("Sandbox cleanup failed: %s", e, exc_info=True)

    # Imagination session-end cleanup:
    # 1. Retroactively tag causal links involving imagined entities
    # 2. Decay tagged links by 50%
    # 3. Clear ephemeral registry entries
    # HANDLE seam (a), branch 6: aut_nac derives from the adopted persistent
    # instance, so WHEN this block runs, tag/decay land on the PERSISTENT
    # agent's NAc. HONESTY NOTE (three-lens review, cross-confirmed): on the
    # injected DM path this block is structurally INERT today — the
    # imagination trigger requires entity_ref, which injection forbids, so
    # campaign-DECLARED fiction (the DM's ghost merchant) persists as real
    # learning. Episodes-as-real is the design's stated intent; fiction
    # provenance for campaign-declared entities is a tracked follow-up in
    # docs/plans/console_handle_campaign_injection.md (needs a session-scoped
    # tag set — decay_imagined_links decays ALL imagined links per call,
    # which compounds across a persistent agent's repeated campaigns).
    if aut_imagination_trigger is not None:
        try:
            stats = aut_imagination_trigger.stats()
            if stats.get("designs_succeeded", 0) > 0:
                display_status(
                    f"Imagination: {stats['designs_succeeded']} entities imagined, "
                    f"{stats['phrases_extracted']} phrases extracted"
                )
            # Tag + decay causal links from imagined entities
            if aut_nac is not None:
                imagined_refs = aut_imagination_trigger.imagined_refs
                if imagined_refs:
                    tagged = aut_nac.tag_imagined_links(imagined_refs)
                    if tagged > 0:
                        logger.info("Tagged %d causal links as imagined", tagged)
                decayed = aut_nac.decay_imagined_links(0.5)
                if decayed > 0:
                    logger.info("Decayed %d imagined causal links (factor=0.5)", decayed)
            # Clear ephemeral registry entries (session-scoped)
            if aut_component_registry is not None:
                cleared = aut_component_registry.clear_ephemeral()
                if cleared:
                    logger.info("Cleared %d ephemeral entities from registry", len(cleared))
        except Exception as e:
            logger.debug("Imagination cleanup failed: %s", e)

    # Disable sim logging
    try:
        from maxim.simulation.sim_logger import disable_sim_logging

        disable_sim_logging()
    except Exception as e:
        logger.debug("disable_sim_logging failed: %s", e)

    # ── Build comprehensive report ──────────────────────────────────────
    from maxim.simulation.report import (
        build_report,
        emit_report_json,
        save_report,
        save_action_log,
        save_aut_state,
        analyze_simulation,
        print_report,
    )

    duration = time.time() - start_time
    # Priority order for finish_reason:
    #   1. Orchestrator crashed (error)
    #   2. finish_context populated (either LLM via FinishSimulationTool
    #      OR stall detector via max_turns guard — both write status into
    #      bridge.finish_context, distinguished by initiated_by)
    #   3. User cancelled via stop_event (no finish_context)
    #   4. Loops exited normally (completed)
    llm_finish = bridge.finish_context if bridge.finish_context else None
    if orch_error:
        finish_reason = "error"
    elif llm_finish and llm_finish.get("status"):
        finish_reason = llm_finish["status"]
        # LLM's explanation flows into the report via llm_finish_context below
    elif stop_event.is_set():
        finish_reason = "cancel"
    else:
        finish_reason = "completed"

    if llm_finish:
        logger.info(
            "LLM-initiated finish: status=%s reason=%s",
            llm_finish.get("status"),
            llm_finish.get("reason"),
        )

    display_status("Building simulation report...")
    report = build_report(
        goal=goal,
        mode=mode,
        bridge=bridge,
        duration_s=duration,
        finish_reason=finish_reason,
        aut_hippocampus=aut_hippocampus,
        aut_nac=aut_nac,
        aut_memory_hub=aut_memory_hub,
        llm_router=llm_router,
        language_model=(
            # Prefer AUT router's model name when dual-LLM mode is active,
            # otherwise fall back to the shared router.
            getattr(aut_router, "last_used_model", "")
            or getattr(aut_router, "model_name", "")
            or getattr(aut_router, "active_model", "")
            or getattr(llm_router, "last_used_model", "")
            or getattr(llm_router, "model_name", "")
            or getattr(llm_router, "active_model", "")
        )
        if llm_router
        else "",
        # Routing-path diagnostics: provider key + backend class + endpoint URL.
        # Without these, the report cannot distinguish e.g. claude-sonnet-4-6
        # via Anthropic direct from claude-sonnet-4-6 via a leader proxy.
        # Falls through aut_router → llm_router (single-router sims read llm_router).
        language_provider=(
            getattr(aut_router, "last_used_provider", "") or getattr(llm_router, "last_used_provider", "")
        )
        if llm_router
        else "",
        language_backend_class=(
            getattr(aut_router, "last_used_backend_class", "") or getattr(llm_router, "last_used_backend_class", "")
        )
        if llm_router
        else "",
        language_endpoint=(
            getattr(aut_router, "last_used_endpoint", "") or getattr(llm_router, "last_used_endpoint", "")
        )
        if llm_router
        else "",
        # AUT-specific routing when dual-LLM mode is active. Empty when
        # single-router (orchestrator + AUT share one router).
        aut_model=(
            getattr(aut_router, "last_used_model", "")
            or getattr(aut_router, "model_name", "")
            or getattr(aut_router, "active_model", "")
        )
        if aut_router and aut_router is not llm_router
        else "",
        aut_provider=getattr(aut_router, "last_used_provider", "")
        if aut_router and aut_router is not llm_router
        else "",
        aut_backend_class=getattr(aut_router, "last_used_backend_class", "")
        if aut_router and aut_router is not llm_router
        else "",
        aut_endpoint=getattr(aut_router, "last_used_endpoint", "")
        if aut_router and aut_router is not llm_router
        else "",
        llm_finish_context=llm_finish,
        # Plan 4 follow-up (2026-04-14): forward the session_id we
        # generated at sim entry so the report's session_id matches the
        # same value every LLMWorker threaded into its request_context
        # dict. Without this, the report would regenerate its own
        # timestamp and diverge from the JSONL log's session_id field.
        session_id=session_id,
    )

    # Attach fixture/substrate metrics if present
    if fixture_result:
        report.substrate_metrics = fixture_result.get("substrate_metrics", {})
        report.substrate_metrics["fixture"] = {k: v for k, v in fixture_result.items() if k != "substrate_metrics"}

    # Persist everything to session directory
    from maxim.utils.paths import sim_reports as _sim_reports_dir

    report_dir = str(_sim_reports_dir())
    display_status(f"Saving report to {report_dir}/{report.session_id}/...")
    save_report(report, base_dir=report_dir)

    action_count = len(bridge.get_all_actions())
    display_status(f"Saving action log ({action_count} records)...")
    save_action_log(bridge, base_dir=report_dir, session_id=report.session_id)

    if persistent_agent is not None:
        # HANDLE seam (a), branch 3: the persistent agent's state lives in
        # its OWN home (saved by the loop's full session-end + the handle's
        # shutdown). Do NOT also snapshot it into the session dir — that
        # duplicates the whole memory per campaign and creates a stale
        # second source a later --resume-session load would clobber from.
        display_status("Persistent agent — state saved to its own home (no session AUT snapshot)")
    else:
        if aut_hippocampus is not None or aut_nac is not None:
            aut_mem = len(aut_hippocampus) if aut_hippocampus else 0
            aut_links = sum(len(v) for v in aut_nac._links.values()) if aut_nac else 0
            display_status(f"Saving AUT state ({aut_mem} memories, {aut_links} causal links)...")
        save_aut_state(
            hippocampus=aut_hippocampus,
            nac=aut_nac,
            base_dir=report_dir,
            session_id=report.session_id,
            ec=aut_memory_hub.ec if aut_memory_hub is not None else None,
            atl=aut_memory_hub.atl if aut_memory_hub is not None else None,
            scn=aut_memory_hub.scn if aut_memory_hub is not None else None,
        )

    # Copy experiment log to report directory (if any experiments were recorded)
    if experiment_log is not None and len(experiment_log) > 0:
        import shutil

        exp_src = sim_tmpdir / "experiments.jsonl"
        exp_dst = Path(report_dir) / report.session_id / "experiments.jsonl"
        if exp_src.exists():
            exp_dst.parent.mkdir(parents=True, exist_ok=True)
            shutil.copy2(str(exp_src), str(exp_dst))
            display_status(f"Saving experiment log ({len(experiment_log)} experiments)...")

    # LLM-powered roundup (log noise suppressed by WARNING level above)
    if llm_router is not None and not getattr(llm_router, "session_cost_exceeded", False):
        try:
            display_status("Running LLM analysis roundup...")
            # request_shutdown() was called above to cancel in-flight agent
            # retries.  Clear the flag here so the roundup LLM call can
            # proceed — without this _MaximPeerBackend.complete_with_usage()
            # sees is_shutdown_requested()==True and raises BackendDown
            # immediately (0.1ms dispatch_exhausted on every sim end).
            from maxim.models.language.cancellation import reset_shutdown

            logger.debug("LLM shutdown signal cleared for sim roundup")
            reset_shutdown()
            analyze_simulation(report, llm_router=llm_router)
            save_report(report, base_dir=report_dir)
        except Exception:
            display_status("LLM roundup skipped (model unavailable after shutdown)")
    elif llm_router is not None:
        display_status("Skipping LLM roundup (session cost ceiling reached)")

    # Emit machine-readable report when --report-json was requested via
    # MAXIM_REPORT_JSON.  Set by cli.py from args.report_json so the env
    # var is the contract — orchestrator does NOT import argparse.  Pop
    # (not just read) so that two back-to-back sims in the menu loop do
    # not silently overwrite the first sim's report file when only the
    # first invocation passed --report-json.
    _report_json_path = os.environ.pop("MAXIM_REPORT_JSON", "").strip()
    if _report_json_path:
        try:
            emit_report_json(report, _report_json_path)
        except Exception as e:
            logger.warning("Failed to emit report JSON to %r: %s", _report_json_path, e)

    if _is_interactive:
        # Show the report IN the Live panel so the user can scroll it.
        # Reset scroll to bottom first so the report appears at the end,
        # then scroll up to show the start of the report.
        display = get_active_display()
        if display is not None:
            display.scroll(-999999)  # Jump to bottom before report

        log_count_before = display.log_count if display is not None else 0
        _saved_session_dir = Path(report_dir) / report.session_id
        print_report(report, session_dir=_saved_session_dir)
        log_count_after = display.log_count if display is not None else 0
        report_lines = log_count_after - log_count_before

        if display is not None:
            # Scroll up to show the start of the report
            if report_lines > 0:
                display.scroll(report_lines)
            display.set_prompt(
                "Tell me a new simulation to imagine (memory carries over), or press Enter to finish.\n\n> "
            )
            display.set_urgent(True)

        # Wait for user input: a goal (continue) or Enter (finish).
        # Live is still running — arrow keys scroll the report.
        _new_goal = ""
        _stdin = __import__("sys").stdin
        _can_raw = _stdin is not None and hasattr(_stdin, "isatty") and _stdin.isatty()
        if _can_raw:
            try:
                import os as _os3
                import select as _sel3
                import termios as _term3
                import tty as _tty3

                _fd3 = _stdin.fileno()
                _old3 = _term3.tcgetattr(_fd3)
                _buf3: list[str] = []
                try:
                    _tty3.setcbreak(_fd3)
                    _new3 = _term3.tcgetattr(_fd3)
                    _new3[3] &= ~_term3.ECHO
                    _term3.tcsetattr(_fd3, _term3.TCSADRAIN, _new3)

                    while True:
                        ready, _, _ = _sel3.select([_stdin], [], [], 0.1)
                        if not ready:
                            continue
                        ch = _os3.read(_fd3, 1).decode("utf-8", errors="replace")
                        if ch in ("\n", "\r"):
                            _new_goal = "".join(_buf3).strip()
                            break
                        elif ch == "\x7f" or ch == "\x08":
                            if _buf3:
                                _buf3.pop()
                        elif ch == "\x15":
                            _buf3.clear()
                        elif ch == "\x1b":
                            rest = _os3.read(_fd3, 2)
                            if len(rest) == 2 and display is not None:
                                seq = rest.decode("ascii", errors="replace")
                                if seq == "[A":
                                    display.scroll(3)
                                elif seq == "[B":
                                    display.scroll(-3)
                                elif seq == "[C":
                                    display.scroll(-999999)
                                elif seq == "[D":
                                    approx = display.page_height
                                    display.scroll(approx)
                        elif ch == "\x03":
                            break
                        elif ch >= " ":
                            _buf3.append(ch)

                        # Update prompt with typed text
                        if display is not None:
                            typed = "".join(_buf3)
                            display.set_prompt(
                                f"Tell me a new simulation to imagine (memory carries over), or press Enter to finish.\n\n> {typed}"
                            )
                finally:
                    _term3.tcsetattr(_fd3, _term3.TCSADRAIN, _old3)
            except Exception:
                pass

        if display is not None:
            display.set_urgent(False)
            display.stop()

        if _new_goal and _new_goal.lower() not in ("/cancel", "quit", "exit"):
            # Consolidate memory before restarting with a new goal.
            # Without this, in-session learning (NAc decay, hippocampus
            # consolidation, semantic embeddings) is lost on /new.
            if aut_memory_hub is not None:
                try:
                    aut_memory_hub.on_session_end()
                except Exception as _mhe:
                    logger.warning("Memory consolidation before /new failed: %s", _mhe)
            # NOTE: This recurses. Depth is bounded by human interaction
            # (each level requires typing a new goal + running a full sim).
            # RecursionError after ~50-100 is theoretically possible but
            # extremely unlikely in practice.
            # persistent_agent threads through: dropping it would silently
            # rebuild a throwaway sim_aut for the follow-up goal — the exact
            # mis-route this seam kills. Re-adoption re-snapshots the lease
            # (the outer restore already ran above). (Review fold: Arch #3.)
            return start_simulation_mode(
                goal=_new_goal,
                mode=mode,
                max_turns=max_turns,
                response_timeout=response_timeout,
                no_sim_env=no_sim_env,
                debug=debug,
                persistent_agent=persistent_agent,
            )
    else:
        # Non-interactive: just print the report
        print_report(report, session_dir=Path(report_dir) / report.session_id)

    # ── Capture detailed data for programmatic access ──────────────────
    # Tool usage stats from the inner executor (before wrappers)
    _tool_stats: dict[str, Any] = {}
    try:
        # Unwrap FearGated/Pain wrappers to reach the inner Executor
        _inner = aut_executor
        for _attr in ("_executor", "_executor"):
            if hasattr(_inner, _attr):
                _inner = getattr(_inner, _attr)
        if hasattr(_inner, "tool_usage_stats"):
            _tool_stats = _inner.tool_usage_stats()
    except Exception as e:
        logger.warning("Failed to collect tool_usage_stats for SimulationResult: %s", e, exc_info=True)

    # Serialized action history
    _actions: list[dict[str, Any]] = []
    try:
        for a in bridge.get_all_actions():
            _actions.append(
                {
                    "timestamp": a.timestamp,
                    "tool_name": a.tool_name,
                    "tool_args": getattr(a, "tool_args", {}),
                    "result_success": a.result_success,
                    "result_output": str(a.result_output)[:200] if a.result_output else None,
                    "blocked": a.blocked,
                    "block_reason": a.block_reason,
                }
            )
    except Exception as e:
        logger.warning("Failed to serialize action history for SimulationResult: %s", e, exc_info=True)

    # Subsystem snapshot
    _snapshot: dict[str, Any] = {}
    if aut_introspector is not None:
        try:
            _snapshot = aut_introspector.benchmark_snapshot()
        except Exception as e:
            logger.warning("Failed to collect subsystem snapshot for SimulationResult: %s", e, exc_info=True)

    # JSON parse compliance
    _router_stats: dict[str, Any] = {}
    try:
        from maxim.models.language.json_parser import json_parse_stats

        _router_stats = json_parse_stats()
    except Exception as e:
        logger.debug("json_parse_stats unavailable: %s", e)

    _session_dir = str(Path(report_dir) / report.session_id)

    result = SimulationResult(
        goal=goal,
        mode=mode,
        turns=report.turns,
        total_actions=report.total_actions,
        blocked_actions=report.blocked_actions,
        duration_s=duration,
        finish_reason=finish_reason,
        summary=report.llm_summary,
        session_id=report.session_id,
        session_dir=_session_dir,
        campaign_analysis=campaign_analysis
        if pre_campaign_turns
        else (dm_rollup or _build_basic_analysis(aut_introspector)),
        introspector=aut_introspector,
        tool_stats=_tool_stats,
        actions=_actions,
        subsystem_snapshot=_snapshot,
        router_stats=_router_stats,
    )

    return result