ouroboros-ai 0.29.2.dev3__tar.gz → 0.29.3.dev6__tar.gz

{ouroboros_ai-0.29.2.dev3 → ouroboros_ai-0.29.3.dev6}/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "ouroboros",
       "description": "Transform vague ideas into validated seed specifications through Socratic questioning and ontological analysis",
-      "version": "0.29.1",
+      "version": "0.29.2",
       "author": {
         "name": "Q00",
         "email": "jqyu.lee@gmail.com"

{ouroboros_ai-0.29.2.dev3 → ouroboros_ai-0.29.3.dev6}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ouroboros",
-  "version": "0.29.1",
+  "version": "0.29.2",
   "description": "Self-improving AI workflow system. Crystallize requirements before execution with Socratic interview, ambiguity scoring, and 3-stage evaluation.",
   "author": {
     "name": "Q00",

{ouroboros_ai-0.29.2.dev3 → ouroboros_ai-0.29.3.dev6}/CLAUDE.md

@@ -32,6 +32,7 @@ When the user types any of these commands, read the corresponding SKILL.md file
 | `ooo pm` or `ooo pm ...` | Read `skills/pm/SKILL.md` and follow it |
 | `ooo brownfield` or `ooo brownfield ...` | Read `skills/brownfield/SKILL.md` and follow it |
 | `ooo publish` or `ooo publish ...` | Read `skills/publish/SKILL.md` and follow it |
+| `ooo resume` | Read `skills/resume/SKILL.md` and follow it |
 
 **Important**: Do NOT use the Skill tool. Read the file with the Read tool and execute its instructions directly.
 

{ouroboros_ai-0.29.2.dev3 → ouroboros_ai-0.29.3.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.29.2.dev3
+Version: 0.29.3.dev6
 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

ouroboros_ai-0.29.3.dev6/skills/resume/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: resume
+description: "List in-flight sessions and show the commands needed to re-attach after MCP disconnect"
+---
+
+# /ouroboros:resume
+
+Recover in-flight sessions after an unexpected MCP server disconnect.
+
+## Usage
+
+```
+ooo resume
+ooo resume --all
+```
+
+**Trigger keywords:** "resume session", "re-attach", "mcp disconnected", "lost session", "in-flight"
+
+## How It Works
+
+`ooo resume` reads the EventStore directly (no MCP server required) and lists
+every session that is still in a `running` or `paused` state. The command is
+strictly read-only — it never creates the data directory, never writes
+schema, and never appends events. Its job is to surface the identifiers you
+need to re-attach.
+
+- `ooo resume` shows the 20 most recent active sessions.
+- `ooo resume --all` shows every active session.
+
+## Instructions
+
+When the user invokes this skill:
+
+1. Run the CLI command:
+
+   ```
+   ouroboros resume
+   ```
+
+   This reads `~/.ouroboros/ouroboros.db` directly — the MCP server does **not**
+   need to be running.
+
+2. If sessions are listed, enter the number of the session you want to work
+   with. The command prints both the `session_id` and the `exec_id`, along
+   with the two re-attach paths.
+
+3. Pick the right re-attach path:
+
+   - **Inspect only** (read-only interactive monitor):
+
+     ```
+     ouroboros tui monitor
+     ```
+
+     Launches the TUI and lets you pick the session to inspect. The
+     `ouroboros status execution <exec_id>` command is *registered* but its
+     handler is still a placeholder in `src/ouroboros/cli/commands/status.py`
+     (it only prints "Would show details for execution: …"), so it is
+     intentionally not surfaced here. Follow-up tracked as a separate issue.
+
+   - **Resume execution** (requires the original seed file):
+
+     ```
+     ouroboros run workflow --orchestrator --resume <session_id> <seed.yaml>
+     ```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Success — sessions listed, or no sessions found |
+| `1`  | Invalid user selection (non-numeric or out-of-range) |
+| `2`  | EventStore exists but could not be opened or read |
+
+## Fallback (No sessions found)
+
+If the command reports "No in-flight sessions found", the execution either
+completed, failed, was cancelled, or the EventStore has never been created.
+To browse historical sessions interactively, use the TUI monitor:
+
+```
+ouroboros tui monitor
+```
+
+## Example
+
+```
+User: ooo resume
+
+┌─────────────────────── In-Flight Sessions ───────────────────────┐
+│  #  Session ID          Execution ID        Status    Started    │
+│  1  sess-abc123         exec-xyz789         running   2026-04-15 │
+└───────────────────────────────────────────────────────────────────┘
+
+Enter number to re-attach (1-1), or 'q' to quit: 1
+
+╭─ Re-attach ────────────────────────────────────────────────────────────────╮
+│ Session ID:   sess-abc123                                                  │
+│ Execution ID: exec-xyz789                                                  │
+│                                                                            │
+│ Inspect (read-only interactive monitor):                                   │
+│     ouroboros tui monitor                                                  │
+│                                                                            │
+│ Resume execution (requires the original seed file):                        │
+│     ouroboros run workflow --orchestrator --resume sess-abc123 seed-001    │
+╰────────────────────────────────────────────────────────────────────────────╯
+```
+
+## Next Steps
+
+After you have the identifiers:
+
+- `ouroboros tui monitor` — launch the TUI and pick the session to inspect
+- `ouroboros run workflow --orchestrator --resume <session_id> <seed.yaml>` — resume execution
+- `ooo evaluate` — evaluate results once the execution completes
+- `ooo cancel execution <exec_id>` — cancel if the session is stuck

{ouroboros_ai-0.29.2.dev3 → ouroboros_ai-0.29.3.dev6}/skills/setup/SKILL.md

@@ -246,7 +246,7 @@ A backup will be created: CLAUDE.md.bak
 **If "Preview first", show:**
 ````markdown
 <!-- ooo:START -->
-<!-- ooo:VERSION:0.29.1 -->
+<!-- ooo:VERSION:0.29.2 -->
 # Ouroboros — Specification-First AI Development
 
 > Before telling AI what to build, define what should be built.

{ouroboros_ai-0.29.2.dev3 → ouroboros_ai-0.29.3.dev6}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.29.2.dev3'
-__version_tuple__ = version_tuple = (0, 29, 2, 'dev3')
+__version__ = version = '0.29.3.dev6'
+__version_tuple__ = version_tuple = (0, 29, 3, 'dev6')
 
 __commit_id__ = commit_id = None

ouroboros_ai-0.29.3.dev6/src/ouroboros/cli/commands/resume.py

@@ -0,0 +1,333 @@
+"""Resume command for Ouroboros.
+
+List in-flight sessions directly from the EventStore (no MCP dependency).
+The command is intentionally read-only: it never creates the data directory,
+never writes schema, and never appends events. Read-only is enforced at the
+SQLite connection layer via ``EventStore(..., read_only=True)`` so even
+unexpected write paths fail fast with ``attempt to write a readonly
+database``. Its only job is to surface the identifiers a user needs to
+re-attach (inspect with ``ouroboros tui monitor`` or resume execution with
+``ouroboros run workflow --orchestrator --resume <session_id> <seed.yaml>``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from ouroboros.cli.formatters import console
+from ouroboros.cli.formatters.panels import print_error, print_info, print_success
+from ouroboros.cli.formatters.tables import create_table, print_table
+
+app = typer.Typer(
+    name="resume",
+    help="List in-flight sessions and re-attach after MCP disconnect.",
+    invoke_without_command=True,
+)
+
+
+# Default cap on rows shown when many stale sessions accumulate. The user can
+# opt into the full list with ``--all``.
+DEFAULT_DISPLAY_LIMIT = 20
+
+# Exit code surfaced when the EventStore exists but is unreadable. Pinned so
+# users/scripts can branch on it (distinct from the happy "no sessions" path
+# which exits 0).
+EXIT_CORRUPTED_DB = 2
+
+
+def _default_db_path() -> str:
+    """Return the canonical SQLite path used by the running CLI."""
+    return os.path.expanduser("~/.ouroboros/ouroboros.db")
+
+
+async def _get_event_store(db_path: str | None = None):
+    """Open the EventStore read-only.
+
+    Returns ``None`` if the database file does not exist. Intentionally does
+    not create ``~/.ouroboros/`` or run ``metadata.create_all`` — this command
+    is a recovery tool and must not mutate user state. Read-only is enforced
+    at the SQLite connection layer via ``EventStore(..., read_only=True)``
+    so any accidental write path raises
+    ``sqlite3.OperationalError: attempt to write a readonly database``.
+    """
+    from ouroboros.persistence.event_store import EventStore
+
+    resolved = db_path or _default_db_path()
+    if not Path(resolved).exists():
+        return None
+
+    event_store = EventStore(
+        f"sqlite+aiosqlite:///{resolved}",
+        read_only=True,
+    )
+    try:
+        await event_store.initialize()
+    except Exception:
+        # Ensure the partially constructed engine is disposed before we bail
+        # out — otherwise the outer ``finally`` cannot close it (the variable
+        # was never bound in the caller).
+        try:
+            await event_store.close()
+        finally:
+            raise
+    return event_store
+
+
+def _is_active_snapshot(snapshot) -> bool:
+    """Return True when a snapshot is plausibly running or paused.
+
+    Terminal ``status_event_type`` values short-circuit the expensive replay.
+    Non-terminal or progress-only snapshots fall through to reconstruction.
+    """
+    terminal = {
+        "orchestrator.session.completed",
+        "orchestrator.session.failed",
+        "orchestrator.session.cancelled",
+    }
+    return snapshot.status_event_type not in terminal
+
+
+async def _get_in_flight_sessions(event_store, limit: int | None = DEFAULT_DISPLAY_LIMIT) -> list:
+    """Return running or paused session trackers, most-recent-first.
+
+    Uses ``get_session_activity_snapshots`` to narrow candidates without
+    replaying every event for every session, then reconstructs only the
+    snapshots whose latest status is non-terminal.
+    """
+    from ouroboros.orchestrator.session import SessionRepository, SessionStatus
+
+    repo = SessionRepository(event_store)
+
+    try:
+        snapshots = await event_store.get_session_activity_snapshots()
+    except AttributeError:
+        # Older EventStore builds may lack the snapshot helper. Fall back to
+        # the full replay path so the command still works.
+        return await _get_in_flight_sessions_fallback(event_store)
+
+    candidates = [s for s in snapshots if _is_active_snapshot(s)]
+
+    def _activity_key(snapshot) -> str:
+        return str(snapshot.last_activity or snapshot.start_time or "")
+
+    candidates.sort(key=_activity_key, reverse=True)
+
+    in_flight: list = []
+    for snapshot in candidates:
+        result = await repo.reconstruct_session(snapshot.session_id)
+        if result.is_err:
+            continue
+        tracker = result.value
+        if tracker.status in (SessionStatus.RUNNING, SessionStatus.PAUSED):
+            in_flight.append(tracker)
+            if limit is not None and len(in_flight) >= limit:
+                break
+
+    return in_flight
+
+
+async def _get_in_flight_sessions_fallback(event_store) -> list:
+    """Legacy path: replay every session. Retained only for API compatibility."""
+    from ouroboros.orchestrator.session import SessionRepository, SessionStatus
+
+    repo = SessionRepository(event_store)
+    session_events = await event_store.get_all_sessions()
+    if not session_events:
+        return []
+
+    seen: set[str] = set()
+    in_flight: list = []
+    for event in session_events:
+        session_id = event.aggregate_id
+        if session_id in seen:
+            continue
+        seen.add(session_id)
+        result = await repo.reconstruct_session(session_id)
+        if result.is_err:
+            continue
+        tracker = result.value
+        if tracker.status in (SessionStatus.RUNNING, SessionStatus.PAUSED):
+            in_flight.append(tracker)
+    return in_flight
+
+
+def _display_sessions(sessions: list) -> None:
+    """Render in-flight sessions in a numbered table."""
+    table = create_table("In-Flight Sessions")
+    table.add_column("#", style="bold", no_wrap=True, justify="right")
+    table.add_column("Session ID", style="cyan", no_wrap=True)
+    table.add_column("Execution ID", style="dim")
+    table.add_column("Seed ID", style="dim")
+    table.add_column("Status", justify="center")
+    table.add_column("Started", style="dim")
+
+    for idx, tracker in enumerate(sessions, 1):
+        status = tracker.status.value
+        status_style = "success" if status == "running" else "warning"
+        table.add_row(
+            str(idx),
+            tracker.session_id,
+            tracker.execution_id or "-",
+            tracker.seed_id or "-",
+            f"[{status_style}]{status}[/]",
+            tracker.start_time.isoformat(),
+        )
+
+    print_table(table)
+
+
+def _format_reattach_guidance(tracker) -> str:
+    """Build the post-selection guidance block.
+
+    Prints two commands, matching the real CLI contracts:
+
+    - Inspect:   ``ouroboros tui monitor`` (functional TUI; select the session)
+    - Resume:    ``ouroboros run workflow --orchestrator --resume <session_id> <seed.yaml>``
+
+    ``run workflow --resume`` takes a *session_id* (not an execution_id) and
+    also requires the seed file, so both identifiers are surfaced explicitly.
+
+    Note: ``ouroboros status execution <exec_id>`` is *registered* but its
+    implementation is still a placeholder (see src/ouroboros/cli/commands/status.py),
+    so we deliberately do not surface it as an inspection path — it would
+    print misleading "Would show details" output.
+    """
+    exec_id = tracker.execution_id or "<unknown>"
+    seed_hint = tracker.seed_id or "<seed.yaml>"
+
+    inspect_line = "ouroboros tui monitor"
+    resume_line = f"ouroboros run workflow --orchestrator --resume {tracker.session_id} {seed_hint}"
+
+    lines = [
+        f"Session ID:   [bold cyan]{tracker.session_id}[/]",
+        f"Execution ID: [bold cyan]{exec_id}[/]",
+        "",
+        "[bold]Inspect[/] (read-only interactive monitor):",
+        f"    {inspect_line}",
+        "",
+        "[bold]Resume execution[/] (requires the original seed file):",
+        f"    {resume_line}",
+    ]
+    if not tracker.seed_id:
+        lines.append(
+            "[dim]Seed ID was not recorded for this session — replace "
+            "<seed.yaml> with the original seed path.[/]"
+        )
+    return "\n".join(lines)
+
+
+async def _interactive_resume(show_all: bool = False) -> int:
+    """List in-flight sessions and prompt the user to pick one to re-attach.
+
+    Returns the integer exit code the CLI should emit so callers can pin
+    distinct codes for missing DB vs. corrupted DB vs. happy path.
+    """
+    limit = None if show_all else DEFAULT_DISPLAY_LIMIT
+
+    try:
+        event_store = await _get_event_store()
+    except Exception as exc:  # noqa: BLE001 — surface any open error verbatim
+        print_error(f"Failed to open EventStore: {exc}")
+        return EXIT_CORRUPTED_DB
+
+    if event_store is None:
+        print_info("No in-flight sessions found.", "Resume")
+        console.print(
+            "[dim]EventStore does not exist yet. "
+            "Sessions appear here after the MCP server has started at least one run.[/]"
+        )
+        return 0
+
+    try:
+        try:
+            sessions = await _get_in_flight_sessions(event_store, limit=limit)
+        except Exception as exc:  # noqa: BLE001
+            print_error(f"Failed to read EventStore: {exc}")
+            return EXIT_CORRUPTED_DB
+    finally:
+        await event_store.close()
+
+    if not sessions:
+        print_info("No in-flight sessions found.", "Resume")
+        console.print(
+            "[dim]Sessions appear here when the MCP server was disconnected mid-execution.[/]"
+        )
+        return 0
+
+    _display_sessions(sessions)
+    console.print()
+
+    choice = typer.prompt(
+        f"Enter number to re-attach (1-{len(sessions)}), or 'q' to quit",
+        default="q",
+    )
+
+    if choice.strip().lower() == "q":
+        print_info("No session selected.", "Resume")
+        return 0
+
+    try:
+        index = int(choice) - 1
+    except ValueError:
+        print_error(f"Invalid selection: {choice!r}")
+        return 1
+
+    if index < 0 or index >= len(sessions):
+        print_error(f"Selection out of range: {choice}. Expected 1-{len(sessions)}.")
+        return 1
+
+    selected = sessions[index]
+    print_success(_format_reattach_guidance(selected), "Re-attach")
+    return 0
+
+
+@app.callback(invoke_without_command=True)
+def resume(
+    ctx: typer.Context,
+    show_all: Annotated[
+        bool,
+        typer.Option(
+            "--all",
+            "-a",
+            help=(
+                f"Show every in-flight session instead of the most recent {DEFAULT_DISPLAY_LIMIT}."
+            ),
+        ),
+    ] = False,
+) -> None:
+    """List in-flight sessions and get re-attach instructions.
+
+    Reads the EventStore directly — no MCP server required. Use this command
+    after an unexpected MCP disconnect to recover the session/execution IDs
+    and re-attach.
+
+    Re-attach paths surfaced after selection:
+
+        # Inspect (interactive monitor — the `status execution` placeholder is
+        # not wired up yet)
+        ouroboros tui monitor
+
+        # Resume execution (requires the original seed file)
+        ouroboros run workflow --orchestrator --resume <session_id> <seed.yaml>
+
+    Examples:
+
+        # Interactive: list in-flight sessions and pick one
+        ouroboros resume
+
+        # Show every stale active session, not just the 20 most recent
+        ouroboros resume --all
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+    exit_code = asyncio.run(_interactive_resume(show_all=show_all))
+    if exit_code != 0:
+        raise typer.Exit(exit_code)
+
+
+__all__ = ["app"]

{ouroboros_ai-0.29.2.dev3 → ouroboros_ai-0.29.3.dev6}/src/ouroboros/cli/main.py

@@ -21,6 +21,7 @@ from ouroboros.cli.commands import (
     init,
     mcp,
     pm,
+    resume,
     run,
     setup,
     status,
@@ -48,6 +49,7 @@ app.add_typer(setup.app, name="setup")
 app.add_typer(detect.app, name="detect")
 app.add_typer(tui.app, name="tui")
 app.add_typer(pm.app, name="pm")
+app.add_typer(resume.app, name="resume")
 app.add_typer(uninstall.app, name="uninstall")
 
 

{ouroboros_ai-0.29.2.dev3 → ouroboros_ai-0.29.3.dev6}/src/ouroboros/mcp/tools/evaluation_handlers.py

@@ -1252,6 +1252,21 @@ class LateralThinkHandler:
                         "all",
                     ),
                 ),
+                MCPToolParameter(
+                    name="stagnation_pattern",
+                    type=ToolInputType.STRING,
+                    description=(
+                        "Detected stagnation pattern used to suggest a persona when "
+                        "persona is omitted."
+                    ),
+                    required=False,
+                    enum=(
+                        "spinning",
+                        "oscillation",
+                        "no_drift",
+                        "diminishing_returns",
+                    ),
+                ),
                 MCPToolParameter(
                     name="personas",
                     type=ToolInputType.ARRAY,
@@ -1292,6 +1307,7 @@ class LateralThinkHandler:
             Result containing lateral thinking prompt(s) or error.
         """
         from ouroboros.resilience.lateral import LateralThinker, ThinkingPersona
+        from ouroboros.resilience.stagnation import StagnationPattern
 
         problem_context = arguments.get("problem_context")
         if not problem_context:
@@ -1316,7 +1332,18 @@ class LateralThinkHandler:
 
         # --- Parallel multi-persona dispatch path ---
         explicit_list = arguments.get("personas")
-        persona_arg = arguments.get("persona", "contrarian")
+        raw_persona_arg = arguments.get("persona")
+        if explicit_list or raw_persona_arg is None:
+            persona_arg = ""
+        else:
+            persona_arg = str(raw_persona_arg).strip()
+            if not persona_arg:
+                return Result.err(
+                    MCPToolError(
+                        "persona cannot be blank",
+                        tool_name="ouroboros_lateral_think",
+                    )
+                )
         dispatch_all = persona_arg == "all"
 
         if explicit_list or dispatch_all:
@@ -1435,6 +1462,43 @@ class LateralThinkHandler:
             )
 
         # --- Single-persona path ---
+        if not persona_arg:
+            stagnation_pattern_arg = arguments.get("stagnation_pattern")
+            if stagnation_pattern_arg:
+                try:
+                    stagnation_pattern = StagnationPattern(str(stagnation_pattern_arg))
+                except ValueError:
+                    return Result.err(
+                        MCPToolError(
+                            (
+                                f"Invalid stagnation_pattern: {stagnation_pattern_arg}. "
+                                "Must be one of: spinning, oscillation, no_drift, "
+                                "diminishing_returns"
+                            ),
+                            tool_name="ouroboros_lateral_think",
+                        )
+                    )
+
+                from ouroboros.resilience.recovery import suggest_lateral_persona_for_pattern
+
+                suggested = suggest_lateral_persona_for_pattern(
+                    stagnation_pattern,
+                    failed_attempts=failed_attempts,
+                )
+                if suggested is None:
+                    return Result.err(
+                        MCPToolError(
+                            (
+                                "No available lateral thinking persona remains after "
+                                "applying failed_attempts exclusions"
+                            ),
+                            tool_name="ouroboros_lateral_think",
+                        )
+                    )
+                persona_arg = suggested.value
+            else:
+                persona_arg = ThinkingPersona.CONTRARIAN.value
+
         try:
             persona = ThinkingPersona(persona_arg)
         except ValueError: