ouroboros-ai 0.27.3.dev1__tar.gz → 0.27.3.dev3__tar.gz

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/PKG-INFO

@@ -1,32 +1,40 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.27.3.dev1
+Version: 0.27.3.dev3
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE
 Requires-Python: >=3.12
-Requires-Dist: aiosqlite>=0.20.0
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: pyyaml>=6.0.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: sqlalchemy[asyncio]>=2.0.0
-Requires-Dist: structlog>=24.0.0
-Requires-Dist: typer>=0.12.0
+Requires-Dist: aiosqlite<1.0.0,>=0.20.0
+Requires-Dist: prompt-toolkit<4.0.0,>=3.0.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: pyyaml<7.0.0,>=6.0.0
+Requires-Dist: rich<15.0.0,>=13.0.0
+Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.0
+Requires-Dist: structlog<26.0.0,>=24.0.0
+Requires-Dist: typer<1.0.0,>=0.12.0
 Provides-Extra: all
-Requires-Dist: anthropic>=0.52.0; extra == 'all'
-Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'all'
+Requires-Dist: anthropic<1.0.0,>=0.52.0; extra == 'all'
+Requires-Dist: claude-agent-sdk<1.0.0,>=0.1.0; extra == 'all'
 Requires-Dist: litellm<=1.82.6,>=1.80.0; extra == 'all'
-Requires-Dist: mcp>=1.26.0; extra == 'all'
-Requires-Dist: textual>=1.0.0; extra == 'all'
+Requires-Dist: mcp<2.0.0,>=1.26.0; extra == 'all'
+Requires-Dist: pandas<3.0.0,>=2.2.0; extra == 'all'
+Requires-Dist: plotly<7.0.0,>=5.24.0; extra == 'all'
+Requires-Dist: streamlit<2.0.0,>=1.40.0; extra == 'all'
+Requires-Dist: textual<9.0.0,>=1.0.0; extra == 'all'
 Provides-Extra: claude
-Requires-Dist: anthropic>=0.52.0; extra == 'claude'
-Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'claude'
+Requires-Dist: anthropic<1.0.0,>=0.52.0; extra == 'claude'
+Requires-Dist: claude-agent-sdk<1.0.0,>=0.1.0; extra == 'claude'
+Provides-Extra: dashboard
+Requires-Dist: pandas<3.0.0,>=2.2.0; extra == 'dashboard'
+Requires-Dist: plotly<7.0.0,>=5.24.0; extra == 'dashboard'
+Requires-Dist: streamlit<2.0.0,>=1.40.0; extra == 'dashboard'
 Provides-Extra: litellm
 Requires-Dist: litellm<=1.82.6,>=1.80.0; extra == 'litellm'
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.26.0; extra == 'mcp'
+Requires-Dist: mcp<2.0.0,>=1.26.0; extra == 'mcp'
 Provides-Extra: tui
-Requires-Dist: textual>=1.0.0; extra == 'tui'
+Requires-Dist: textual<9.0.0,>=1.0.0; extra == 'tui'
 Description-Content-Type: text/markdown
 
 <p align="right">
@@ -128,10 +136,12 @@ pip install ouroboros-ai[claude]        # + Claude Code deps
 pip install ouroboros-ai[litellm]       # + LiteLLM multi-provider
 pip install ouroboros-ai[mcp]           # + MCP server/client support
 pip install ouroboros-ai[tui]           # + Textual terminal UI
-pip install ouroboros-ai[all]           # everything
+pip install ouroboros-ai[all]           # everything (claude + litellm + mcp + tui + dashboard)
 ouroboros setup                         # configure runtime
 ```
 
+Legacy compatibility: `ouroboros-ai[dashboard]` is still accepted as a compatibility alias while extras migrate.
+
 See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md)
 
 </details>

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/README.ko.md

@@ -125,6 +125,8 @@ pip install ouroboros-ai[all]           # 전부
 ouroboros setup                         # 런타임 설정
 ```
 
+호환성 참고: extras 전환 기간 동안 `ouroboros-ai[dashboard]`도 no-op alias로 계속 허용됩니다.
+
 런타임별 가이드: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md)
 
 </details>

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/README.md

@@ -97,10 +97,12 @@ pip install ouroboros-ai[claude]        # + Claude Code deps
 pip install ouroboros-ai[litellm]       # + LiteLLM multi-provider
 pip install ouroboros-ai[mcp]           # + MCP server/client support
 pip install ouroboros-ai[tui]           # + Textual terminal UI
-pip install ouroboros-ai[all]           # everything
+pip install ouroboros-ai[all]           # everything (claude + litellm + mcp + tui + dashboard)
 ouroboros setup                         # configure runtime
 ```
 
+Legacy compatibility: `ouroboros-ai[dashboard]` is still accepted as a compatibility alias while extras migrate.
+
 See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md)
 
 </details>

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/docs/cli-reference.md

@@ -160,10 +160,6 @@ ouroboros init start --resume interview_20260116_120000
 ouroboros init
 ```
 
-> **Interactive multiline input:** when `init` or other interview-style commands prompt for a
-> longer response, press `Ctrl+D` (macOS/Linux) or `Ctrl+Z` then Enter (Windows) to submit the
-> full response. Plain Enter inserts a newline.
-
 ### `init list`
 
 List all interview sessions.

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/docs/getting-started.md

@@ -82,13 +82,14 @@ pip install ouroboros-ai[claude]      # + Claude Code runtime deps (anthropic, c
 pip install ouroboros-ai[litellm]     # + LiteLLM multi-provider support (100+ models)
 pip install ouroboros-ai[mcp]         # + MCP server/client runtime support
 pip install ouroboros-ai[tui]         # + Textual terminal UI
-pip install ouroboros-ai[all]         # Everything (claude + litellm + mcp + tui)
+pip install ouroboros-ai[all]         # Everything (claude + litellm + mcp + tui + dashboard)
 
 ouroboros --version                   # verify CLI
 ```
 
 > **Which extra do I need?** If you only use Claude Code as your runtime, `ouroboros-ai[claude]` is sufficient.
 > For multi-model support via LiteLLM, use `ouroboros-ai[litellm]` or just grab everything with `ouroboros-ai[all]`.
+> Legacy note: `ouroboros-ai[dashboard]` is still accepted as a compatibility extra during the extras transition.
 
 **One-liner alternative** (auto-detects your runtime and installs matching extras):
 ```bash

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/pyproject.toml

@@ -8,21 +8,27 @@ authors = [
 ]
 requires-python = ">=3.12"
 dependencies = [
-    "aiosqlite>=0.20.0",
-    "pydantic>=2.0.0",
-    "pyyaml>=6.0.0",
-    "rich>=13.0.0",
-    "sqlalchemy[asyncio]>=2.0.0",
-    "structlog>=24.0.0",
-    "typer>=0.12.0",
+    "aiosqlite>=0.20.0,<1.0.0",
+    "pydantic>=2.0.0,<3.0.0",
+    "prompt-toolkit>=3.0.0,<4.0.0",
+    "pyyaml>=6.0.0,<7.0.0",
+    "rich>=13.0.0,<15.0.0",
+    "sqlalchemy[asyncio]>=2.0.0,<3.0.0",
+    "structlog>=24.0.0,<26.0.0",
+    "typer>=0.12.0,<1.0.0",
 ]
 
 [project.optional-dependencies]
-claude = ["claude-agent-sdk>=0.1.0", "anthropic>=0.52.0"]
+claude = ["claude-agent-sdk>=0.1.0,<1.0.0", "anthropic>=0.52.0,<1.0.0"]
 litellm = ["litellm>=1.80.0,<=1.82.6"]
-mcp = ["mcp>=1.26.0"]
-tui = ["textual>=1.0.0"]
-all = ["ouroboros-ai[claude,litellm,mcp,tui]"]
+dashboard = [
+    "streamlit>=1.40.0,<2.0.0",
+    "plotly>=5.24.0,<7.0.0",
+    "pandas>=2.2.0,<3.0.0",
+]
+mcp = ["mcp>=1.26.0,<2.0.0"]
+tui = ["textual>=1.0.0,<9.0.0"]
+all = ["ouroboros-ai[claude,litellm,mcp,tui,dashboard]"]
 
 [project.scripts]
 ouroboros = "ouroboros.cli.main:app"

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.27.3.dev1'
-__version_tuple__ = version_tuple = (0, 27, 3, 'dev1')
+__version__ = version = '0.27.3.dev3'
+__version_tuple__ = version_tuple = (0, 27, 3, 'dev3')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/src/ouroboros/cli/commands/mcp.py

@@ -140,22 +140,35 @@ async def _run_mcp_server(
     else:
         event_store = EventStore()
 
-    # Auto-cancel orphaned sessions on startup.
-    # Sessions left in RUNNING/PAUSED state for >1 hour are considered orphaned
-    # (e.g., from a previous crash). Cancel them before accepting new requests.
-    # NOTE: find_orphaned_sessions now checks for active runtime processes first,
-    # so sessions with live claude/codex agents won't be cancelled even if stale.
+    cleanup_task: asyncio.Task[None] | None = None
+
+    # Initialize the event store up front because the MCP server uses it for
+    # request handling. Orphan cleanup is intentionally deferred into the
+    # background so large SQLite histories do not block the initial MCP
+    # handshake on startup (#304).
     try:
         await event_store.initialize()
-        repo = SessionRepository(event_store)
-        cancelled = await repo.cancel_orphaned_sessions()
-        if cancelled:
-            _stderr_console.print(
-                f"[yellow]Auto-cancelled {len(cancelled)} orphaned session(s)[/yellow]"
-            )
     except Exception as e:
         # Auto-cleanup is best-effort — don't prevent server from starting
         _stderr_console.print(f"[yellow]Warning: auto-cleanup failed: {e}[/yellow]")
+    else:
+        repo = SessionRepository(event_store)
+
+        async def _run_startup_cleanup() -> None:
+            try:
+                cancelled = await repo.cancel_orphaned_sessions()
+                if cancelled:
+                    _stderr_console.print(
+                        f"[yellow]Auto-cancelled {len(cancelled)} orphaned session(s)[/yellow]"
+                    )
+            except Exception as e:
+                # Auto-cleanup is best-effort — don't prevent server startup
+                _stderr_console.print(f"[yellow]Warning: auto-cleanup failed: {e}[/yellow]")
+
+        cleanup_task = asyncio.create_task(
+            _run_startup_cleanup(),
+            name="ouroboros-mcp-startup-cleanup",
+        )
 
     # Auto-discover and connect MCP bridge for server-to-server communication
     from ouroboros.mcp.bridge import create_bridge_from_env
@@ -224,6 +237,12 @@ async def _run_mcp_server(
     try:
         await server.serve(transport=transport, host=host, port=port)
     finally:
+        if cleanup_task is not None and not cleanup_task.done():
+            cleanup_task.cancel()
+            try:
+                await cleanup_task
+            except asyncio.CancelledError:
+                pass
         _cleanup_pid_file()
 
 

ouroboros_ai-0.27.3.dev3/src/ouroboros/cli/formatters/prompting.py

@@ -0,0 +1,38 @@
+"""Prompt helpers for interactive CLI input."""
+
+from __future__ import annotations
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.key_binding import KeyBindings, KeyPressEvent
+from prompt_toolkit.patch_stdout import patch_stdout
+
+from ouroboros.cli.formatters import console
+
+
+async def multiline_prompt_async(prompt_text: str) -> str:
+    """Get multiline-safe input while allowing logs above the active prompt."""
+    bindings = KeyBindings()
+
+    @bindings.add("c-j")
+    def insert_newline(event: KeyPressEvent) -> None:
+        event.current_buffer.insert_text("\n")
+
+    @bindings.add("c-m")
+    def submit(event: KeyPressEvent) -> None:
+        event.current_buffer.validate_and_handle()
+
+    console.print(f"[bold green]{prompt_text}[/] [dim](Enter: submit, Ctrl+J: newline)[/]")
+
+    session: PromptSession[str] = PromptSession(
+        message="> ",
+        multiline=True,
+        prompt_continuation="  ",
+        key_bindings=bindings,
+    )
+
+    # prompt_toolkit proxies both stdout and stderr above the prompt.
+    with patch_stdout(raw=True):
+        return await session.prompt_async()
+
+
+__all__ = ["multiline_prompt_async"]

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/src/ouroboros/config/loader.py

@@ -54,6 +54,8 @@ from ouroboros.core.errors import ConfigError  # noqa: E402
 _CODEX_LLM_BACKENDS = frozenset({"codex", "codex_cli", "opencode", "opencode_cli"})
 _OPENCODE_BACKENDS = frozenset({"opencode", "opencode_cli"})
 _CODEX_DEFAULT_MODEL = "default"
+_PLACEHOLDER_API_KEY_PREFIX = "YOUR_"
+_PLACEHOLDER_API_KEY_SUFFIX = "_API_KEY"
 _DEFAULT_CONSENSUS_MODELS = (
     "openrouter/openai/gpt-4o",
     "openrouter/anthropic/claude-opus-4-6",
@@ -82,6 +84,16 @@ def _parse_env_value(raw_value: str) -> str:
     return candidate.rstrip()
 
 
+def _is_placeholder_api_key(value: str) -> bool:
+    """Treat common template placeholders as unset."""
+    candidate = value.strip()
+    return bool(
+        candidate
+        and candidate.startswith(_PLACEHOLDER_API_KEY_PREFIX)
+        and candidate.endswith(_PLACEHOLDER_API_KEY_SUFFIX)
+    )
+
+
 def _load_env_file(path: Path) -> None:
     if not path.exists():
         return
@@ -99,7 +111,14 @@ def _load_env_file(path: Path) -> None:
         key = key.strip()
         if not key or any(ch.isspace() for ch in key):
             continue
-        os.environ.setdefault(key, _parse_env_value(raw_value))
+
+        parsed_value = _parse_env_value(raw_value)
+        if not parsed_value or _is_placeholder_api_key(parsed_value):
+            continue
+
+        current_value = os.environ.get(key)
+        if current_value is None or _is_placeholder_api_key(current_value):
+            os.environ[key] = parsed_value
 
 
 for env_path in (Path(".env"), Path.home() / ".ouroboros" / ".env"):

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/src/ouroboros/core/file_lock.py

@@ -15,14 +15,14 @@ else:  # pragma: no branch
 
 
 @contextmanager
-def file_lock(file_path: Path, exclusive: bool = True) -> Iterator[None]:  # noqa: ARG001
+def file_lock(file_path: Path, exclusive: bool = True) -> Iterator[None]:
     """Context manager for cross-platform file locking."""
     lock_path = file_path.with_suffix(file_path.suffix + ".lock")
     lock_path.parent.mkdir(parents=True, exist_ok=True)
 
     with lock_path.open("a+", encoding="utf-8") as handle:
         _ensure_lockfile_content(handle)
-        _acquire_lock(handle)
+        _acquire_lock(handle, exclusive=exclusive)
         try:
             yield
         finally:
@@ -37,13 +37,13 @@ def _ensure_lockfile_content(handle: TextIO) -> None:
         handle.seek(0)
 
 
-def _acquire_lock(handle: TextIO) -> None:
+def _acquire_lock(handle: TextIO, *, exclusive: bool = True) -> None:
     if os.name == "nt":  # pragma: no cover - exercised on Windows
         handle.seek(0)
-        msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
+        msvcrt.locking(handle.fileno(), msvcrt.LK_RLCK if not exclusive else msvcrt.LK_LOCK, 1)
         return
 
-    fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+    fcntl.flock(handle.fileno(), fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH)
 
 
 def _release_lock(handle: TextIO) -> None:

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/src/ouroboros/mcp/server/adapter.py

@@ -8,8 +8,10 @@ handling, and server lifecycle.
 import asyncio
 from collections.abc import Sequence
 import inspect
+import keyword
 import os
 from pathlib import Path
+import re
 from typing import Any
 
 import structlog
@@ -105,13 +107,50 @@ def _build_tool_signature(parameters: tuple[MCPToolParameter, ...]) -> inspect.S
     By setting __signature__ with explicit parameters, FastMCP generates the
     correct schema and clients can send flat argument dicts.
     """
+    signature, _ = _build_tool_signature_with_aliases(parameters)
+    return signature
+
+
+def _to_safe_signature_name(name: str) -> str:
+    """Return a valid Python identifier for a tool parameter name."""
+    if name.isidentifier() and not keyword.iskeyword(name):
+        return name
+
+    # Replace invalid characters with underscore and avoid starting with a digit.
+    sanitized = re.sub(r"[^0-9a-zA-Z_]", "_", name)
+    sanitized = re.sub(r"_+", "_", sanitized).strip("_")
+    if not sanitized or sanitized[0].isdigit():
+        sanitized = f"_{sanitized or 'param'}"
+
+    if keyword.iskeyword(sanitized):
+        sanitized = f"_{sanitized}"
+
+    return sanitized
+
+
+def _build_tool_signature_with_aliases(
+    parameters: tuple[MCPToolParameter, ...],
+) -> tuple[inspect.Signature, dict[str, str]]:
+    """Build signature plus map from schema args to original MCP parameter names."""
+
     sig_params = []
+    alias_counts: dict[str, int] = {}
+    alias_to_original: dict[str, str] = {}
+
     for p in parameters:
+        parameter_name = _to_safe_signature_name(p.name)
+        alias_count = alias_counts.get(parameter_name, 0) + 1
+        alias_counts[parameter_name] = alias_count
+        if alias_count > 1:
+            parameter_name = f"{parameter_name}_{alias_count}"
+
+        alias_to_original[parameter_name] = p.name
+
         python_type = _TOOL_TYPE_MAP.get(p.type, Any)
         if p.required:
             sig_params.append(
                 inspect.Parameter(
-                    name=p.name,
+                    name=parameter_name,
                     kind=inspect.Parameter.KEYWORD_ONLY,
                     annotation=python_type,
                 )
@@ -120,13 +159,14 @@ def _build_tool_signature(parameters: tuple[MCPToolParameter, ...]) -> inspect.S
             default = p.default if p.default is not None else None
             sig_params.append(
                 inspect.Parameter(
-                    name=p.name,
+                    name=parameter_name,
                     kind=inspect.Parameter.KEYWORD_ONLY,
                     default=default,
                     annotation=python_type | None,
                 )
             )
-    return inspect.Signature(parameters=sig_params)
+
+    return inspect.Signature(parameters=sig_params), alias_to_original
 
 
 _PROJECT_ROOT_MARKERS = (
@@ -200,11 +240,13 @@ def _project_dir_from_artifact(artifact: str) -> str | None:
     from pathlib import Path
     import re
 
-    # Match quoted paths (spaces allowed) or unquoted paths (no spaces).
+    # Match quoted paths (spaces allowed) and unquoted paths.
     # Examples:  Write: /foo/bar.py  |  File: "/path with spaces/bar.py"
     write_matches: list[str] = []
-    for m in re.finditer(r'(?:Write|Edit|File): (?:"([^"]+)"|(/[^\s]+))', artifact):
-        write_matches.append(m.group(1) or m.group(2))
+    for m in re.finditer(r'(?:Write|Edit|File): (?:"([^"]+)"|(.+))', artifact):
+        path_candidate = m.group(1) or m.group(2)
+        if path_candidate:
+            write_matches.append(path_candidate.strip())
     for path_str in write_matches:
         candidate = Path(path_str).parent
         for _ in range(10):
@@ -529,7 +571,18 @@ class MCPServerAdapter:
                         and isinstance(kwargs["kwargs"], dict)
                     ):
                         kwargs = kwargs["kwargs"]
-                    result = await h.handle(kwargs)
+
+                    _, alias_to_original = _build_tool_signature_with_aliases(
+                        h.definition.parameters,
+                    )
+                    normalized_kwargs: dict[str, Any] = {}
+                    for alias_key, original_key in alias_to_original.items():
+                        if alias_key in kwargs:
+                            normalized_kwargs[original_key] = kwargs[alias_key]
+                    for key, value in kwargs.items():
+                        normalized_kwargs.setdefault(key, value)
+
+                    result = await h.handle(normalized_kwargs)
                     if result.is_ok:
                         # Convert MCPToolResult to FastMCP format
                         tool_result = result.value

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/src/ouroboros/orchestrator/mcp_tools.py

@@ -2059,6 +2059,7 @@ class MCPToolProvider:
 
         try:
             # Retry transient failures with bounded backoff
+            # Use retry_async for retries on transient failures
             result = await self._call_with_retry(
                 tool_info=tool_info,
                 arguments=arguments or {},
@@ -2090,7 +2091,7 @@ class MCPToolProvider:
     ) -> Result[MCPToolResult, MCPToolError]:
         """Call tool with retry logic for transient failures.
 
-        Uses internal exponential backoff retries on:
+        Uses retry_async for exponential backoff retries on:
         - Connection errors
         - Timeout errors (if marked retriable)
         - Other transient MCPClientErrors

{ouroboros_ai-0.27.3.dev1 → ouroboros_ai-0.27.3.dev3}/src/ouroboros/orchestrator/session.py

@@ -34,7 +34,7 @@ from ouroboros.events.base import BaseEvent, sanitize_event_data_for_persistence
 from ouroboros.observability.logging import get_logger
 
 if TYPE_CHECKING:
-    from ouroboros.persistence.event_store import EventStore
+    from ouroboros.persistence.event_store import EventStore, SessionActivitySnapshot
 
 log = get_logger(__name__)
 
@@ -352,6 +352,70 @@ class SessionRepository:
 
         return progress
 
+    @staticmethod
+    def _coerce_snapshot_datetime(value: object) -> datetime | None:
+        """Normalize timestamp values returned by snapshot queries."""
+        if isinstance(value, datetime):
+            if value.tzinfo is None:
+                return value.replace(tzinfo=UTC)
+            return value
+        if isinstance(value, str) and value:
+            parsed = datetime.fromisoformat(value)
+            if parsed.tzinfo is None:
+                return parsed.replace(tzinfo=UTC)
+            return parsed
+        return None
+
+    @classmethod
+    def _status_from_snapshot(cls, snapshot: SessionActivitySnapshot) -> SessionStatus:
+        """Derive session status from a snapshot row."""
+        status = cls._status_from_event(snapshot.status_event_type, {})
+        if status is not None:
+            return status
+
+        runtime_status = cls._coerce_runtime_status(snapshot.runtime_status)
+        if runtime_status is not None:
+            return runtime_status
+
+        return SessionStatus.RUNNING
+
+    async def _find_orphaned_sessions_via_snapshots(
+        self,
+        snapshots: list[SessionActivitySnapshot],
+        alive_sessions: set[str],
+        staleness_threshold: timedelta,
+        now: datetime,
+    ) -> list[SessionTracker]:
+        """Detect orphaned sessions from pre-aggregated session snapshots."""
+        orphaned: list[SessionTracker] = []
+
+        for snapshot in snapshots:
+            status = self._status_from_snapshot(snapshot)
+            if status not in (SessionStatus.RUNNING, SessionStatus.PAUSED):
+                continue
+
+            if snapshot.session_id in alive_sessions:
+                log.info(
+                    "orchestrator.orphan_detection.heartbeat_alive",
+                    session_id=snapshot.session_id,
+                )
+                continue
+
+            last_activity = self._coerce_snapshot_datetime(snapshot.last_activity)
+            if last_activity is None:
+                last_activity = self._coerce_snapshot_datetime(snapshot.start_time)
+            if last_activity is None:
+                continue
+
+            if (now - last_activity) <= staleness_threshold:
+                continue
+
+            result = await self.reconstruct_session(snapshot.session_id)
+            if result.is_ok:
+                orphaned.append(result.value)
+
+        return orphaned
+
     @staticmethod
     def _merge_event_streams(
         primary_events: list[BaseEvent],
@@ -892,6 +956,24 @@ class SessionRepository:
         orphaned: list[SessionTracker] = []
 
         try:
+            get_snapshots = getattr(self._event_store, "get_session_activity_snapshots", None)
+            if callable(get_snapshots):
+                snapshots = await get_snapshots()
+                if isinstance(snapshots, list):
+                    orphaned = await self._find_orphaned_sessions_via_snapshots(
+                        snapshots,
+                        alive_sessions,
+                        staleness_threshold,
+                        now,
+                    )
+                    log.info(
+                        "orchestrator.orphan_detection.complete",
+                        total_sessions=len(snapshots),
+                        orphaned_count=len(orphaned),
+                        strategy="snapshot",
+                    )
+                    return orphaned
+
             # Get all session start events to enumerate sessions
             start_events = await self._event_store.get_all_sessions()
 
@@ -955,6 +1037,7 @@ class SessionRepository:
                 "orchestrator.orphan_detection.complete",
                 total_sessions=len(start_events),
                 orphaned_count=len(orphaned),
+                strategy="replay",
             )
 
         except Exception as e: