codex-autorunner 0.1.2__py3-none-any.whl → 1.1.0__py3-none-any.whl

codex_autorunner/core/engine.py

@@ -1,6 +1,9 @@
 import asyncio
 import contextlib
 import dataclasses
+import hashlib
+import importlib
+import inspect
 import json
 import logging
 import os
@@ -8,52 +11,45 @@ import signal
 import threading
 import time
 import traceback
+import uuid
 from collections import Counter
 from datetime import datetime, timezone
 from logging.handlers import RotatingFileHandler
 from pathlib import Path
-from typing import IO, Any, Dict, Iterator, Optional, Union
+from typing import IO, Any, Awaitable, Callable, Iterator, Optional
 
 import yaml
 
-from ..agents.factory import create_orchestrator
-from ..agents.opencode.logging import OpenCodeEventFormatter
-from ..agents.opencode.runtime import (
-    OpenCodeTurnOutput,
-    build_turn_id,
-    collect_opencode_output,
-    extract_session_id,
-    map_approval_policy_to_permission,
-    opencode_missing_env,
-    parse_message_response,
-    split_model_id,
-)
-from ..agents.opencode.supervisor import OpenCodeSupervisor, OpenCodeSupervisorError
 from ..agents.registry import validate_agent_id
-from ..integrations.app_server.client import (
-    CodexAppServerError,
-    _extract_thread_id,
-    _extract_thread_id_for_turn,
-    _extract_turn_id,
-)
-from ..integrations.app_server.env import build_app_server_env
-from ..integrations.app_server.supervisor import WorkspaceAppServerSupervisor
 from ..manifest import MANIFEST_VERSION
-from ..web.static_assets import missing_static_assets, resolve_static_dir
+from ..tickets.files import list_ticket_paths, ticket_is_done
 from .about_car import ensure_about_car_file
-from .app_server_events import AppServerEventBuffer
+from .adapter_utils import handle_agent_output
+from .app_server_ids import (
+    extract_thread_id,
+    extract_thread_id_for_turn,
+    extract_turn_id,
+)
 from .app_server_logging import AppServerEventFormatter
 from .app_server_prompts import build_autorunner_prompt
 from .app_server_threads import AppServerThreadRegistry, default_app_server_threads_path
 from .config import (
+    CONFIG_FILENAME,
+    CONFIG_VERSION,
+    DEFAULT_REPO_CONFIG,
     ConfigError,
     RepoConfig,
+    _build_repo_config,
     _is_loopback_host,
+    _load_yaml_dict,
+    _merge_defaults,
+    _validate_repo_config,
     derive_repo_config,
     load_hub_config,
     load_repo_config,
 )
 from .docs import DocsManager, parse_todos
+from .flows.models import FlowEventType
 from .git_utils import GitError, run_git
 from .locks import (
     DEFAULT_RUNNER_CMD_HINTS,
@@ -66,14 +62,29 @@ from .locks import (
 )
 from .notifications import NotificationManager
 from .optional_dependencies import missing_optional_dependencies
+from .ports.agent_backend import AgentBackend
+from .ports.run_event import (
+    ApprovalRequested,
+    Completed,
+    Failed,
+    OutputDelta,
+    RunEvent,
+    RunNotice,
+    Started,
+    TokenUsage,
+    ToolCall,
+)
 from .prompt import build_final_summary_prompt
+from .redaction import redact_text
 from .review_context import build_spec_progress_review_context
 from .run_index import RunIndexStore
 from .state import RunnerState, load_state, now_iso, save_state, state_lock
+from .state_roots import resolve_global_state_root, resolve_repo_state_root
+from .ticket_linter_cli import ensure_ticket_linter
+from .ticket_manager_cli import ensure_ticket_manager
 from .utils import (
     RepoNotFoundError,
     atomic_write,
-    build_opencode_supervisor,
     ensure_executable,
     find_repo_root,
 )
@@ -106,13 +117,11 @@ class RunTelemetry:
     diff: Optional[Any] = None
 
 
-@dataclasses.dataclass
-class ActiveOpencodeRun:
-    session_id: str
-    turn_id: str
-    client: Any
-    interrupted: bool
-    interrupt_event: asyncio.Event
+NotificationHandler = Callable[[dict[str, Any]], Awaitable[None]]
+BackendFactory = Callable[
+    [str, RunnerState, Optional[NotificationHandler]], AgentBackend
+]
+AppServerSupervisorFactory = Callable[[str, Optional[NotificationHandler]], Any]
 
 
 class Engine:
@@ -122,6 +131,10 @@ class Engine:
         *,
         config: Optional[RepoConfig] = None,
         hub_path: Optional[Path] = None,
+        backend_factory: Optional[BackendFactory] = None,
+        app_server_supervisor_factory: Optional[AppServerSupervisorFactory] = None,
+        backend_orchestrator: Optional[Any] = None,
+        agent_id_validator: Optional[Callable[[str], str]] = None,
     ):
         if config is None:
             config = load_repo_config(repo_root, hub_path=hub_path)
@@ -134,21 +147,42 @@ class Engine:
         self._run_index_store = RunIndexStore(self.state_path)
         self.lock_path = self.repo_root / ".codex-autorunner" / "lock"
         self.stop_path = self.repo_root / ".codex-autorunner" / "stop"
+        self._hub_path = hub_path
         self._active_global_handler: Optional[RotatingFileHandler] = None
         self._active_run_log: Optional[IO[str]] = None
         self._app_server_threads = AppServerThreadRegistry(
             default_app_server_threads_path(self.repo_root)
         )
         self._app_server_threads_lock = threading.Lock()
-        self._app_server_supervisor: Optional[WorkspaceAppServerSupervisor] = None
+        self._backend_factory = backend_factory
+        self._app_server_supervisor_factory = app_server_supervisor_factory
+        self._app_server_supervisor: Optional[Any] = None
+        self._backend_orchestrator: Optional[Any] = None
         self._app_server_logger = logging.getLogger("codex_autorunner.app_server")
-        self._app_server_event_formatter = AppServerEventFormatter()
-        self._app_server_events = AppServerEventBuffer()
-        self._opencode_event_formatter = OpenCodeEventFormatter()
-        self._opencode_supervisor: Optional[OpenCodeSupervisor] = None
+        self._agent_id_validator = agent_id_validator or validate_agent_id
+        redact_enabled = self.config.security.get("redact_run_logs", True)
+        self._app_server_event_formatter = AppServerEventFormatter(
+            redact_enabled=redact_enabled
+        )
+        self._opencode_supervisor: Optional[Any] = None
+
+        # Backend orchestrator for protocol-agnostic backend management
+        # Use provided orchestrator if available (for testing), otherwise create it
+        self._backend_orchestrator = None
+        if backend_orchestrator is not None:
+            self._backend_orchestrator = backend_orchestrator
+        elif backend_factory is None and app_server_supervisor_factory is None:
+            self._backend_orchestrator = self._build_backend_orchestrator()
+        else:
+            self._app_server_logger.debug(
+                "Skipping BackendOrchestrator creation because backend_factory or app_server_supervisor_factory is set",
+            )
+            self._backend_orchestrator = None
         self._run_telemetry_lock = threading.Lock()
         self._run_telemetry: Optional[RunTelemetry] = None
         self._last_telemetry_update_time: float = 0.0
+        self._canonical_event_lock = threading.Lock()
+        self._canonical_event_seq: dict[int, int] = {}
         self._last_run_interrupted = False
         self._lock_handle: Optional[FileLock] = None
         # Ensure the interactive TUI briefing doc exists (for web Terminal "New").
@@ -159,6 +193,44 @@ class Engine:
             self._app_server_logger.debug(
                 "Best-effort ABOUT_CAR.md creation failed: %s", exc
             )
+        try:
+            ensure_ticket_linter(self.config.root)
+        except (OSError, IOError) as exc:
+            self._app_server_logger.debug(
+                "Best-effort lint_tickets.py creation failed: %s", exc
+            )
+        try:
+            ensure_ticket_manager(self.config.root)
+        except (OSError, IOError) as exc:
+            self._app_server_logger.debug(
+                "Best-effort ticket_tool.py creation failed: %s", exc
+            )
+
+    def _build_backend_orchestrator(self) -> Optional[Any]:
+        """
+        Dynamically construct BackendOrchestrator without introducing a core -> integrations
+        import-time dependency. Keeps import-boundary checks satisfied.
+        """
+        try:
+            module = importlib.import_module(
+                "codex_autorunner.integrations.agents.backend_orchestrator"
+            )
+            orchestrator_cls = getattr(module, "BackendOrchestrator", None)
+            if orchestrator_cls is None:
+                raise AttributeError("BackendOrchestrator not found in module")
+            return orchestrator_cls(
+                repo_root=self.repo_root,
+                config=self.config,
+                notification_handler=self._handle_app_server_notification,
+                logger=self._app_server_logger,
+            )
+        except Exception as exc:
+            self._app_server_logger.warning(
+                "Failed to create BackendOrchestrator: %s\n%s",
+                exc,
+                traceback.format_exc(),
+            )
+            return None
 
     @staticmethod
     def from_cwd(repo: Optional[Path] = None) -> "Engine":
@@ -262,41 +334,21 @@ class Engine:
         return None
 
     def todos_done(self) -> bool:
-        return self.docs.todos_done()
+        # Ticket-first mode: completion is determined by ticket files, not TODO.md.
+        ticket_dir = self.repo_root / ".codex-autorunner" / "tickets"
+        ticket_paths = list_ticket_paths(ticket_dir)
+        if not ticket_paths:
+            return False
+        return all(ticket_is_done(path) for path in ticket_paths)
 
     def summary_finalized(self) -> bool:
-        """Return True if SUMMARY.md contains the finalization marker."""
-        try:
-            text = self.docs.read_doc("summary")
-        except (FileNotFoundError, OSError) as exc:
-            self._app_server_logger.debug("Failed to read SUMMARY.md: %s", exc)
-            return False
-        return SUMMARY_FINALIZED_MARKER in (text or "")
+        # Legacy docs finalization no longer applies (no SUMMARY doc).
+        return True
 
     def _stamp_summary_finalized(self, run_id: int) -> None:
-        """
-        Append an idempotency marker to SUMMARY.md so the final summary job runs only once.
-        Users may remove the marker to force regeneration.
-        """
-        path = self.config.doc_path("summary")
-        try:
-            existing = path.read_text(encoding="utf-8") if path.exists() else ""
-        except (FileNotFoundError, OSError) as exc:
-            self._app_server_logger.debug(
-                "Failed to read SUMMARY.md for stamping: %s", exc
-            )
-            existing = ""
-        if SUMMARY_FINALIZED_MARKER in existing:
-            return
-        stamp = f"{SUMMARY_FINALIZED_MARKER_PREFIX} run_id={int(run_id)} -->\n"
-        new_text = existing
-        if new_text and not new_text.endswith("\n"):
-            new_text += "\n"
-        # Keep a blank line before the marker for readability.
-        if new_text and not new_text.endswith("\n\n"):
-            new_text += "\n"
-        new_text += stamp
-        atomic_write(path, new_text)
+        # No-op: summary file no longer exists.
+        _ = run_id
+        return
 
     async def _execute_run_step(
         self,
@@ -317,43 +369,56 @@ class Engine:
         try:
             todo_before = self.docs.read_doc("todo")
         except (FileNotFoundError, OSError) as exc:
-            self._app_server_logger.debug("Failed to read TODO.md before run: %s", exc)
+            self._app_server_logger.debug(
+                "Failed to read TODO.md before run %s: %s", run_id, exc
+            )
             todo_before = ""
         state = load_state(self.state_path)
-        selected_agent = (state.autorunner_agent_override or "codex").strip().lower()
         try:
-            validated_agent = validate_agent_id(selected_agent)
+            validated_agent = self._agent_id_validator(
+                state.autorunner_agent_override or "codex"
+            )
         except ValueError:
             validated_agent = "codex"
             self.log_line(
                 run_id,
-                f"info: unknown agent '{selected_agent}', defaulting to codex",
+                f"info: unknown agent '{state.autorunner_agent_override}', defaulting to codex",
             )
         self._update_state("running", run_id, None, started=True)
         self._last_run_interrupted = False
         self._start_run_telemetry(run_id)
+
+        actor: dict[str, Any] = {
+            "backend": "codex_app_server",
+            "agent_id": validated_agent,
+            "surface": "hub" if self._hub_path else "cli",
+        }
+        mode: dict[str, Any] = {
+            "approval_policy": state.autorunner_approval_policy or "never",
+            "sandbox": state.autorunner_sandbox_mode or "dangerFullAccess",
+        }
+        runner_cfg = self.config.raw.get("runner") or {}
+        review_cfg = runner_cfg.get("review")
+        if isinstance(review_cfg, dict):
+            mode["review_enabled"] = bool(review_cfg.get("enabled"))
+
         with self._run_log_context(run_id):
-            self._write_run_marker(run_id, "start")
-            if validated_agent == "opencode":
-                exit_code = await self._run_opencode_app_server_async(
-                    prompt,
-                    run_id,
-                    model=state.autorunner_model_override,
-                    reasoning=state.autorunner_effort_override,
-                    external_stop_flag=external_stop_flag,
-                )
-            else:
-                exit_code = await self._run_codex_app_server_async(
-                    prompt,
-                    run_id,
-                    external_stop_flag=external_stop_flag,
-                )
+            self._write_run_marker(run_id, "start", actor=actor, mode=mode)
+            exit_code = await self._run_agent_async(
+                agent_id=validated_agent,
+                prompt=prompt,
+                run_id=run_id,
+                state=state,
+                external_stop_flag=external_stop_flag,
+            )
             self._write_run_marker(run_id, "end", exit_code=exit_code)
 
         try:
             todo_after = self.docs.read_doc("todo")
         except (FileNotFoundError, OSError) as exc:
-            self._app_server_logger.debug("Failed to read TODO.md after run: %s", exc)
+            self._app_server_logger.debug(
+                "Failed to read TODO.md after run %s: %s", run_id, exc
+            )
             todo_after = ""
         todo_delta = self._compute_todo_attribution(todo_before, todo_after)
         todo_snapshot = self._build_todo_snapshot(todo_before, todo_after)
@@ -362,6 +427,7 @@ class Engine:
             "todo_snapshot": todo_snapshot,
         }
         telemetry = self._snapshot_run_telemetry(run_id)
+        usage_payload: Optional[dict[str, Any]] = None
         if (
             telemetry
             and telemetry.thread_id
@@ -374,42 +440,51 @@ class Engine:
                     thread_id=telemetry.thread_id, run_id=run_id
                 )
             delta = self._compute_token_delta(baseline, telemetry.token_total)
-            run_updates["token_usage"] = {
+            token_usage_payload = {
                 "delta": delta,
                 "thread_total_before": baseline,
                 "thread_total_after": telemetry.token_total,
             }
+            run_updates["token_usage"] = token_usage_payload
+            usage_payload = {
+                "run_id": run_id,
+                "captured_at": timestamp(),
+                "agent": validated_agent,
+                "thread_id": telemetry.thread_id,
+                "turn_id": telemetry.turn_id,
+                "token_usage": token_usage_payload,
+                # Use getattr() for optional config attributes that may not exist in all config versions
+                "cache_scope": getattr(self.config.usage, "cache_scope", "global"),
+            }
         artifacts: dict[str, str] = {}
+        if usage_payload is not None:
+            usage_path = self._write_run_usage_artifact(run_id, usage_payload)
+            if usage_path is not None:
+                artifacts["usage_path"] = str(usage_path)
+        redact_enabled = self.config.security.get("redact_run_logs", True)
         if telemetry and telemetry.plan is not None:
-            try:
-                plan_content = (
-                    telemetry.plan
-                    if isinstance(telemetry.plan, str)
-                    else json.dumps(
-                        telemetry.plan, ensure_ascii=True, indent=2, default=str
-                    )
-                )
-            except (TypeError, ValueError) as exc:
-                self._app_server_logger.debug(
-                    "Failed to serialize plan to JSON: %s", exc
-                )
-                plan_content = json.dumps(
-                    {"plan": str(telemetry.plan)}, ensure_ascii=True, indent=2
-                )
+            plan_content = self._serialize_plan_content(
+                telemetry.plan, redact_enabled=redact_enabled, run_id=run_id
+            )
             plan_path = self._write_run_artifact(run_id, "plan.json", plan_content)
             artifacts["plan_path"] = str(plan_path)
         if telemetry and telemetry.diff is not None:
-            diff_content = (
-                telemetry.diff
-                if isinstance(telemetry.diff, str)
-                else json.dumps(
-                    telemetry.diff, ensure_ascii=True, indent=2, default=str
-                )
+            diff_content = self._serialize_diff_content(
+                telemetry.diff, redact_enabled=redact_enabled
             )
-            diff_path = self._write_run_artifact(run_id, "diff.patch", diff_content)
-            artifacts["diff_path"] = str(diff_path)
+            if diff_content is not None:
+                diff_path = self._write_run_artifact(run_id, "diff.patch", diff_content)
+                artifacts["diff_path"] = str(diff_path)
         if artifacts:
             run_updates["artifacts"] = artifacts
+        if redact_enabled:
+            from .redaction import get_redaction_patterns
+
+            run_updates["security"] = {
+                "redaction_enabled": True,
+                "redaction_version": "1.0",
+                "redaction_patterns": get_redaction_patterns(),
+            }
         if run_updates:
             self._merge_run_index_entry(run_id, run_updates)
         self._clear_run_telemetry(run_id)
@@ -457,7 +532,7 @@ class Engine:
                 text = run_log.read_text(encoding="utf-8")
             except (FileNotFoundError, OSError) as exc:
                 self._app_server_logger.debug(
-                    "Failed to read previous run log: %s", exc
+                    "Failed to read previous run log for run %s: %s", run_id, exc
                 )
                 text = ""
             if text:
@@ -508,10 +583,12 @@ class Engine:
             try:
                 return run_log.read_text(encoding="utf-8")
             except (FileNotFoundError, OSError) as exc:
-                self._app_server_logger.debug("Failed to read run log block: %s", exc)
+                self._app_server_logger.debug(
+                    "Failed to read run log block for run %s: %s", run_id, exc
+                )
                 return None
         if index_entry:
-            block = self._read_log_range(index_entry)
+            block = self._read_log_range(run_id, index_entry)
             if block is not None:
                 return block
         if not self.log_path.exists():
@@ -555,7 +632,7 @@ class Engine:
                 return "\n".join(buf) if buf else None
         except (FileNotFoundError, OSError, ValueError) as exc:
             self._app_server_logger.debug(
-                "Failed to read full log for run block: %s", exc
+                "Failed to read full log for run %s block: %s", run_id, exc
             )
             return None
         return None
@@ -582,7 +659,7 @@ class Engine:
                 self._active_run_log.flush()
             except (OSError, IOError) as exc:
                 self._app_server_logger.warning(
-                    "Failed to write to active run log: %s", exc
+                    "Failed to write to active run log for run %s: %s", run_id, exc
                 )
         else:
             run_log = self._run_log_path(run_id)
@@ -607,7 +684,69 @@ class Engine:
                 f.write(_json.dumps(event_data) + "\n")
         except (OSError, IOError) as exc:
             self._app_server_logger.warning(
-                "Failed to write event to events log: %s", exc
+                "Failed to write event to events log for run %s: %s", run_id, exc
+            )
+        event_type = {
+            "run.started": FlowEventType.RUN_STARTED,
+            "run.finished": FlowEventType.RUN_FINISHED,
+            "run.state_changed": FlowEventType.RUN_STATE_CHANGED,
+            "run.no_progress": FlowEventType.RUN_NO_PROGRESS,
+            "token.updated": FlowEventType.TOKEN_USAGE,
+            "plan.updated": FlowEventType.PLAN_UPDATED,
+            "diff.updated": FlowEventType.DIFF_UPDATED,
+        }.get(event)
+        if event_type is not None:
+            self._emit_canonical_event(run_id, event_type, payload)
+
+    def _emit_canonical_event(
+        self,
+        run_id: int,
+        event_type: FlowEventType,
+        data: Optional[dict[str, Any]] = None,
+        *,
+        step_id: Optional[str] = None,
+        timestamp_override: Optional[str] = None,
+    ) -> None:
+        event_payload: dict[str, Any] = {
+            "id": uuid.uuid4().hex,
+            "run_id": str(run_id),
+            "event_type": event_type.value,
+            "timestamp": timestamp_override or now_iso(),
+            "data": data or {},
+        }
+        if step_id is not None:
+            event_payload["step_id"] = step_id
+        self._ensure_run_log_dir()
+        with self._canonical_event_lock:
+            seq = self._canonical_event_seq.get(run_id, 0) + 1
+            self._canonical_event_seq[run_id] = seq
+            event_payload["seq"] = seq
+            events_path = self._canonical_events_log_path(run_id)
+            try:
+                with events_path.open("a", encoding="utf-8") as f:
+                    f.write(json.dumps(event_payload, ensure_ascii=True) + "\n")
+            except (OSError, IOError) as exc:
+                self._app_server_logger.warning(
+                    "Failed to write canonical event for run %s: %s", run_id, exc
+                )
+
+    async def _cancel_task_with_notice(
+        self,
+        run_id: int,
+        task: asyncio.Task[Any],
+        *,
+        name: str,
+    ) -> None:
+        if task.done():
+            return
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            self._emit_canonical_event(
+                run_id,
+                FlowEventType.RUN_CANCELLED,
+                {"task": name},
             )
 
     def _ensure_log_path(self) -> None:
@@ -619,18 +758,32 @@ class Engine:
     def _events_log_path(self, run_id: int) -> Path:
         return self.log_path.parent / "runs" / f"run-{run_id}.events.jsonl"
 
+    def _canonical_events_log_path(self, run_id: int) -> Path:
+        return self.log_path.parent / "runs" / f"run-{run_id}.events.canonical.jsonl"
+
     def _ensure_run_log_dir(self) -> None:
         (self.log_path.parent / "runs").mkdir(parents=True, exist_ok=True)
 
     def _write_run_marker(
-        self, run_id: int, marker: str, exit_code: Optional[int] = None
+        self,
+        run_id: int,
+        marker: str,
+        exit_code: Optional[int] = None,
+        *,
+        actor: Optional[dict[str, Any]] = None,
+        mode: Optional[dict[str, Any]] = None,
     ) -> None:
         suffix = ""
         if marker == "end":
             suffix = f" (code {exit_code})"
             self._emit_event(run_id, "run.finished", exit_code=exit_code)
         elif marker == "start":
-            self._emit_event(run_id, "run.started")
+            payload: dict[str, Any] = {}
+            if actor is not None:
+                payload["actor"] = actor
+            if mode is not None:
+                payload["mode"] = mode
+            self._emit_event(run_id, "run.started", **payload)
         text = f"=== run {run_id} {marker}{suffix} ==="
         offset = self._emit_global_line(text)
         if self._active_run_log is not None:
@@ -639,14 +792,18 @@ class Engine:
                 self._active_run_log.flush()
             except (OSError, IOError) as exc:
                 self._app_server_logger.warning(
-                    "Failed to write marker to active run log: %s", exc
+                    "Failed to write marker to active run log for run %s: %s",
+                    run_id,
+                    exc,
                 )
         else:
             self._ensure_run_log_dir()
             run_log = self._run_log_path(run_id)
             with run_log.open("a", encoding="utf-8") as f:
                 f.write(f"{text}\n")
-        self._update_run_index(run_id, marker, offset, exit_code)
+        self._update_run_index(
+            run_id, marker, offset, exit_code, actor=actor, mode=mode
+        )
 
     def _emit_global_line(self, text: str) -> Optional[tuple[int, int]]:
         if self._active_global_handler is None:
@@ -693,6 +850,7 @@ class Engine:
     def _run_log_context(self, run_id: int) -> Iterator[None]:
         self._ensure_log_path()
         self._ensure_run_log_dir()
+        # Use getattr() for optional config attributes that may not exist in all config versions
         max_bytes = getattr(self.config.log, "max_bytes", None) or 0
         backup_count = getattr(self.config.log, "backup_count", 0) or 0
         handler = RotatingFileHandler(
@@ -715,14 +873,13 @@ class Engine:
                     handler.close()
                 except (OSError, IOError) as exc:
                     self._app_server_logger.debug(
-                        "Failed to close run log handler: %s", exc
+                        "Failed to close run log handler for run %s: %s", run_id, exc
                     )
 
     def _start_run_telemetry(self, run_id: int) -> None:
         with self._run_telemetry_lock:
             self._run_telemetry = RunTelemetry(run_id=run_id)
         self._app_server_event_formatter.reset()
-        self._opencode_event_formatter.reset()
 
     def _update_run_telemetry(self, run_id: int, **updates: Any) -> None:
         with self._run_telemetry_lock:
@@ -747,6 +904,75 @@ class Engine:
                 return
             self._run_telemetry = None
 
+    @staticmethod
+    def _normalize_diff_payload(diff: Any) -> Optional[Any]:
+        if diff is None:
+            return None
+        if isinstance(diff, str):
+            return diff if diff.strip() else None
+        if isinstance(diff, dict):
+            # Prefer meaningful fields if present.
+            for key in ("diff", "patch", "content", "value"):
+                if key in diff:
+                    val = diff.get(key)
+                    if isinstance(val, str) and val.strip():
+                        return val
+                    if val not in (None, "", [], {}, ()):
+                        return diff
+            for val in diff.values():
+                if isinstance(val, str) and val.strip():
+                    return diff
+                if val not in (None, "", [], {}, ()):
+                    return diff
+            return None
+        return diff
+
+    @staticmethod
+    def _hash_content(content: str) -> str:
+        return hashlib.sha256((content or "").encode("utf-8")).hexdigest()
+
+    def _serialize_plan_content(
+        self,
+        plan: Any,
+        *,
+        redact_enabled: bool,
+        run_id: Optional[int] = None,
+    ) -> str:
+        try:
+            content = (
+                plan
+                if isinstance(plan, str)
+                else json.dumps(plan, ensure_ascii=True, indent=2, default=str)
+            )
+        except (TypeError, ValueError) as exc:
+            if run_id is not None:
+                self._app_server_logger.debug(
+                    "Failed to serialize plan to JSON for run %s: %s", run_id, exc
+                )
+            else:
+                self._app_server_logger.debug(
+                    "Failed to serialize plan to JSON: %s", exc
+                )
+            content = json.dumps({"plan": str(plan)}, ensure_ascii=True, indent=2)
+        if redact_enabled:
+            content = redact_text(content)
+        return content
+
+    def _serialize_diff_content(
+        self, diff: Any, *, redact_enabled: bool
+    ) -> Optional[str]:
+        normalized = self._normalize_diff_payload(diff)
+        if normalized is None:
+            return None
+        content = (
+            normalized
+            if isinstance(normalized, str)
+            else json.dumps(normalized, ensure_ascii=True, indent=2, default=str)
+        )
+        if redact_enabled:
+            content = redact_text(content)
+        return content
+
     def _maybe_update_run_index_telemetry(
         self, run_id: int, min_interval_seconds: float = 3.0
     ) -> None:
@@ -789,12 +1015,14 @@ class Engine:
         params_raw = message.get("params")
         params = params_raw if isinstance(params_raw, dict) else {}
         thread_id = (
-            _extract_thread_id_for_turn(params)
-            or _extract_thread_id(params)
-            or _extract_thread_id(message)
+            extract_thread_id_for_turn(params)
+            or extract_thread_id(params)
+            or extract_thread_id(message)
         )
-        turn_id = _extract_turn_id(params) or _extract_turn_id(message)
+        turn_id = extract_turn_id(params) or extract_turn_id(message)
         run_id: Optional[int] = None
+        plan_update: Any = None
+        diff_update: Any = None
         with self._run_telemetry_lock:
             telemetry = self._run_telemetry
             if telemetry is None:
@@ -819,17 +1047,60 @@ class Engine:
                         self._maybe_update_run_index_telemetry(run_id)
                         self._emit_event(run_id, "token.updated", token_total=total)
             if method == "turn/plan/updated":
-                telemetry.plan = params.get("plan") if "plan" in params else params
+                plan_update = params.get("plan") if "plan" in params else params
+                telemetry.plan = plan_update
             if method == "turn/diff/updated":
-                diff = (
-                    params.get("diff")
-                    or params.get("patch")
-                    or params.get("content")
-                    or params.get("value")
-                )
-                telemetry.diff = diff if diff is not None else params
+                diff: Any = None
+                for key in ("diff", "patch", "content", "value"):
+                    if key in params:
+                        diff = params.get(key)
+                        break
+                diff_update = diff if diff is not None else params or None
+                telemetry.diff = diff_update
         if run_id is None:
             return
+        redact_enabled = self.config.security.get("redact_run_logs", True)
+        notification_path = self._append_run_notification(
+            run_id, message, redact_enabled
+        )
+        if notification_path is not None:
+            self._merge_run_index_entry(
+                run_id,
+                {
+                    "artifacts": {
+                        "app_server_notifications_path": str(notification_path)
+                    }
+                },
+            )
+        if plan_update is not None:
+            plan_content = self._serialize_plan_content(
+                plan_update, redact_enabled=redact_enabled, run_id=run_id
+            )
+            plan_path = self._write_run_artifact(run_id, "plan.json", plan_content)
+            self._merge_run_index_entry(
+                run_id, {"artifacts": {"plan_path": str(plan_path)}}
+            )
+            self._emit_event(
+                run_id,
+                "plan.updated",
+                plan_hash=self._hash_content(plan_content),
+                plan_path=str(plan_path),
+            )
+        if diff_update is not None:
+            diff_content = self._serialize_diff_content(
+                diff_update, redact_enabled=redact_enabled
+            )
+            if diff_content is not None:
+                diff_path = self._write_run_artifact(run_id, "diff.patch", diff_content)
+                self._merge_run_index_entry(
+                    run_id, {"artifacts": {"diff_path": str(diff_path)}}
+                )
+                self._emit_event(
+                    run_id,
+                    "diff.updated",
+                    diff_hash=self._hash_content(diff_content),
+                    diff_path=str(diff_path),
+                )
         for line in self._app_server_event_formatter.format_event(message):
             self.log_line(run_id, f"stdout: {line}" if line else "stdout: ")
 
@@ -847,7 +1118,10 @@ class Engine:
         """
         try:
             state = load_state(self.state_path)
-        except Exception:
+        except Exception as exc:
+            self._app_server_logger.warning(
+                "Failed to load state during run index reconciliation: %s", exc
+            )
             return
 
         active_pid: Optional[int] = None
@@ -870,7 +1144,10 @@ class Engine:
         now = now_iso()
         try:
             index = self._run_index_store.load_all()
-        except Exception:
+        except Exception as exc:
+            self._app_server_logger.warning(
+                "Failed to load run index during reconciliation: %s", exc
+            )
             return
 
         for key, entry in index.items():
@@ -917,7 +1194,10 @@ class Engine:
                         ),
                     },
                 )
-            except Exception:
+            except Exception as exc:
+                self._app_server_logger.warning(
+                    "Failed to reconcile run index entry for run %d: %s", run_id, exc
+                )
                 continue
 
     def _merge_run_index_entry(self, run_id: int, updates: dict[str, Any]) -> None:
@@ -929,6 +1209,9 @@ class Engine:
         marker: str,
         offset: Optional[tuple[int, int]],
         exit_code: Optional[int],
+        *,
+        actor: Optional[dict[str, Any]] = None,
+        mode: Optional[dict[str, Any]] = None,
     ) -> None:
         self._run_index_store.update_marker(
             run_id,
@@ -937,6 +1220,8 @@ class Engine:
             exit_code,
             log_path=str(self.log_path),
             run_log_path=str(self._run_log_path(run_id)),
+            actor=actor,
+            mode=mode,
         )
 
     def _list_from_counts(self, source: list[str], counts: Counter[str]) -> list[str]:
@@ -1021,7 +1306,10 @@ class Engine:
                 entry_id = int(key)
             except (TypeError, ValueError) as exc:
                 self._app_server_logger.debug(
-                    "Failed to parse run index key '%s': %s", key, exc
+                    "Failed to parse run index key '%s' while resolving run %s: %s",
+                    key,
+                    run_id,
+                    exc,
                 )
                 continue
             if entry_id >= run_id:
@@ -1106,7 +1394,52 @@ class Engine:
         atomic_write(path, content)
         return path
 
-    def _read_log_range(self, entry: dict) -> Optional[str]:
+    def _write_run_usage_artifact(
+        self, run_id: int, payload: dict[str, Any]
+    ) -> Optional[Path]:
+        self._ensure_run_log_dir()
+        run_dir = self.log_path.parent / "runs" / str(run_id)
+        try:
+            run_dir.mkdir(parents=True, exist_ok=True)
+            path = run_dir / "usage.json"
+            atomic_write(
+                path,
+                json.dumps(payload, ensure_ascii=True, indent=2, default=str),
+            )
+            return path
+        except OSError as exc:
+            self._app_server_logger.warning(
+                "Failed to write usage artifact for run %s: %s", run_id, exc
+            )
+            return None
+
+    def _app_server_notifications_path(self, run_id: int) -> Path:
+        return (
+            self.log_path.parent
+            / "runs"
+            / f"run-{run_id}.app_server.notifications.jsonl"
+        )
+
+    def _append_run_notification(
+        self, run_id: int, message: dict[str, Any], redact_enabled: bool
+    ) -> Optional[Path]:
+        self._ensure_run_log_dir()
+        path = self._app_server_notifications_path(run_id)
+        payload = {"ts": timestamp(), "message": message}
+        try:
+            line = json.dumps(payload, ensure_ascii=True, default=str)
+            if redact_enabled:
+                line = redact_text(line)
+            with path.open("a", encoding="utf-8") as f:
+                f.write(line + "\n")
+        except (OSError, IOError, TypeError, ValueError) as exc:
+            self._app_server_logger.warning(
+                "Failed to write app-server notification for run %s: %s", run_id, exc
+            )
+            return None
+        return path
+
+    def _read_log_range(self, run_id: int, entry: dict) -> Optional[str]:
         start = entry.get("start_offset")
         end = entry.get("end_offset")
         if start is None or end is None:
@@ -1115,7 +1448,9 @@ class Engine:
             start_offset = int(start)
             end_offset = int(end)
         except (TypeError, ValueError) as exc:
-            self._app_server_logger.debug("Failed to parse log range offsets: %s", exc)
+            self._app_server_logger.debug(
+                "Failed to parse log range offsets for run %s: %s", run_id, exc
+            )
             return None
         if end_offset < start_offset:
             return None
@@ -1131,7 +1466,9 @@ class Engine:
                 data = f.read(end_offset - start_offset)
             return data.decode("utf-8", errors="replace")
         except (FileNotFoundError, OSError) as exc:
-            self._app_server_logger.debug("Failed to read log range: %s", exc)
+            self._app_server_logger.debug(
+                "Failed to read log range for run %s: %s", run_id, exc
+            )
             return None
 
     def _build_app_server_prompt(self, prev_output: Optional[str]) -> str:
@@ -1154,7 +1491,6 @@ class Engine:
                     prompt,
                     run_id,
                     external_stop_flag=external_stop_flag,
-                    reuse_supervisor=False,
                 )
             )
         except RuntimeError as exc:
@@ -1166,114 +1502,312 @@ class Engine:
                 return 1
             raise
 
-    async def _run_agent_turn_async(
+    async def _run_agent_async(
         self,
+        *,
         agent_id: str,
         prompt: str,
         run_id: int,
-        *,
-        external_stop_flag: Optional[threading.Event] = None,
+        state: RunnerState,
+        external_stop_flag: Optional[threading.Event],
     ) -> int:
-        orchestrator = self._get_orchestrator(agent_id)
-        if orchestrator is None:
-            self.log_line(
-                run_id,
-                f"error: agent '{agent_id}' backend is not configured",
+        """
+        Run an agent turn using the specified backend.
+
+        This method is protocol-agnostic - it determines the appropriate
+        model/reasoning parameters based on the agent_id and delegates to
+        either the BackendOrchestrator or _run_agent_backend_async().
+        """
+        # Determine model and reasoning parameters based on agent
+        if agent_id == "codex":
+            model = state.autorunner_model_override or self.config.codex_model
+            reasoning = state.autorunner_effort_override or self.config.codex_reasoning
+        elif agent_id == "opencode":
+            model = state.autorunner_model_override
+            reasoning = state.autorunner_effort_override
+        else:
+            # Fallback to codex defaults for unknown agents
+            model = state.autorunner_model_override or self.config.codex_model
+            reasoning = state.autorunner_effort_override or self.config.codex_reasoning
+
+        # Use BackendOrchestrator if available, otherwise fall back to old method
+        if agent_id == "codex":
+            session_key = "autorunner"
+        elif agent_id == "opencode":
+            session_key = "autorunner.opencode"
+        else:
+            session_key = "autorunner"
+
+        if self._backend_orchestrator is not None:
+            return await self._run_agent_via_orchestrator(
+                agent_id=agent_id,
+                prompt=prompt,
+                run_id=run_id,
+                state=state,
+                model=model,
+                reasoning=reasoning,
+                session_key=session_key,
+                external_stop_flag=external_stop_flag,
             )
-            return 1
 
-        thread_key = f"autorunner.{agent_id}"
-        with state_lock(self.state_path):
-            state = load_state(self.state_path)
-        effective_model = state.autorunner_model_override or self.config.codex_model
-        effective_effort = (
-            state.autorunner_effort_override or self.config.codex_reasoning
+        # Fallback to old method for backward compatibility (testing)
+        return await self._run_agent_backend_async(
+            agent_id=agent_id,
+            prompt=prompt,
+            run_id=run_id,
+            state=state,
+            session_key=session_key,
+            model=model,
+            reasoning=reasoning,
+            external_stop_flag=external_stop_flag,
         )
 
-        with self._app_server_threads_lock:
-            conversation_id = self._app_server_threads.get_thread_id(thread_key)
-            if not conversation_id:
-                try:
-                    conversation_info = (
-                        await orchestrator.create_or_resume_conversation(
-                            self.repo_root, agent_id
-                        )
-                    )
-                    conversation_id = conversation_info.id
-                    self._app_server_threads.set_thread_id(thread_key, conversation_id)
-                except Exception as exc:
-                    self.log_line(
-                        run_id, f"error: failed to create conversation: {exc}"
-                    )
-                    return 1
+    async def _run_agent_via_orchestrator(
+        self,
+        *,
+        agent_id: str,
+        prompt: str,
+        run_id: int,
+        state: RunnerState,
+        model: Optional[str],
+        reasoning: Optional[str],
+        session_key: str,
+        external_stop_flag: Optional[threading.Event],
+    ) -> int:
+        """
+        Run an agent turn using the BackendOrchestrator.
+
+        This method uses the orchestrator's protocol-agnostic interface to run
+        a turn on the backend, handling all events and emitting canonical events.
+        """
+        orchestrator = self._backend_orchestrator
+        assert (
+            orchestrator is not None
+        ), "orchestrator should be set when calling this method"
 
-        if conversation_id:
-            self._update_run_telemetry(run_id, thread_id=conversation_id)
+        events: asyncio.Queue[Optional[RunEvent]] = asyncio.Queue()
 
-        approval_policy = state.autorunner_approval_policy or "never"
-        sandbox_mode = state.autorunner_sandbox_mode or "dangerFullAccess"
-        if sandbox_mode == "workspaceWrite":
-            sandbox_policy: Union[Dict[str, Any], str] = {
-                "type": "workspaceWrite",
-                "writableRoots": [str(self.repo_root)],
-                "networkAccess": bool(state.autorunner_workspace_write_network),
-            }
-        else:
-            sandbox_policy = sandbox_mode
+        async def _produce_events() -> None:
+            try:
+                async for event in orchestrator.run_turn(
+                    agent_id=agent_id,
+                    state=state,
+                    prompt=prompt,
+                    model=model,
+                    reasoning=reasoning,
+                    session_key=session_key,
+                ):
+                    await events.put(event)
+            except Exception as exc:
+                await events.put(Failed(timestamp=now_iso(), error_message=str(exc)))
+            finally:
+                await events.put(None)
 
-        stop_event = asyncio.Event()
-        stop_task: Optional[asyncio.Task] = None
+        producer_task = asyncio.create_task(_produce_events())
+        stop_task = asyncio.create_task(self._wait_for_stop(external_stop_flag))
+        timeout_seconds = self.config.app_server.turn_timeout_seconds
+        timeout_task: Optional[asyncio.Task] = (
+            asyncio.create_task(asyncio.sleep(timeout_seconds))
+            if timeout_seconds
+            else None
+        )
 
-        if external_stop_flag:
-            stop_task = asyncio.create_task(
-                self._wait_for_stop(external_stop_flag, stop_event)
-            )
+        assistant_messages: list[str] = []
+        final_message: Optional[str] = None
+        failed_error: Optional[str] = None
 
         try:
-            result = await orchestrator.run_turn(
-                self.repo_root,
-                conversation_id,
-                prompt,
-                model=effective_model,
-                reasoning=effective_effort,
-                approval_mode=approval_policy,
-                sandbox_policy=sandbox_policy,
-                should_stop=stop_event.is_set,
-            )
-            if result.get("status") != "completed":
-                self.log_line(
-                    run_id, f"error: turn failed with status {result.get('status')}"
-                )
-                return 1
-            output = result.get("output", "")
-            if output:
-                self._log_app_server_output(run_id, output.splitlines())
-                output_path = self._write_run_artifact(run_id, "output.txt", output)
-                self._merge_run_index_entry(
-                    run_id, {"artifacts": {"output_path": str(output_path)}}
+            while True:
+                get_task = asyncio.create_task(events.get())
+                tasks = {get_task, stop_task}
+                if timeout_task is not None:
+                    tasks.add(timeout_task)
+                done, pending = await asyncio.wait(
+                    tasks, return_when=asyncio.FIRST_COMPLETED
                 )
-            return 0
-        except Exception as exc:
-            self.log_line(run_id, f"error: {exc}")
-            return 1
+
+                if get_task in done:
+                    event = get_task.result()
+                    if event is None:
+                        break
+                    if isinstance(event, Started) and event.session_id:
+                        self._update_run_telemetry(run_id, thread_id=event.session_id)
+                    elif isinstance(event, OutputDelta):
+                        self._emit_canonical_event(
+                            run_id,
+                            FlowEventType.AGENT_STREAM_DELTA,
+                            {
+                                "delta": event.content,
+                                "delta_type": event.delta_type,
+                            },
+                            timestamp_override=event.timestamp,
+                        )
+                        if event.delta_type in {
+                            "assistant_message",
+                            "assistant_stream",
+                        }:
+                            assistant_messages.append(event.content)
+                        elif event.delta_type == "log_line":
+                            self.log_line(
+                                run_id,
+                                (
+                                    f"stdout: {event.content}"
+                                    if event.content
+                                    else "stdout: "
+                                ),
+                            )
+                    elif isinstance(event, ToolCall):
+                        self._emit_canonical_event(
+                            run_id,
+                            FlowEventType.TOOL_CALL,
+                            {
+                                "tool_name": event.tool_name,
+                                "tool_input": event.tool_input,
+                            },
+                            timestamp_override=event.timestamp,
+                        )
+                    elif isinstance(event, ApprovalRequested):
+                        self._emit_canonical_event(
+                            run_id,
+                            FlowEventType.APPROVAL_REQUESTED,
+                            {
+                                "request_id": event.request_id,
+                                "description": event.description,
+                                "context": event.context,
+                            },
+                            timestamp_override=event.timestamp,
+                        )
+                    elif isinstance(event, TokenUsage):
+                        self._emit_canonical_event(
+                            run_id,
+                            FlowEventType.TOKEN_USAGE,
+                            {"usage": event.usage},
+                            timestamp_override=event.timestamp,
+                        )
+                    elif isinstance(event, RunNotice):
+                        notice_type = FlowEventType.RUN_STATE_CHANGED
+                        if event.kind.endswith("timeout"):
+                            notice_type = FlowEventType.RUN_TIMEOUT
+                        elif "cancel" in event.kind:
+                            notice_type = FlowEventType.RUN_CANCELLED
+                        data: dict[str, Any] = {
+                            "kind": event.kind,
+                            "message": event.message,
+                        }
+                        if event.data:
+                            data["data"] = event.data
+                        self._emit_canonical_event(
+                            run_id,
+                            notice_type,
+                            data,
+                            timestamp_override=event.timestamp,
+                        )
+                    elif isinstance(event, Completed):
+                        if event.final_message:
+                            self._emit_canonical_event(
+                                run_id,
+                                FlowEventType.AGENT_MESSAGE_COMPLETE,
+                                {"final_message": event.final_message},
+                                timestamp_override=event.timestamp,
+                            )
+                        if event.final_message:
+                            final_message = event.final_message
+                    elif isinstance(event, Failed):
+                        self.log_line(
+                            run_id,
+                            f"error: backend run failed: {event.error_message}",
+                        )
+                        failed_error = event.error_message
+
+                if stop_task in done:
+                    self._last_run_interrupted = True
+                    self.log_line(run_id, "info: stop requested; interrupting backend")
+                    if not producer_task.done():
+                        producer_task.cancel()
+                        try:
+                            await producer_task
+                        except asyncio.CancelledError:
+                            pass
+                    if timeout_task and not timeout_task.done():
+                        timeout_task.cancel()
+                    try:
+                        await orchestrator.interrupt(agent_id, state)
+                    except Exception as exc:
+                        self.log_line(run_id, f"interrupt failed: {exc}")
+                    if not get_task.done():
+                        get_task.cancel()
+                    for task in pending:
+                        task.cancel()
+                    return 0
+
+                if timeout_task and timeout_task in done:
+                    if not producer_task.done():
+                        producer_task.cancel()
+                        try:
+                            await producer_task
+                        except asyncio.CancelledError:
+                            pass
+                    try:
+                        await orchestrator.interrupt(agent_id, state)
+                    except Exception as exc:
+                        self.log_line(run_id, f"interrupt failed: {exc}")
+                    if not get_task.done():
+                        get_task.cancel()
+                    for task in pending:
+                        task.cancel()
+                    return 1
         finally:
-            if stop_task is not None:
+            if not producer_task.done():
+                producer_task.cancel()
+                try:
+                    await producer_task
+                except asyncio.CancelledError:
+                    pass
+            if timeout_task and not timeout_task.done():
+                timeout_task.cancel()
+            if stop_task and not stop_task.done():
                 stop_task.cancel()
-                with contextlib.suppress(asyncio.CancelledError):
-                    await stop_task
-            if stop_event.is_set():
-                await orchestrator.interrupt_turn(
-                    self.repo_root, conversation_id, grace_seconds=30.0
-                )
-                self._last_run_interrupted = True
 
-    async def _run_codex_app_server_async(
-        self,
+        if failed_error:
+            return 1
+
+        output_messages: list[str] = []
+        if final_message:
+            self.log_line(run_id, final_message)
+            output_messages = [final_message]
+        elif assistant_messages:
+            output_messages = assistant_messages
+
+        if output_messages:
+            handle_agent_output(
+                self._log_app_server_output,
+                self._write_run_artifact,
+                self._merge_run_index_entry,
+                run_id,
+                output_messages,
+            )
+
+        context = orchestrator.get_context()
+        if context:
+            turn_id = context.turn_id or orchestrator.get_last_turn_id()
+            thread_info = context.thread_info or orchestrator.get_last_thread_info()
+            token_total = orchestrator.get_last_token_total()
+            self._update_run_telemetry(
+                run_id,
+                turn_id=turn_id,
+                token_total=token_total,
+            )
+            if thread_info:
+                self._update_run_telemetry(run_id, thread_info=thread_info)
+
+        return 0
+
+    async def _run_codex_app_server_async(
+        self,
         prompt: str,
         run_id: int,
         *,
         external_stop_flag: Optional[threading.Event] = None,
-        reuse_supervisor: bool = True,
     ) -> int:
         config = self.config
         if not config.app_server.command:
@@ -1282,129 +1816,306 @@ class Engine:
                 "error: app-server backend requires app_server.command to be configured",
             )
             return 1
-
-        def _env_builder(
-            workspace_root: Path, _workspace_id: str, state_dir: Path
-        ) -> dict[str, str]:
-            state_dir.mkdir(parents=True, exist_ok=True)
-            return build_app_server_env(
-                config.app_server.command,
-                workspace_root,
-                state_dir,
-                logger=self._app_server_logger,
-                event_prefix="autorunner",
-            )
-
-        supervisor = (
-            self._ensure_app_server_supervisor(_env_builder)
-            if reuse_supervisor
-            else self._build_app_server_supervisor(_env_builder)
-        )
         with state_lock(self.state_path):
             state = load_state(self.state_path)
         effective_model = state.autorunner_model_override or config.codex_model
         effective_effort = state.autorunner_effort_override or config.codex_reasoning
-        approval_policy = state.autorunner_approval_policy or "never"
-        sandbox_mode = state.autorunner_sandbox_mode or "dangerFullAccess"
-        if sandbox_mode == "workspaceWrite":
-            sandbox_policy: Any = {
-                "type": "workspaceWrite",
-                "writableRoots": [str(self.repo_root)],
-                "networkAccess": bool(state.autorunner_workspace_write_network),
-            }
-        else:
-            sandbox_policy = sandbox_mode
+        return await self._run_agent_backend_async(
+            agent_id="codex",
+            prompt=prompt,
+            run_id=run_id,
+            state=state,
+            session_key="autorunner",
+            model=effective_model,
+            reasoning=effective_effort,
+            external_stop_flag=external_stop_flag,
+        )
+
+    async def _run_agent_backend_async(
+        self,
+        *,
+        agent_id: str,
+        prompt: str,
+        run_id: int,
+        state: RunnerState,
+        session_key: str,
+        model: Optional[str],
+        reasoning: Optional[str],
+        external_stop_flag: Optional[threading.Event],
+    ) -> int:
+        if self._backend_factory is None:
+            self.log_line(
+                run_id,
+                f"error: {agent_id} backend factory is not configured for this engine",
+            )
+            return 1
+
         try:
-            client = await supervisor.get_client(self.repo_root)
-            with self._app_server_threads_lock:
-                thread_id = self._app_server_threads.get_thread_id("autorunner")
-                thread_info: Optional[dict[str, Any]] = None
-                if thread_id:
-                    try:
-                        resume_result = await client.thread_resume(thread_id)
-                        resumed = resume_result.get("id")
-                        if isinstance(resumed, str) and resumed:
-                            thread_id = resumed
-                            self._app_server_threads.set_thread_id(
-                                "autorunner", thread_id
-                            )
-                        if isinstance(resume_result, dict):
-                            thread_info = resume_result
-                    except CodexAppServerError:
-                        self._app_server_threads.reset_thread("autorunner")
-                        thread_id = None
-                if not thread_id:
-                    thread = await client.thread_start(str(self.repo_root))
-                    thread_id = thread.get("id")
-                    if not isinstance(thread_id, str) or not thread_id:
-                        self.log_line(
-                            run_id, "error: app-server did not return a thread id"
-                        )
-                        return 1
-                    self._app_server_threads.set_thread_id("autorunner", thread_id)
-                    if isinstance(thread, dict):
-                        thread_info = thread
-            if thread_id:
-                self._update_run_telemetry(run_id, thread_id=thread_id)
-            turn_kwargs: dict[str, Any] = {}
-            if effective_model:
-                turn_kwargs["model"] = str(effective_model)
-            if effective_effort:
-                turn_kwargs["effort"] = str(effective_effort)
-            handle = await client.turn_start(
-                thread_id,
-                prompt,
-                approval_policy=approval_policy,
-                sandbox_policy=sandbox_policy,
-                **turn_kwargs,
+            backend = self._backend_factory(
+                agent_id, state, self._handle_app_server_notification
             )
-            app_server_meta = self._build_app_server_meta(
-                thread_id=thread_id,
-                turn_id=handle.turn_id,
-                thread_info=thread_info,
-                model=turn_kwargs.get("model"),
-                reasoning_effort=turn_kwargs.get("effort"),
+        except Exception as exc:
+            self.log_line(
+                run_id, f"error: failed to initialize {agent_id} backend: {exc}"
             )
-            self._merge_run_index_entry(run_id, {"app_server": app_server_meta})
-            self._update_run_telemetry(
-                run_id, thread_id=thread_id, turn_id=handle.turn_id
+            return 1
+
+        reuse_session = bool(getattr(self.config, "autorunner_reuse_session", False))
+        session_id: Optional[str] = None
+        if reuse_session and self._backend_orchestrator is not None:
+            session_id = self._backend_orchestrator.get_thread_id(session_key)
+        elif reuse_session:
+            with self._app_server_threads_lock:
+                session_id = self._app_server_threads.get_thread_id(session_key)
+
+        try:
+            session_id = await backend.start_session(
+                target={"workspace": str(self.repo_root)},
+                context={"workspace": str(self.repo_root), "session_id": session_id},
             )
-            turn_timeout = config.app_server.turn_timeout_seconds
-            turn_result, interrupted = await self._wait_for_turn_with_stop(
-                client,
-                handle,
-                run_id,
-                timeout=turn_timeout,
-                external_stop_flag=external_stop_flag,
-                supervisor=supervisor,
+        except Exception as exc:
+            self.log_line(
+                run_id, f"error: {agent_id} backend failed to start session: {exc}"
             )
-            self._last_run_interrupted = interrupted
-            self._log_app_server_output(run_id, turn_result.agent_messages)
-            output_text = "\n\n".join(turn_result.agent_messages).strip()
-            if output_text:
-                output_path = self._write_run_artifact(
-                    run_id, "output.txt", output_text
+            return 1
+
+        if not session_id:
+            self.log_line(
+                run_id, f"error: {agent_id} backend did not return a session id"
+            )
+            return 1
+
+        if reuse_session and self._backend_orchestrator is not None:
+            self._backend_orchestrator.set_thread_id(session_key, session_id)
+        elif reuse_session:
+            with self._app_server_threads_lock:
+                self._app_server_threads.set_thread_id(session_key, session_id)
+
+        self._update_run_telemetry(run_id, thread_id=session_id)
+
+        events: asyncio.Queue[Optional[RunEvent]] = asyncio.Queue()
+
+        async def _produce_events() -> None:
+            try:
+                async for event in backend.run_turn_events(session_id, prompt):
+                    await events.put(event)
+            except Exception as exc:
+                await events.put(Failed(timestamp=now_iso(), error_message=str(exc)))
+            finally:
+                await events.put(None)
+
+        producer_task = asyncio.create_task(_produce_events())
+        stop_task = asyncio.create_task(self._wait_for_stop(external_stop_flag))
+        timeout_seconds = self.config.app_server.turn_timeout_seconds
+        timeout_task: Optional[asyncio.Task] = (
+            asyncio.create_task(asyncio.sleep(timeout_seconds))
+            if timeout_seconds
+            else None
+        )
+
+        assistant_messages: list[str] = []
+        final_message: Optional[str] = None
+        failed_error: Optional[str] = None
+
+        try:
+            while True:
+                get_task = asyncio.create_task(events.get())
+                tasks = {get_task, stop_task}
+                if timeout_task is not None:
+                    tasks.add(timeout_task)
+                done, pending = await asyncio.wait(
+                    tasks, return_when=asyncio.FIRST_COMPLETED
                 )
-                self._merge_run_index_entry(
-                    run_id, {"artifacts": {"output_path": str(output_path)}}
+
+                if get_task in done:
+                    event = get_task.result()
+                    if event is None:
+                        break
+                    if isinstance(event, Started) and event.session_id:
+                        self._update_run_telemetry(
+                            run_id, thread_id=event.session_id, turn_id=event.turn_id
+                        )
+                    elif isinstance(event, OutputDelta):
+                        self._emit_canonical_event(
+                            run_id,
+                            FlowEventType.AGENT_STREAM_DELTA,
+                            {
+                                "delta": event.content,
+                                "delta_type": event.delta_type,
+                            },
+                            timestamp_override=event.timestamp,
+                        )
+                        if event.delta_type in {
+                            "assistant_message",
+                            "assistant_stream",
+                        }:
+                            assistant_messages.append(event.content)
+                        elif event.delta_type == "log_line":
+                            self.log_line(
+                                run_id,
+                                (
+                                    f"stdout: {event.content}"
+                                    if event.content
+                                    else "stdout: "
+                                ),
+                            )
+                    elif isinstance(event, ToolCall):
+                        self._emit_canonical_event(
+                            run_id,
+                            FlowEventType.TOOL_CALL,
+                            {
+                                "tool_name": event.tool_name,
+                                "tool_input": event.tool_input,
+                            },
+                            timestamp_override=event.timestamp,
+                        )
+                    elif isinstance(event, ApprovalRequested):
+                        self._emit_canonical_event(
+                            run_id,
+                            FlowEventType.APPROVAL_REQUESTED,
+                            {
+                                "request_id": event.request_id,
+                                "description": event.description,
+                                "context": event.context,
+                            },
+                            timestamp_override=event.timestamp,
+                        )
+                    elif isinstance(event, TokenUsage):
+                        self._emit_canonical_event(
+                            run_id,
+                            FlowEventType.TOKEN_USAGE,
+                            {"usage": event.usage},
+                            timestamp_override=event.timestamp,
+                        )
+                    elif isinstance(event, RunNotice):
+                        notice_type = FlowEventType.RUN_STATE_CHANGED
+                        if event.kind.endswith("timeout"):
+                            notice_type = FlowEventType.RUN_TIMEOUT
+                        elif "cancel" in event.kind:
+                            notice_type = FlowEventType.RUN_CANCELLED
+                        data: dict[str, Any] = {
+                            "kind": event.kind,
+                            "message": event.message,
+                        }
+                        if event.data:
+                            data["data"] = event.data
+                        self._emit_canonical_event(
+                            run_id,
+                            notice_type,
+                            data,
+                            timestamp_override=event.timestamp,
+                        )
+                    elif isinstance(event, Completed):
+                        if event.final_message:
+                            self._emit_canonical_event(
+                                run_id,
+                                FlowEventType.AGENT_MESSAGE_COMPLETE,
+                                {"final_message": event.final_message},
+                                timestamp_override=event.timestamp,
+                            )
+                        if event.final_message:
+                            final_message = event.final_message
+                    elif isinstance(event, Failed):
+                        self._emit_canonical_event(
+                            run_id,
+                            FlowEventType.AGENT_FAILED,
+                            {"error_message": event.error_message},
+                            timestamp_override=event.timestamp,
+                        )
+                        failed_error = event.error_message
+                    continue
+
+                timed_out = timeout_task is not None and timeout_task in done
+                stopped = stop_task in done
+                if timed_out:
+                    self.log_line(
+                        run_id,
+                        "error: app-server turn timed out; interrupting app-server",
+                    )
+                    self._emit_canonical_event(
+                        run_id,
+                        FlowEventType.RUN_TIMEOUT,
+                        {
+                            "context": "app_server_turn",
+                            "timeout_seconds": timeout_seconds,
+                        },
+                    )
+                if stopped:
+                    self._last_run_interrupted = True
+                    self.log_line(
+                        run_id, "info: stop requested; interrupting app-server"
+                    )
+                try:
+                    await backend.interrupt(session_id)
+                except Exception as exc:
+                    self.log_line(run_id, f"error: app-server interrupt failed: {exc}")
+
+                done_after_interrupt, _pending = await asyncio.wait(
+                    {producer_task}, timeout=AUTORUNNER_INTERRUPT_GRACE_SECONDS
                 )
-            if turn_result.errors:
-                for error in turn_result.errors:
-                    self.log_line(run_id, f"error: {error}")
+                if not done_after_interrupt:
+                    await self._cancel_task_with_notice(
+                        run_id, producer_task, name="producer_task"
+                    )
+                    if stopped:
+                        return 0
+                    return 1
+                if stopped:
+                    return 0
                 return 1
-            return 0
-        except asyncio.TimeoutError:
-            self.log_line(run_id, "error: app-server turn timed out")
-            return 1
-        except CodexAppServerError as exc:
-            self.log_line(run_id, f"error: {exc}")
-            return 1
-        except Exception as exc:  # pragma: no cover - defensive
-            self.log_line(run_id, f"error: app-server failed: {exc}")
-            return 1
+
+            await producer_task
         finally:
-            if not reuse_supervisor:
-                await supervisor.close_all()
+            await self._cancel_task_with_notice(run_id, stop_task, name="stop_task")
+            if timeout_task is not None:
+                await self._cancel_task_with_notice(
+                    run_id, timeout_task, name="timeout_task"
+                )
+
+        if failed_error:
+            self.log_line(run_id, f"error: {failed_error}")
+            return 1
+
+        output_messages = []
+        if final_message:
+            output_messages = [final_message]
+        elif assistant_messages:
+            output_messages = assistant_messages
+
+        if output_messages:
+            handle_agent_output(
+                self._log_app_server_output,
+                self._write_run_artifact,
+                self._merge_run_index_entry,
+                run_id,
+                output_messages,
+            )
+
+        token_total = getattr(backend, "last_token_total", None)
+        if isinstance(token_total, dict):
+            self._update_run_telemetry(run_id, token_total=token_total)
+
+        telemetry = self._snapshot_run_telemetry(run_id)
+        turn_id = None
+        if telemetry is not None:
+            turn_id = telemetry.turn_id
+        if not turn_id:
+            turn_id = getattr(backend, "last_turn_id", None)
+        thread_info = getattr(backend, "last_thread_info", None)
+
+        if session_id and turn_id:
+            app_server_meta = self._build_app_server_meta(
+                thread_id=session_id,
+                turn_id=turn_id,
+                thread_info=thread_info if isinstance(thread_info, dict) else None,
+                model=model,
+                reasoning_effort=reasoning,
+            )
+            if agent_id != "codex":
+                app_server_meta["agent"] = agent_id
+            self._merge_run_index_entry(run_id, {"app_server": app_server_meta})
+
+        return 0
 
     def _log_app_server_output(self, run_id: int, messages: list[str]) -> None:
         if not messages:
@@ -1419,13 +2130,12 @@ class Engine:
         msg = self.config.git_commit_message_template.replace(
             "{run_id}", str(run_id)
         ).replace("#{run_id}", str(run_id))
-        paths = [
-            self.config.doc_path("todo"),
-            self.config.doc_path("progress"),
-            self.config.doc_path("opinions"),
-            self.config.doc_path("spec"),
-            self.config.doc_path("summary"),
-        ]
+        paths = []
+        for key in ("active_context", "decisions", "spec"):
+            try:
+                paths.append(self.config.doc_path(key))
+            except KeyError:
+                pass
         add_paths = [str(p.relative_to(self.repo_root)) for p in paths if p.exists()]
         if not add_paths:
             return
@@ -1455,26 +2165,36 @@ class Engine:
         except GitError as exc:
             self.log_line(run_id, f"git commit failed: {exc}")
 
-    def _build_app_server_supervisor(
-        self, env_builder: Any
-    ) -> WorkspaceAppServerSupervisor:
-        config = self.config.app_server
-        return WorkspaceAppServerSupervisor(
-            config.command,
-            state_root=config.state_root,
-            env_builder=env_builder,
-            logger=self._app_server_logger,
-            notification_handler=self._handle_app_server_notification,
-            max_handles=config.max_handles,
-            idle_ttl_seconds=config.idle_ttl_seconds,
-            request_timeout=config.request_timeout,
-        )
+    def _ensure_app_server_supervisor(self, event_prefix: str) -> Optional[Any]:
+        """
+        Ensure app server supervisor exists by delegating to BackendOrchestrator.
 
-    def _ensure_app_server_supervisor(
-        self, env_builder: Any
-    ) -> WorkspaceAppServerSupervisor:
+        This method is kept for backward compatibility but now delegates to
+        BackendOrchestrator to keep Engine protocol-agnostic.
+        """
         if self._app_server_supervisor is None:
-            self._app_server_supervisor = self._build_app_server_supervisor(env_builder)
+            if (
+                self._backend_orchestrator is None
+                and self._app_server_supervisor_factory is not None
+            ):
+                self._app_server_supervisor = self._app_server_supervisor_factory(
+                    event_prefix, self._handle_app_server_notification
+                )
+            elif self._backend_orchestrator is not None:
+                try:
+                    self._app_server_supervisor = (
+                        self._backend_orchestrator.build_app_server_supervisor(
+                            event_prefix=event_prefix,
+                            notification_handler=self._handle_app_server_notification,
+                        )
+                    )
+                except Exception:
+                    if self._app_server_supervisor_factory is not None:
+                        self._app_server_supervisor = (
+                            self._app_server_supervisor_factory(
+                                event_prefix, self._handle_app_server_notification
+                            )
+                        )
         return self._app_server_supervisor
 
     async def _close_app_server_supervisor(self) -> None:
@@ -1483,45 +2203,49 @@ class Engine:
         supervisor = self._app_server_supervisor
         self._app_server_supervisor = None
         try:
-            await supervisor.close_all()
+            close_all = getattr(supervisor, "close_all", None)
+            if close_all is None:
+                return
+            result = close_all()
+            if inspect.isawaitable(result):
+                await result
         except Exception as exc:
             self._app_server_logger.warning(
                 "app-server supervisor close failed: %s", exc
             )
 
-    def _build_opencode_supervisor(self) -> Optional[OpenCodeSupervisor]:
-        config = self.config.app_server
-        opencode_command = self.config.agent_serve_command("opencode")
-        opencode_binary = None
+    async def _close_agent_backends(self) -> None:
+        if self._backend_factory is None:
+            return
+        close_all = getattr(self._backend_factory, "close_all", None)
+        if close_all is None:
+            return
         try:
-            opencode_binary = self.config.agent_binary("opencode")
-        except ConfigError:
-            opencode_binary = None
-
-        agent_config = self.config.agents.get("opencode")
-        subagent_models = agent_config.subagent_models if agent_config else None
+            result = close_all()
+            if inspect.isawaitable(result):
+                await result
+        except Exception as exc:
+            self._app_server_logger.warning("agent backend close failed: %s", exc)
 
-        supervisor = build_opencode_supervisor(
-            opencode_command=opencode_command,
-            opencode_binary=opencode_binary,
-            workspace_root=self.repo_root,
-            logger=self._app_server_logger,
-            request_timeout=config.request_timeout,
-            max_handles=config.max_handles,
-            idle_ttl_seconds=config.idle_ttl_seconds,
-            base_env=None,
-            subagent_models=subagent_models,
-        )
+    def _build_opencode_supervisor(self) -> Optional[Any]:
+        """
+        Build OpenCode supervisor by delegating to BackendOrchestrator.
 
-        if supervisor is None:
-            self._app_server_logger.info(
-                "OpenCode command unavailable; skipping opencode supervisor."
-            )
+        This method is kept for backward compatibility but now delegates to
+        BackendOrchestrator to keep Engine protocol-agnostic.
+        """
+        if self._backend_orchestrator is None:
             return None
 
-        return supervisor
+        return self._backend_orchestrator.ensure_opencode_supervisor()
+
+    def _ensure_opencode_supervisor(self) -> Optional[Any]:
+        """
+        Ensure OpenCode supervisor exists by delegating to BackendOrchestrator.
 
-    def _ensure_opencode_supervisor(self) -> Optional[OpenCodeSupervisor]:
+        This method is kept for backward compatibility but now delegates to
+        BackendOrchestrator to keep Engine protocol-agnostic.
+        """
         if self._opencode_supervisor is None:
             self._opencode_supervisor = self._build_opencode_supervisor()
         return self._opencode_supervisor
@@ -1536,22 +2260,6 @@ class Engine:
         except Exception as exc:
             self._app_server_logger.warning("opencode supervisor close failed: %s", exc)
 
-    def _get_orchestrator(self, agent_id: str):
-        if agent_id == "opencode":
-            opencode_sup = self._ensure_opencode_supervisor()
-            if opencode_sup is None:
-                return None
-            return create_orchestrator(agent_id, opencode_supervisor=opencode_sup)
-        else:
-            app_server_sup = self._ensure_app_server_supervisor(
-                lambda workspace_root, workspace_id, state_dir: {}
-            )
-            return create_orchestrator(
-                agent_id,
-                codex_supervisor=app_server_sup,
-                codex_events=self._app_server_events,
-            )
-
     async def _wait_for_stop(
         self,
         external_stop_flag: Optional[threading.Event],
@@ -1570,7 +2278,7 @@ class Engine:
         *,
         timeout: Optional[float],
         external_stop_flag: Optional[threading.Event],
-        supervisor: Optional[WorkspaceAppServerSupervisor] = None,
+        supervisor: Optional[Any] = None,
     ) -> tuple[Any, bool]:
         stop_task = asyncio.create_task(self._wait_for_stop(external_stop_flag))
         turn_task = asyncio.create_task(handle.wait(timeout=None))
@@ -1594,6 +2302,11 @@ class Engine:
                 self.log_line(
                     run_id, "error: app-server turn timed out; interrupting app-server"
                 )
+                self._emit_canonical_event(
+                    run_id,
+                    FlowEventType.RUN_TIMEOUT,
+                    {"context": "app_server_turn", "timeout_seconds": timeout},
+                )
             if stopped and not turn_task.done():
                 interrupted = True
                 self.log_line(run_id, "info: stop requested; interrupting app-server")
@@ -1602,7 +2315,7 @@ class Engine:
                     await client.turn_interrupt(
                         handle.turn_id, thread_id=handle.thread_id
                     )
-                except CodexAppServerError as exc:
+                except Exception as exc:
                     self.log_line(run_id, f"error: app-server interrupt failed: {exc}")
                     if interrupted:
                         self.kill_running_process()
@@ -1617,7 +2330,7 @@ class Engine:
                     )
                     if interrupted:
                         self.kill_running_process()
-                        raise CodexAppServerError("App-server interrupt timed out")
+                        raise RuntimeError("App-server interrupt timed out")
                     if supervisor is not None:
                         await supervisor.close_all()
                     raise asyncio.TimeoutError()
@@ -1626,254 +2339,11 @@ class Engine:
                 raise asyncio.TimeoutError()
             return result, interrupted
         finally:
-            stop_task.cancel()
-            with contextlib.suppress(asyncio.CancelledError):
-                await stop_task
-            if timeout_task is not None:
-                timeout_task.cancel()
-                with contextlib.suppress(asyncio.CancelledError):
-                    await timeout_task
-
-    async def _abort_opencode(self, client: Any, session_id: str, run_id: int) -> None:
-        try:
-            await client.abort(session_id)
-        except Exception as exc:
-            self.log_line(run_id, f"error: opencode abort failed: {exc}")
-
-    async def _run_opencode_app_server_async(
-        self,
-        prompt: str,
-        run_id: int,
-        *,
-        model: Optional[str],
-        reasoning: Optional[str],
-        external_stop_flag: Optional[threading.Event] = None,
-    ) -> int:
-        supervisor = self._ensure_opencode_supervisor()
-        if supervisor is None:
-            self.log_line(
-                run_id, "error: opencode backend is not configured in this repo"
-            )
-            return 1
-        try:
-            client = await supervisor.get_client(self.repo_root)
-        except OpenCodeSupervisorError as exc:
-            self.log_line(run_id, f"error: opencode backend unavailable: {exc}")
-            return 1
-
-        with self._app_server_threads_lock:
-            key = "autorunner.opencode"
-            thread_id = self._app_server_threads.get_thread_id(key)
-            if thread_id:
-                try:
-                    await client.get_session(thread_id)
-                except Exception as exc:
-                    self._app_server_logger.debug(
-                        "Failed to get existing opencode session '%s': %s",
-                        thread_id,
-                        exc,
-                    )
-                    self._app_server_threads.reset_thread(key)
-                    thread_id = None
-            if not thread_id:
-                session = await client.create_session(directory=str(self.repo_root))
-                thread_id = extract_session_id(session, allow_fallback_id=True)
-                if not isinstance(thread_id, str) or not thread_id:
-                    self.log_line(run_id, "error: opencode did not return a session id")
-                    return 1
-                self._app_server_threads.set_thread_id(key, thread_id)
-
-        model_payload = split_model_id(model)
-        missing_env = await opencode_missing_env(
-            client, str(self.repo_root), model_payload
-        )
-        if missing_env:
-            provider_id = model_payload.get("providerID") if model_payload else None
-            self.log_line(
-                run_id,
-                "error: opencode provider "
-                f"{provider_id or 'selected'} requires env vars: "
-                f"{', '.join(missing_env)}",
-            )
-            return 1
-        opencode_turn_started = False
-        await supervisor.mark_turn_started(self.repo_root)
-        opencode_turn_started = True
-        turn_id = build_turn_id(thread_id)
-        self._update_run_telemetry(run_id, thread_id=thread_id, turn_id=turn_id)
-        app_server_meta = self._build_app_server_meta(
-            thread_id=thread_id,
-            turn_id=turn_id,
-            thread_info=None,
-            model=model,
-            reasoning_effort=reasoning,
-        )
-        app_server_meta["agent"] = "opencode"
-        self._merge_run_index_entry(run_id, {"app_server": app_server_meta})
-
-        active = ActiveOpencodeRun(
-            session_id=thread_id,
-            turn_id=turn_id,
-            client=client,
-            interrupted=False,
-            interrupt_event=asyncio.Event(),
-        )
-        with state_lock(self.state_path):
-            state = load_state(self.state_path)
-        permission_policy = map_approval_policy_to_permission(
-            state.autorunner_approval_policy, default="allow"
-        )
-
-        async def _opencode_part_handler(
-            part_type: str, part: dict[str, Any], delta_text: Optional[str]
-        ) -> None:
-            if part_type == "usage" and isinstance(part, dict):
-                for line in self._opencode_event_formatter.format_usage(part):
-                    self.log_line(run_id, f"stdout: {line}" if line else "stdout: ")
-            else:
-                for line in self._opencode_event_formatter.format_part(
-                    part_type, part, delta_text
-                ):
-                    self.log_line(run_id, f"stdout: {line}" if line else "stdout: ")
-
-        ready_event = asyncio.Event()
-        output_task = asyncio.create_task(
-            collect_opencode_output(
-                client,
-                session_id=thread_id,
-                workspace_path=str(self.repo_root),
-                permission_policy=permission_policy,
-                question_policy="auto_first_option",
-                should_stop=active.interrupt_event.is_set,
-                part_handler=_opencode_part_handler,
-                ready_event=ready_event,
-            )
-        )
-        with contextlib.suppress(asyncio.TimeoutError):
-            await asyncio.wait_for(ready_event.wait(), timeout=2.0)
-        prompt_task = asyncio.create_task(
-            client.prompt_async(
-                thread_id,
-                message=prompt,
-                model=model_payload,
-                variant=reasoning,
-            )
-        )
-        stop_task = asyncio.create_task(self._wait_for_stop(external_stop_flag))
-        timeout_task = None
-        turn_timeout = self.config.app_server.turn_timeout_seconds
-        if turn_timeout:
-            timeout_task = asyncio.create_task(asyncio.sleep(turn_timeout))
-        timed_out = False
-        try:
-            try:
-                prompt_response = await prompt_task
-                prompt_info = (
-                    prompt_response.get("info")
-                    if isinstance(prompt_response, dict)
-                    else {}
-                )
-                tokens = (
-                    prompt_info.get("tokens") if isinstance(prompt_info, dict) else {}
-                )
-                if isinstance(tokens, dict):
-                    input_tokens = int(tokens.get("input", 0) or 0)
-                    cached_read = (
-                        int(tokens.get("cache", {}).get("read", 0) or 0)
-                        if isinstance(tokens.get("cache"), dict)
-                        else 0
-                    )
-                    output_tokens = int(tokens.get("output", 0) or 0)
-                    reasoning_tokens = int(tokens.get("reasoning", 0) or 0)
-                    total_tokens = (
-                        input_tokens + cached_read + output_tokens + reasoning_tokens
-                    )
-                    token_total = {
-                        "total": total_tokens,
-                        "input_tokens": input_tokens,
-                        "prompt_tokens": input_tokens,
-                        "cached_input_tokens": cached_read,
-                        "output_tokens": output_tokens,
-                        "completion_tokens": output_tokens,
-                        "reasoning_tokens": reasoning_tokens,
-                        "reasoning_output_tokens": reasoning_tokens,
-                    }
-                    self._update_run_telemetry(run_id, token_total=token_total)
-            except Exception as exc:
-                active.interrupt_event.set()
-                output_task.cancel()
-                with contextlib.suppress(asyncio.CancelledError):
-                    await output_task
-                self.log_line(run_id, f"error: opencode prompt failed: {exc}")
-                return 1
-            tasks = {output_task, stop_task}
-            if timeout_task is not None:
-                tasks.add(timeout_task)
-            done, _pending = await asyncio.wait(
-                tasks, return_when=asyncio.FIRST_COMPLETED
-            )
-            timed_out = timeout_task is not None and timeout_task in done
-            stopped = stop_task in done
-            if timed_out:
-                self.log_line(
-                    run_id, "error: opencode turn timed out; aborting session"
-                )
-                active.interrupt_event.set()
-            if stopped:
-                active.interrupted = True
-                active.interrupt_event.set()
-                self.log_line(run_id, "info: stop requested; aborting opencode")
-            if timed_out or stopped:
-                await self._abort_opencode(client, thread_id, run_id)
-                done, _pending = await asyncio.wait(
-                    {output_task}, timeout=AUTORUNNER_INTERRUPT_GRACE_SECONDS
-                )
-                if not done:
-                    output_task.cancel()
-                    with contextlib.suppress(asyncio.CancelledError):
-                        await output_task
-                    if timed_out:
-                        return 1
-                    self._last_run_interrupted = active.interrupted
-                    return 0
-            output_result = await output_task
-            if not output_result.text and not output_result.error:
-                fallback = parse_message_response(prompt_response)
-                if fallback.text:
-                    output_result = OpenCodeTurnOutput(
-                        text=fallback.text, error=fallback.error
-                    )
-        finally:
-            stop_task.cancel()
-            with contextlib.suppress(asyncio.CancelledError):
-                await stop_task
+            await self._cancel_task_with_notice(run_id, stop_task, name="stop_task")
             if timeout_task is not None:
-                timeout_task.cancel()
-                with contextlib.suppress(asyncio.CancelledError):
-                    await timeout_task
-            if opencode_turn_started:
-                await supervisor.mark_turn_finished(self.repo_root)
-
-        output = output_result.text
-        if output:
-            self._log_app_server_output(run_id, [output])
-            output_text = output.strip()
-            if output_text:
-                output_path = self._write_run_artifact(
-                    run_id, "output.txt", output_text
+                await self._cancel_task_with_notice(
+                    run_id, timeout_task, name="timeout_task"
                 )
-                self._merge_run_index_entry(
-                    run_id, {"artifacts": {"output_path": str(output_path)}}
-                )
-        if output_result.error:
-            self.log_line(
-                run_id, f"error: opencode session error: {output_result.error}"
-            )
-            return 1
-        self._last_run_interrupted = active.interrupted
-        if timed_out:
-            return 1
-        return 0
 
     async def _run_loop_async(
         self,
@@ -1894,8 +2364,10 @@ class Engine:
             )
         )
         no_progress_count = 0
-        last_outstanding_count = len(self.docs.todos()[0])
-        last_done_count = len(self.docs.todos()[1])
+        ticket_dir = self.repo_root / ".codex-autorunner" / "tickets"
+        initial_tickets = list_ticket_paths(ticket_dir)
+        last_done_count = sum(1 for path in initial_tickets if ticket_is_done(path))
+        last_outstanding_count = len(initial_tickets) - last_done_count
         exit_reason: Optional[str] = None
 
         try:
@@ -1949,9 +2421,11 @@ class Engine:
                     break
 
                 # Check for no progress across runs
-                current_outstanding, current_done = self.docs.todos()
-                current_outstanding_count = len(current_outstanding)
-                current_done_count = len(current_done)
+                current_tickets = list_ticket_paths(ticket_dir)
+                current_done_count = sum(
+                    1 for path in current_tickets if ticket_is_done(path)
+                )
+                current_outstanding_count = len(current_tickets) - current_done_count
 
                 # Check if there was any meaningful progress
                 has_progress = (
@@ -1959,25 +2433,55 @@ class Engine:
                     or current_done_count != last_done_count
                 )
 
-                # Check if there was any meaningful output (diff, files changed, etc.)
+                # Check if there was any meaningful output (diff, plan, etc.)
                 has_output = False
-                try:
-                    output_path = (
-                        self.repo_root
-                        / ".codex-autorunner"
-                        / "runs"
-                        / f"run-{run_id}"
-                        / "output.txt"
-                    )
-                    if output_path.exists():
-                        output_content = output_path.read_text(encoding="utf-8").strip()
-                        # Consider it output if there's meaningful text (not just empty or whitespace)
-                        has_output = len(output_content) > 100
-                except (OSError, IOError):
-                    pass
+                run_entry = self._run_index_store.get_entry(run_id)
+                if run_entry:
+                    artifacts = run_entry.get("artifacts", {})
+                    if isinstance(artifacts, dict):
+                        diff_path = artifacts.get("diff_path")
+                        if diff_path:
+                            try:
+                                diff_content = (
+                                    Path(diff_path).read_text(encoding="utf-8").strip()
+                                )
+                                has_output = len(diff_content) > 0
+                            except (OSError, IOError):
+                                pass
+                        if not has_output:
+                            plan_path = artifacts.get("plan_path")
+                            if plan_path:
+                                try:
+                                    plan_content = (
+                                        Path(plan_path)
+                                        .read_text(encoding="utf-8")
+                                        .strip()
+                                    )
+                                    has_output = len(plan_content) > 0
+                                except (OSError, IOError):
+                                    pass
 
                 if not has_progress and not has_output:
                     no_progress_count += 1
+
+                    evidence = {
+                        "outstanding_count": current_outstanding_count,
+                        "done_count": current_done_count,
+                        "has_diff": bool(
+                            run_entry
+                            and isinstance(run_entry.get("artifacts"), dict)
+                            and run_entry["artifacts"].get("diff_path")
+                        ),
+                        "has_plan": bool(
+                            run_entry
+                            and isinstance(run_entry.get("artifacts"), dict)
+                            and run_entry["artifacts"].get("plan_path")
+                        ),
+                        "run_id": run_id,
+                    }
+                    self._emit_event(
+                        run_id, "run.no_progress", count=no_progress_count, **evidence
+                    )
                     self.log_line(
                         run_id,
                         f"info: no progress detected ({no_progress_count}/{self.config.runner_no_progress_threshold} runs without progress)",
@@ -2030,12 +2534,16 @@ class Engine:
                 for line in tb.splitlines():
                     self.log_line(run_id, f"traceback: {line}")
             except (OSError, IOError) as exc:
-                self._app_server_logger.error("Failed to log run_loop crash: %s", exc)
+                self._app_server_logger.error(
+                    "Failed to log run_loop crash for run %s: %s", run_id, exc
+                )
             try:
                 self._update_state("error", run_id, 1, finished=True)
             except (OSError, IOError) as exc:
                 self._app_server_logger.error(
-                    "Failed to update state after run_loop crash: %s", exc
+                    "Failed to update state after run_loop crash for run %s: %s",
+                    run_id,
+                    exc,
                 )
         finally:
             try:
@@ -2044,9 +2552,12 @@ class Engine:
                     last_exit_code=last_exit_code,
                 )
             except Exception as exc:
-                self._app_server_logger.warning("End-of-run review failed: %s", exc)
+                self._app_server_logger.warning(
+                    "End-of-run review failed for run %s: %s", run_id, exc
+                )
             await self._close_app_server_supervisor()
             await self._close_opencode_supervisor()
+            await self._close_agent_backends()
         # IMPORTANT: lock ownership is managed by the caller (CLI/Hub/Server runner).
         # Engine.run_loop must never unconditionally mutate the lock file.
 
@@ -2116,8 +2627,8 @@ class Engine:
         }
         payload = {k: v for k, v in payload.items() if v is not None}
 
-        opencode_supervisor: Optional[OpenCodeSupervisor] = None
-        app_server_supervisor: Optional[WorkspaceAppServerSupervisor] = None
+        opencode_supervisor: Optional[Any] = None
+        app_server_supervisor: Optional[Any] = None
 
         if agent == "codex":
             if not self.config.app_server.command:
@@ -2125,20 +2636,12 @@ class Engine:
                     "Skipping end-of-run review: codex backend not configured"
                 )
                 return
-
-            def _env_builder(
-                workspace_root: Path, _workspace_id: str, state_dir: Path
-            ) -> dict[str, str]:
-                state_dir.mkdir(parents=True, exist_ok=True)
-                return build_app_server_env(
-                    self.config.app_server.command,
-                    workspace_root,
-                    state_dir,
-                    logger=self._app_server_logger,
-                    event_prefix="review",
+            app_server_supervisor = self._ensure_app_server_supervisor("review")
+            if app_server_supervisor is None:
+                self._app_server_logger.info(
+                    "Skipping end-of-run review: codex supervisor factory unavailable"
                 )
-
-            app_server_supervisor = self._ensure_app_server_supervisor(_env_builder)
+                return
         else:
             opencode_supervisor = self._ensure_opencode_supervisor()
             if opencode_supervisor is None:
@@ -2147,7 +2650,7 @@ class Engine:
                 )
                 return
 
-        from .review import ReviewService
+        from ..flows.review import ReviewService
 
         review_service = ReviewService(
             self,
@@ -2208,8 +2711,12 @@ class Engine:
         started: bool = False,
         finished: bool = False,
     ) -> None:
+        prev_status: Optional[str] = None
+        last_run_started_at: Optional[str] = None
+        last_run_finished_at: Optional[str] = None
         with state_lock(self.state_path):
             current = load_state(self.state_path)
+            prev_status = current.status
             last_run_started_at = current.last_run_started_at
             last_run_finished_at = current.last_run_finished_at
             runner_pid = current.runner_pid
@@ -2237,6 +2744,18 @@ class Engine:
                 repo_to_session=current.repo_to_session,
             )
             save_state(self.state_path, new_state)
+        if run_id > 0 and prev_status != status:
+            payload: dict[str, Any] = {
+                "from_status": prev_status,
+                "to_status": status,
+            }
+            if exit_code is not None:
+                payload["exit_code"] = exit_code
+            if started and last_run_started_at:
+                payload["started_at"] = last_run_started_at
+            if finished and last_run_finished_at:
+                payload["finished_at"] = last_run_finished_at
+            self._emit_event(run_id, "run.state_changed", **payload)
 
 
 def clear_stale_lock(lock_path: Path) -> bool:
@@ -2385,253 +2904,399 @@ def _manifest_has_worktrees(manifest_path: Path) -> bool:
     return False
 
 
-def doctor(start_path: Path) -> DoctorReport:
-    hub_config = load_hub_config(start_path)
-    repo_config: Optional[RepoConfig] = None
-    try:
-        repo_root = find_repo_root(start_path)
-        repo_config = derive_repo_config(hub_config, repo_root)
-    except RepoNotFoundError:
-        repo_config = None
+def _append_repo_check(
+    checks: list[DoctorCheck],
+    prefix: str,
+    check_id: str,
+    status: str,
+    message: str,
+    fix: Optional[str] = None,
+) -> None:
+    full_id = f"{prefix}.{check_id}" if prefix else check_id
+    _append_check(checks, full_id, status, message, fix)
+
+
+def _load_isolated_repo_config(repo_root: Path) -> RepoConfig:
+    config_path = repo_root / CONFIG_FILENAME
+    raw_config = _load_yaml_dict(config_path) if config_path.exists() else {}
+    raw = _merge_defaults(DEFAULT_REPO_CONFIG, raw_config or {})
+    raw["mode"] = "repo"
+    raw["version"] = raw.get("version") or CONFIG_VERSION
+    _validate_repo_config(raw, root=repo_root)
+    return _build_repo_config(config_path, raw)
+
+
+def _repo_checks(
+    repo_config: RepoConfig,
+    global_state_root: Path,
+    prefix: str = "",
+) -> list[DoctorCheck]:
     checks: list[DoctorCheck] = []
-    config = repo_config or hub_config
-    root = config.root
-
-    if repo_config is not None:
-        missing = []
-        for key in ("todo", "progress", "opinions"):
-            path = repo_config.doc_path(key)
-            if not path.exists():
-                missing.append(path)
-        if missing:
-            names = ", ".join(str(p) for p in missing)
-            _append_check(
+    repo_state_root = resolve_repo_state_root(repo_config.root)
+    _append_repo_check(
+        checks,
+        prefix,
+        "state.roots",
+        "ok",
+        f"Repo state root: {repo_state_root}; Global state root: {global_state_root}",
+    )
+
+    missing = []
+    configured_docs = repo_config.docs or {}
+    for key in configured_docs:
+        path = repo_config.doc_path(key)
+        if not path.exists():
+            missing.append(path)
+    if missing:
+        names = ", ".join(str(p) for p in missing)
+        _append_repo_check(
+            checks,
+            prefix,
+            "docs.required",
+            "warning",
+            f"Configured doc files are missing: {names}",
+            "Create the missing files (workspace docs are optional but recommended).",
+        )
+    else:
+        _append_repo_check(
+            checks,
+            prefix,
+            "docs.required",
+            "ok",
+            "Configured doc files are present.",
+        )
+
+    if ensure_executable(repo_config.codex_binary):
+        _append_repo_check(
+            checks,
+            prefix,
+            "codex.binary",
+            "ok",
+            f"Codex binary resolved: {repo_config.codex_binary}",
+        )
+    else:
+        _append_repo_check(
+            checks,
+            prefix,
+            "codex.binary",
+            "error",
+            f"Codex binary not found in PATH: {repo_config.codex_binary}",
+            "Install Codex or set codex.binary to a full path.",
+        )
+
+    voice_enabled = bool(repo_config.voice.get("enabled", True))
+    if voice_enabled:
+        missing_voice = missing_optional_dependencies(
+            (
+                ("httpx", "httpx"),
+                (("multipart", "python_multipart"), "python-multipart"),
+            )
+        )
+        if missing_voice:
+            deps_list = ", ".join(missing_voice)
+            _append_repo_check(
                 checks,
-                "docs.required",
+                prefix,
+                "voice.dependencies",
                 "error",
-                f"Missing doc files: {names}",
-                "Run `car init` or create the missing files.",
+                f"Voice is enabled but missing optional deps: {deps_list}",
+                "Install with `pip install codex-autorunner[voice]`.",
             )
         else:
-            _append_check(
-                checks,
-                "docs.required",
-                "ok",
-                "Required doc files are present.",
-            )
-
-        if ensure_executable(repo_config.codex_binary):
-            _append_check(
+            _append_repo_check(
                 checks,
-                "codex.binary",
+                prefix,
+                "voice.dependencies",
                 "ok",
-                f"Codex binary resolved: {repo_config.codex_binary}",
-            )
-        else:
-            _append_check(
-                checks,
-                "codex.binary",
-                "error",
-                f"Codex binary not found in PATH: {repo_config.codex_binary}",
-                "Install Codex or set codex.binary to a full path.",
+                "Voice dependencies are installed.",
             )
 
-        voice_enabled = bool(repo_config.voice.get("enabled", True))
-        if voice_enabled:
-            missing_voice = missing_optional_dependencies(
-                (
-                    ("httpx", "httpx"),
-                    (("multipart", "python_multipart"), "python-multipart"),
-                )
-            )
-            if missing_voice:
-                deps_list = ", ".join(missing_voice)
-                _append_check(
-                    checks,
-                    "voice.dependencies",
-                    "error",
-                    f"Voice is enabled but missing optional deps: {deps_list}",
-                    "Install with `pip install codex-autorunner[voice]`.",
-                )
-            else:
-                _append_check(
-                    checks,
-                    "voice.dependencies",
-                    "ok",
-                    "Voice dependencies are installed.",
-                )
-
     env_candidates = [
-        root / ".env",
-        root / ".codex-autorunner" / ".env",
+        repo_config.root / ".env",
+        repo_config.root / ".codex-autorunner" / ".env",
     ]
     env_found = [str(path) for path in env_candidates if path.exists()]
     if env_found:
-        _append_check(
+        _append_repo_check(
             checks,
+            prefix,
             "dotenv.locations",
             "ok",
             f"Found .env files: {', '.join(env_found)}",
         )
     else:
-        _append_check(
+        _append_repo_check(
             checks,
+            prefix,
             "dotenv.locations",
             "warning",
             "No .env files found in repo root or .codex-autorunner/.env.",
             "Create one of these files if you rely on env vars.",
         )
 
-    host = str(config.server_host or "")
+    host = str(repo_config.server_host or "")
     if not _is_loopback_host(host):
-        if not config.server_auth_token_env:
-            _append_check(
+        if not repo_config.server_auth_token_env:
+            _append_repo_check(
                 checks,
+                prefix,
                 "server.auth",
                 "error",
                 f"Non-loopback host {host} requires server.auth_token_env.",
                 "Set server.auth_token_env or bind to 127.0.0.1.",
             )
         else:
-            token_val = os.environ.get(config.server_auth_token_env)
+            token_val = os.environ.get(repo_config.server_auth_token_env)
             if not token_val:
-                _append_check(
+                _append_repo_check(
                     checks,
+                    prefix,
                     "server.auth",
                     "warning",
-                    f"Auth token env var {config.server_auth_token_env} is not set.",
+                    f"Auth token env var {repo_config.server_auth_token_env} is not set.",
                     "Export the env var or add it to .env.",
                 )
             else:
-                _append_check(
+                _append_repo_check(
                     checks,
+                    prefix,
                     "server.auth",
                     "ok",
                     "Server auth token env var is set for non-loopback host.",
                 )
 
-    static_dir, static_context = resolve_static_dir()
+    return checks
+
+
+def _iter_hub_repos(hub_config) -> list[tuple[str, Path]]:
+    repos: list[tuple[str, Path]] = []
+    if hub_config.manifest_path.exists():
+        try:
+            raw = yaml.safe_load(hub_config.manifest_path.read_text(encoding="utf-8"))
+        except (OSError, yaml.YAMLError):
+            raw = None
+        if isinstance(raw, dict):
+            entries = raw.get("repos")
+            if isinstance(entries, list):
+                for entry in entries:
+                    if not isinstance(entry, dict):
+                        continue
+                    if not entry.get("enabled", True):
+                        continue
+                    path_val = entry.get("path")
+                    if not isinstance(path_val, str):
+                        continue
+                    repo_id = str(entry.get("id") or path_val)
+                    repos.append((repo_id, (hub_config.root / path_val).resolve()))
+    if not repos and hub_config.repos_root.exists():
+        for child in hub_config.repos_root.iterdir():
+            if child.is_dir():
+                repos.append((child.name, child.resolve()))
+    return repos
+
+
+def doctor(start_path: Path) -> DoctorReport:
+    checks: list[DoctorCheck] = []
+    hub_config = None
     try:
-        missing_assets = missing_static_assets(static_dir)
-        if missing_assets:
-            _append_check(
-                checks,
-                "static.assets",
-                "error",
-                f"Static UI assets missing in {static_dir}: {', '.join(missing_assets)}",
-                "Reinstall the package or rebuild the UI assets.",
-            )
+        hub_config = load_hub_config(start_path)
+    except ConfigError:
+        hub_config = None
+
+    repo_root: Optional[Path] = None
+    try:
+        repo_root = find_repo_root(start_path)
+    except RepoNotFoundError:
+        repo_root = None
+
+    repo_config: Optional[RepoConfig] = None
+    if hub_config is not None and repo_root is not None:
+        try:
+            repo_config = derive_repo_config(hub_config, repo_root)
+        except ConfigError:
+            repo_config = None
+    elif hub_config is None and repo_root is not None:
+        try:
+            repo_config = load_repo_config(start_path)
+        except ConfigError:
+            repo_config = _load_isolated_repo_config(repo_root)
+
+    if hub_config is not None:
+        global_state_root = resolve_global_state_root(config=hub_config)
+        _append_check(
+            checks,
+            "state.roots",
+            "ok",
+            f"Hub root: {hub_config.root}; Global state root: {global_state_root}",
+        )
+    elif repo_config is not None:
+        global_state_root = resolve_global_state_root(config=repo_config)
+        _append_check(
+            checks,
+            "state.roots",
+            "ok",
+            f"Repo state root: {resolve_repo_state_root(repo_config.root)}; Global state root: {global_state_root}",
+        )
+    else:
+        raise ConfigError("No hub or repo configuration found for doctor check.")
+
+    if hub_config is not None:
+        if hub_config.manifest_path.exists():
+            version = _parse_manifest_version(hub_config.manifest_path)
+            if version is None:
+                _append_check(
+                    checks,
+                    "hub.manifest.version",
+                    "error",
+                    f"Failed to read manifest version from {hub_config.manifest_path}.",
+                    "Fix the manifest YAML or regenerate it with `car hub scan`.",
+                )
+            elif version != MANIFEST_VERSION:
+                _append_check(
+                    checks,
+                    "hub.manifest.version",
+                    "error",
+                    f"Hub manifest version {version} unsupported (expected {MANIFEST_VERSION}).",
+                    "Regenerate the manifest (delete it and run `car hub scan`).",
+                )
+            else:
+                _append_check(
+                    checks,
+                    "hub.manifest.version",
+                    "ok",
+                    f"Hub manifest version {version} is supported.",
+                )
         else:
             _append_check(
                 checks,
-                "static.assets",
-                "ok",
-                f"Static UI assets present in {static_dir}",
+                "hub.manifest.exists",
+                "warning",
+                f"Hub manifest missing at {hub_config.manifest_path}.",
+                "Run `car hub scan` or `car hub create` to generate it.",
             )
-    finally:
-        if static_context is not None:
-            static_context.close()
 
-    if hub_config.manifest_path.exists():
-        version = _parse_manifest_version(hub_config.manifest_path)
-        if version is None:
+        if not hub_config.repos_root.exists():
             _append_check(
                 checks,
-                "hub.manifest.version",
+                "hub.repos_root",
                 "error",
-                f"Failed to read manifest version from {hub_config.manifest_path}.",
-                "Fix the manifest YAML or regenerate it with `car hub scan`.",
+                f"Hub repos_root does not exist: {hub_config.repos_root}",
+                "Create the directory or update hub.repos_root in config.",
             )
-        elif version != MANIFEST_VERSION:
+        elif not hub_config.repos_root.is_dir():
             _append_check(
                 checks,
-                "hub.manifest.version",
+                "hub.repos_root",
                 "error",
-                f"Hub manifest version {version} unsupported (expected {MANIFEST_VERSION}).",
-                "Regenerate the manifest (delete it and run `car hub scan`).",
+                f"Hub repos_root is not a directory: {hub_config.repos_root}",
+                "Point hub.repos_root at a directory.",
             )
         else:
             _append_check(
                 checks,
-                "hub.manifest.version",
+                "hub.repos_root",
                 "ok",
-                f"Hub manifest version {version} is supported.",
+                f"Hub repos_root exists: {hub_config.repos_root}",
             )
-    else:
-        _append_check(
-            checks,
-            "hub.manifest.exists",
-            "warning",
-            f"Hub manifest missing at {hub_config.manifest_path}.",
-            "Run `car hub scan` or `car hub create` to generate it.",
-        )
 
-    if not hub_config.repos_root.exists():
-        _append_check(
-            checks,
-            "hub.repos_root",
-            "error",
-            f"Hub repos_root does not exist: {hub_config.repos_root}",
-            "Create the directory or update hub.repos_root in config.",
-        )
-    elif not hub_config.repos_root.is_dir():
-        _append_check(
-            checks,
-            "hub.repos_root",
-            "error",
-            f"Hub repos_root is not a directory: {hub_config.repos_root}",
-            "Point hub.repos_root at a directory.",
-        )
-    else:
-        _append_check(
-            checks,
-            "hub.repos_root",
-            "ok",
-            f"Hub repos_root exists: {hub_config.repos_root}",
+        manifest_has_worktrees = (
+            hub_config.manifest_path.exists()
+            and _manifest_has_worktrees(hub_config.manifest_path)
         )
+        worktrees_enabled = hub_config.worktrees_root.exists() or manifest_has_worktrees
+        if worktrees_enabled:
+            if ensure_executable("git"):
+                _append_check(
+                    checks,
+                    "hub.git",
+                    "ok",
+                    "git is available for hub worktrees.",
+                )
+            else:
+                _append_check(
+                    checks,
+                    "hub.git",
+                    "error",
+                    "git is not available but hub worktrees are enabled.",
+                    "Install git or disable worktrees.",
+                )
 
-    manifest_has_worktrees = (
-        hub_config.manifest_path.exists()
-        and _manifest_has_worktrees(hub_config.manifest_path)
-    )
-    worktrees_enabled = hub_config.worktrees_root.exists() or manifest_has_worktrees
-    if worktrees_enabled:
-        if ensure_executable("git"):
+        env_candidates = [
+            hub_config.root / ".env",
+            hub_config.root / ".codex-autorunner" / ".env",
+        ]
+        env_found = [str(path) for path in env_candidates if path.exists()]
+        if env_found:
             _append_check(
                 checks,
-                "hub.git",
+                "dotenv.locations",
                 "ok",
-                "git is available for hub worktrees.",
+                f"Found .env files: {', '.join(env_found)}",
             )
         else:
             _append_check(
                 checks,
-                "hub.git",
-                "error",
-                "git is not available but hub worktrees are enabled.",
-                "Install git or disable worktrees.",
+                "dotenv.locations",
+                "warning",
+                "No .env files found in repo root or .codex-autorunner/.env.",
+                "Create one of these files if you rely on env vars.",
             )
 
-    telegram_cfg = None
-    if isinstance(config.raw, dict):
-        telegram_cfg = config.raw.get("telegram_bot")
-    if isinstance(telegram_cfg, dict) and telegram_cfg.get("enabled") is True:
-        missing_telegram = missing_optional_dependencies((("httpx", "httpx"),))
-        if missing_telegram:
-            deps_list = ", ".join(missing_telegram)
-            _append_check(
-                checks,
-                "telegram.dependencies",
-                "error",
-                f"Telegram is enabled but missing optional deps: {deps_list}",
-                "Install with `pip install codex-autorunner[telegram]`.",
-            )
-        else:
-            _append_check(
-                checks,
-                "telegram.dependencies",
-                "ok",
-                "Telegram dependencies are installed.",
-            )
+        host = str(hub_config.server_host or "")
+        if not _is_loopback_host(host):
+            if not hub_config.server_auth_token_env:
+                _append_check(
+                    checks,
+                    "server.auth",
+                    "error",
+                    f"Non-loopback host {host} requires server.auth_token_env.",
+                    "Set server.auth_token_env or bind to 127.0.0.1.",
+                )
+            else:
+                token_val = os.environ.get(hub_config.server_auth_token_env)
+                if not token_val:
+                    _append_check(
+                        checks,
+                        "server.auth",
+                        "warning",
+                        f"Auth token env var {hub_config.server_auth_token_env} is not set.",
+                        "Export the env var or add it to .env.",
+                    )
+                else:
+                    _append_check(
+                        checks,
+                        "server.auth",
+                        "ok",
+                        "Server auth token env var is set for non-loopback host.",
+                    )
+
+        for repo_id, repo_path in _iter_hub_repos(hub_config):
+            prefix = f"repo[{repo_id}]"
+            if not repo_path.exists():
+                _append_repo_check(
+                    checks,
+                    prefix,
+                    "state.roots",
+                    "error",
+                    f"Repo path not found: {repo_path}",
+                    "Clone or initialize the repo, or update the hub manifest.",
+                )
+                continue
+            try:
+                repo_cfg = derive_repo_config(hub_config, repo_path)
+            except ConfigError as exc:
+                _append_repo_check(
+                    checks,
+                    prefix,
+                    "config",
+                    "error",
+                    f"Failed to derive repo config: {exc}",
+                )
+                continue
+            checks.extend(_repo_checks(repo_cfg, global_state_root, prefix=prefix))
+
+    else:
+        assert repo_config is not None
+        checks.extend(_repo_checks(repo_config, global_state_root))
 
     return DoctorReport(checks=checks)