zwarm 1.1.1__py3-none-any.whl → 1.3.2__py3-none-any.whl

zwarm/cli/main.py

@@ -76,7 +76,7 @@ app = typer.Typer(
     $ zwarm status
 
 [bold]COMMANDS[/]
-    [cyan]init[/]         Initialize zwarm (create config.toml, .zwarm/)
+    [cyan]init[/]         Initialize zwarm (creates .zwarm/ with config)
     [cyan]reset[/]        Reset state and optionally config files
     [cyan]orchestrate[/]  Start orchestrator to delegate tasks to executors
     [cyan]exec[/]         Run a single executor directly (for testing)
@@ -85,7 +85,8 @@ app = typer.Typer(
     [cyan]configs[/]      Manage configuration files
 
 [bold]CONFIGURATION[/]
-    Create [cyan]config.toml[/] or use [cyan]--config[/] flag with YAML files.
+    Config lives in [cyan].zwarm/config.toml[/] (created by init).
+    Use [cyan]--config[/] flag for YAML files.
     See [cyan]zwarm configs list[/] for available configurations.
 
 [bold]ADAPTERS[/]
@@ -140,6 +141,8 @@ def orchestrate(
     resume: Annotated[bool, typer.Option("--resume", help="Resume from previous state")] = False,
     max_steps: Annotated[Optional[int], typer.Option("--max-steps", help="Maximum orchestrator steps")] = None,
     verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Show detailed output")] = False,
+    instance: Annotated[Optional[str], typer.Option("--instance", "-i", help="Instance ID (for isolation/resume)")] = None,
+    instance_name: Annotated[Optional[str], typer.Option("--name", "-n", help="Human-readable instance name")] = None,
 ):
     """
     Start an orchestrator session.
@@ -148,6 +151,9 @@ def orchestrate(
     (Codex, Claude Code). It can have sync conversations or fire-and-forget
     async delegations.
 
+    Each run creates an isolated instance to prevent conflicts when running
+    multiple orchestrators in the same directory.
+
     [bold]Examples:[/]
         [dim]# Simple task[/]
         $ zwarm orchestrate --task "Add a logout button to the navbar"
@@ -165,8 +171,14 @@ def orchestrate(
         [dim]# Override settings[/]
         $ zwarm orchestrate --task "Fix bug" --set executor.adapter=claude_code
 
-        [dim]# Resume interrupted session[/]
-        $ zwarm orchestrate --task "Continue work" --resume
+        [dim]# Named instance (easier to track)[/]
+        $ zwarm orchestrate --task "Add tests" --name test-work
+
+        [dim]# Resume a specific instance[/]
+        $ zwarm orchestrate --resume --instance abc123
+
+        [dim]# List all instances[/]
+        $ zwarm instances
     """
     from zwarm.orchestrator import build_orchestrator
 
@@ -186,6 +198,8 @@ def orchestrate(
     console.print(f"[bold]Starting orchestrator...[/]")
     console.print(f"  Task: {task}")
     console.print(f"  Working dir: {working_dir.absolute()}")
+    if instance:
+        console.print(f"  Instance: {instance}" + (f" ({instance_name})" if instance_name else ""))
     console.print()
 
     # Output handler to show orchestrator messages
@@ -202,11 +216,17 @@ def orchestrate(
             overrides=override_list,
             resume=resume,
             output_handler=output_handler,
+            instance_id=instance,
+            instance_name=instance_name,
         )
 
         if resume:
             console.print("  [dim]Resuming from previous state...[/]")
 
+        # Show instance ID if auto-generated
+        if orchestrator.instance_id and not instance:
+            console.print(f"  [dim]Instance: {orchestrator.instance_id[:8]}[/]")
+
         # Run the orchestrator loop
         console.print("[bold]--- Orchestrator running ---[/]\n")
         result = orchestrator.run(task=task)
@@ -222,16 +242,35 @@ def orchestrate(
         # Save state for potential resume
         orchestrator.save_state()
 
+        # Update instance status
+        if orchestrator.instance_id:
+            from zwarm.core.state import update_instance_status
+            update_instance_status(
+                orchestrator.instance_id,
+                "completed",
+                working_dir / ".zwarm",
+            )
+            console.print(f"  [dim]Instance {orchestrator.instance_id[:8]} marked completed[/]")
+
     except KeyboardInterrupt:
         console.print("\n\n[yellow]Interrupted.[/]")
         if orchestrator:
             orchestrator.save_state()
             console.print("[dim]State saved. Use --resume to continue.[/]")
+            # Keep instance as "active" so it can be resumed
         sys.exit(1)
     except Exception as e:
         console.print(f"\n[red]Error:[/] {e}")
         if verbose:
             console.print_exception()
+        # Update instance status to failed
+        if orchestrator and orchestrator.instance_id:
+            from zwarm.core.state import update_instance_status
+            update_instance_status(
+                orchestrator.instance_id,
+                "failed",
+                working_dir / ".zwarm",
+            )
         sys.exit(1)
 
 
@@ -258,20 +297,17 @@ def exec(
         [dim]# Async mode[/]
         $ zwarm exec --task "Build feature" --mode async
     """
-    from zwarm.adapters.codex_mcp import CodexMCPAdapter
-    from zwarm.adapters.claude_code import ClaudeCodeAdapter
+    from zwarm.adapters import get_adapter
 
     console.print(f"[bold]Running executor directly...[/]")
     console.print(f"  Adapter: [cyan]{adapter.value}[/]")
     console.print(f"  Mode: {mode.value}")
     console.print(f"  Task: {task}")
 
-    if adapter == AdapterType.codex_mcp:
-        executor = CodexMCPAdapter(model=model)
-    elif adapter == AdapterType.claude_code:
-        executor = ClaudeCodeAdapter(model=model)
-    else:
-        console.print(f"[red]Unknown adapter:[/] {adapter}")
+    try:
+        executor = get_adapter(adapter.value, model=model)
+    except ValueError as e:
+        console.print(f"[red]Error:[/] {e}")
         sys.exit(1)
 
     async def run():
@@ -386,6 +422,63 @@ def status(
         console.print("  [dim](none)[/]")
 
 
+@app.command()
+def instances(
+    working_dir: Annotated[Path, typer.Option("--working-dir", "-w", help="Working directory")] = Path("."),
+    all_instances: Annotated[bool, typer.Option("--all", "-a", help="Show all instances (including completed)")] = False,
+):
+    """
+    List all orchestrator instances.
+
+    Shows instances that have been run in this directory. Use --all to include
+    completed instances.
+
+    [bold]Examples:[/]
+        [dim]# List active instances[/]
+        $ zwarm instances
+
+        [dim]# List all instances[/]
+        $ zwarm instances --all
+    """
+    from zwarm.core.state import list_instances as get_instances
+
+    state_dir = working_dir / ".zwarm"
+    all_inst = get_instances(state_dir)
+
+    if not all_inst:
+        console.print("[dim]No instances found.[/]")
+        console.print("[dim]Run 'zwarm orchestrate' to start a new instance.[/]")
+        return
+
+    # Filter if not showing all
+    if not all_instances:
+        all_inst = [i for i in all_inst if i.get("status") == "active"]
+
+    if not all_inst:
+        console.print("[dim]No active instances. Use --all to see completed ones.[/]")
+        return
+
+    console.print(f"[bold]Instances[/] ({len(all_inst)} total)\n")
+
+    for inst in all_inst:
+        status = inst.get("status", "unknown")
+        status_icon = {"active": "[green]●[/]", "completed": "[dim]✓[/]", "failed": "[red]✗[/]"}.get(status, "[dim]?[/]")
+
+        inst_id = inst.get("id", "unknown")[:8]
+        name = inst.get("name", "")
+        task = (inst.get("task") or "")[:60]
+        updated = inst.get("updated_at", "")[:19] if inst.get("updated_at") else ""
+
+        console.print(f"  {status_icon} [bold]{inst_id}[/]" + (f" ({name})" if name and name != inst_id else ""))
+        if task:
+            console.print(f"      [dim]{task}[/]")
+        if updated:
+            console.print(f"      [dim]Updated: {updated}[/]")
+        console.print()
+
+    console.print("[dim]Use --instance <id> with 'orchestrate --resume' to resume an instance.[/]")
+
+
 @app.command()
 def history(
     working_dir: Annotated[Path, typer.Option("--working-dir", "-w", help="Working directory")] = Path("."),
@@ -482,10 +575,13 @@ def configs_list(
         console.print("  [dim]No configuration files found.[/]")
         console.print("\n  [dim]Create a YAML config in configs/ to get started.[/]")
 
-    # Check for config.toml and mention it
-    config_toml = Path.cwd() / "config.toml"
-    if config_toml.exists():
-        console.print(f"\n[dim]Environment: config.toml (loaded automatically)[/]")
+    # Check for config.toml and mention it (check both locations)
+    new_config = Path.cwd() / ".zwarm" / "config.toml"
+    legacy_config = Path.cwd() / "config.toml"
+    if new_config.exists():
+        console.print(f"\n[dim]Environment: .zwarm/config.toml (loaded automatically)[/]")
+    elif legacy_config.exists():
+        console.print(f"\n[dim]Environment: config.toml (legacy location, loaded automatically)[/]")
 
 
 @configs_app.command("show")
@@ -530,9 +626,9 @@ def init(
     Run this once per project to set up zwarm.
 
     [bold]Creates:[/]
-        [cyan]config.toml[/]   Runtime settings (weave, adapter, watchers)
-        [cyan].zwarm/[/]       State directory for sessions and events
-        [cyan]zwarm.yaml[/]    Project config (optional, with --with-project)
+        [cyan].zwarm/[/]              State directory for sessions and events
+        [cyan].zwarm/config.toml[/]   Runtime settings (weave, adapter, watchers)
+        [cyan]zwarm.yaml[/]           Project config (optional, with --with-project)
 
     [bold]Examples:[/]
         [dim]# Interactive setup[/]
@@ -546,13 +642,25 @@ def init(
     """
     console.print("\n[bold cyan]zwarm init[/] - Initialize zwarm configuration\n")
 
-    config_toml_path = working_dir / "config.toml"
-    zwarm_yaml_path = working_dir / "zwarm.yaml"
     state_dir = working_dir / ".zwarm"
+    config_toml_path = state_dir / "config.toml"
+    zwarm_yaml_path = working_dir / "zwarm.yaml"
+
+    # Check for existing config (also check old location for migration)
+    old_config_path = working_dir / "config.toml"
+    if old_config_path.exists() and not config_toml_path.exists():
+        console.print(f"[yellow]Note:[/] Found config.toml in project root.")
+        console.print(f"  Config now lives in .zwarm/config.toml")
+        if not non_interactive:
+            migrate = typer.confirm("  Move to new location?", default=True)
+            if migrate:
+                state_dir.mkdir(parents=True, exist_ok=True)
+                old_config_path.rename(config_toml_path)
+                console.print(f"  [green]✓[/] Moved config.toml to .zwarm/")
 
     # Check for existing files
     if config_toml_path.exists():
-        console.print(f"[yellow]Warning:[/] config.toml already exists")
+        console.print(f"[yellow]Warning:[/] .zwarm/config.toml already exists")
         if not non_interactive:
             overwrite = typer.confirm("Overwrite?", default=False)
             if not overwrite:
@@ -625,7 +733,7 @@ def init(
     (state_dir / "orchestrator").mkdir(exist_ok=True)
     console.print(f"  [green]✓[/] Created .zwarm/")
 
-    # Create config.toml
+    # Create config.toml inside .zwarm/
     if config_toml_path:
         toml_content = _generate_config_toml(
             weave_project=weave_project,
@@ -633,7 +741,7 @@ def init(
             watchers=watchers_enabled,
         )
         config_toml_path.write_text(toml_content)
-        console.print(f"  [green]✓[/] Created config.toml")
+        console.print(f"  [green]✓[/] Created .zwarm/config.toml")
 
     # Create zwarm.yaml
     if create_project_config:
@@ -790,7 +898,8 @@ def reset(
     console.print("\n[bold cyan]zwarm reset[/] - Reset zwarm state\n")
 
     state_dir = working_dir / ".zwarm"
-    config_toml_path = working_dir / "config.toml"
+    config_toml_path = state_dir / "config.toml"  # New location
+    old_config_toml_path = working_dir / "config.toml"  # Legacy location
     zwarm_yaml_path = working_dir / "zwarm.yaml"
 
     # Expand --all flag
@@ -803,8 +912,12 @@ def reset(
     to_delete = []
     if state and state_dir.exists():
         to_delete.append((".zwarm/", state_dir))
-    if config and config_toml_path.exists():
-        to_delete.append(("config.toml", config_toml_path))
+    # Config: check both new and legacy locations (but skip if state already deletes it)
+    if config and not state:
+        if config_toml_path.exists():
+            to_delete.append((".zwarm/config.toml", config_toml_path))
+        if old_config_toml_path.exists():
+            to_delete.append(("config.toml (legacy)", old_config_toml_path))
     if project and zwarm_yaml_path.exists():
         to_delete.append(("zwarm.yaml", zwarm_yaml_path))
 
@@ -975,6 +1088,516 @@ def clean(
     console.print(f"\n[bold green]Cleanup complete.[/] Killed {killed}, failed {failed}.\n")
 
 
+@app.command()
+def interactive(
+    default_adapter: Annotated[AdapterType, typer.Option("--adapter", "-a", help="Default executor adapter")] = AdapterType.codex_mcp,
+    default_dir: Annotated[Path, typer.Option("--dir", "-d", help="Default working directory")] = Path("."),
+    model: Annotated[Optional[str], typer.Option("--model", help="Default model override")] = None,
+    state_dir: Annotated[Path, typer.Option("--state-dir", help="State directory for persistence")] = Path(".zwarm"),
+):
+    """
+    Universal multi-agent CLI for commanding coding agents.
+
+    Spawn multiple agents (Codex, Claude Code) across different directories,
+    manage them interactively, and view their outputs. You are the orchestrator.
+
+    [bold]Commands:[/]
+        [cyan]spawn[/] "task" [opts]      Start a session (see spawn --help)
+        [cyan]ls[/] / [cyan]list[/]               Dashboard of all sessions
+        [cyan]?[/] / [cyan]check[/] ID            Check session status & response
+        [cyan]c[/] / [cyan]converse[/] ID "msg"   Continue sync conversation
+        [cyan]view[/] ID                  Open session output in $EDITOR
+        [cyan]kill[/] ID                  Stop a session
+        [cyan]killall[/]                  Stop all running sessions
+        [cyan]refresh[/]                  Poll all async sessions
+        [cyan]q[/] / [cyan]quit[/]                Exit
+
+    [bold]Spawn Options:[/]
+        spawn "task" --dir ~/project --adapter claude_code --async
+
+    [bold]Examples:[/]
+        $ zwarm interactive
+        > spawn "Build auth module" --dir ~/api --async
+        > spawn "Fix tests" --dir ~/api --async
+        > spawn "Add docs" --dir ~/docs
+        > ls
+        > ? abc123
+        > view abc123
+    """
+    from zwarm.adapters import get_adapter, list_adapters
+    from zwarm.core.models import ConversationSession
+    import argparse
+    import tempfile
+    import subprocess as sp
+
+    console.print("\n[bold cyan]zwarm interactive[/] - Universal Multi-Agent CLI\n")
+    console.print(f"  Default adapter: [cyan]{default_adapter.value}[/]")
+    console.print(f"  Default dir: {default_dir.absolute()}")
+    console.print(f"  Available adapters: {', '.join(list_adapters())}")
+    console.print("\n  Type [cyan]help[/] for commands, [cyan]quit[/] to exit.\n")
+
+    # Adapter cache (lazy-loaded per adapter type)
+    adapters: dict[str, Any] = {}
+
+    def get_or_create_adapter(adapter_name: str, adapter_model: str | None = None) -> Any:
+        """Get cached adapter or create new one."""
+        key = f"{adapter_name}:{adapter_model or 'default'}"
+        if key not in adapters:
+            adapters[key] = get_adapter(adapter_name, model=adapter_model)
+        return adapters[key]
+
+    # Session tracking with metadata
+    sessions: dict[str, ConversationSession] = {}
+    session_dirs: dict[str, Path] = {}  # session_id -> working_dir
+    session_adapters: dict[str, str] = {}  # session_id -> adapter_name
+
+    # Persistence directory
+    interactive_state_dir = state_dir / "interactive"
+    interactive_state_dir.mkdir(parents=True, exist_ok=True)
+
+    def short_id(session_id: str) -> str:
+        """Get short display ID."""
+        return session_id[:8]
+
+    def find_session(query: str) -> tuple[ConversationSession | None, str | None]:
+        """Find session by full or partial ID. Returns (session, full_id)."""
+        if query in sessions:
+            return sessions[query], query
+        for sid, session in sessions.items():
+            if sid.startswith(query):
+                return session, sid
+        return None, None
+
+    def save_session_output(session: ConversationSession) -> Path:
+        """Save session output to file for viewing."""
+        session_dir = interactive_state_dir / short_id(session.id)
+        session_dir.mkdir(exist_ok=True)
+
+        output_file = session_dir / "output.txt"
+        with open(output_file, "w") as f:
+            f.write(f"Session: {session.id}\n")
+            f.write(f"Task: {session.task_description}\n")
+            f.write(f"Adapter: {session.adapter}\n")
+            f.write(f"Model: {session.model}\n")
+            f.write(f"Status: {session.status.value}\n")
+            f.write(f"Mode: {session.mode.value}\n")
+            f.write(f"Working Dir: {session.working_dir}\n")
+            f.write(f"Tokens: {session.token_usage}\n")
+            f.write("\n" + "="*60 + "\n\n")
+
+            for msg in session.messages:
+                f.write(f"[{msg.role.upper()}]\n")
+                f.write(msg.content)
+                f.write("\n\n" + "-"*40 + "\n\n")
+
+        return output_file
+
+    def show_help():
+        help_table = Table(show_header=False, box=None, padding=(0, 2))
+        help_table.add_column("Command", style="cyan", width=35)
+        help_table.add_column("Description")
+        help_table.add_row('spawn "task" [options]', "Start new session")
+        help_table.add_row("  --dir PATH", "Working directory for this session")
+        help_table.add_row("  --adapter NAME", f"Adapter ({', '.join(list_adapters())})")
+        help_table.add_row("  --async / -a", "Fire-and-forget mode")
+        help_table.add_row("  --model NAME", "Model override")
+        help_table.add_row("", "")
+        help_table.add_row("ls / list", "Dashboard of all sessions")
+        help_table.add_row("? / check ID", "Check session status & messages")
+        help_table.add_row("c / converse ID \"msg\"", "Continue sync conversation")
+        help_table.add_row("view ID", "Open session output in $EDITOR")
+        help_table.add_row("raw ID", "Show raw session JSON")
+        help_table.add_row("kill ID", "Stop a session")
+        help_table.add_row("killall", "Stop all running sessions")
+        help_table.add_row("refresh", "Poll all async sessions for updates")
+        help_table.add_row("q / quit", "Exit interactive mode")
+        console.print(help_table)
+
+    def show_sessions():
+        if not sessions:
+            console.print("  [dim]No sessions yet. Use 'spawn \"task\"' to start one.[/]")
+            return
+
+        table = Table(title="Sessions Dashboard", show_header=True)
+        table.add_column("ID", style="cyan", width=10)
+        table.add_column("Status", width=12)
+        table.add_column("Adapter", width=12)
+        table.add_column("Dir", width=20)
+        table.add_column("Tokens", width=8, justify="right")
+        table.add_column("Task", width=35)
+
+        for sid, s in sessions.items():
+            status_icons = {
+                "active": "[green]● active[/]",
+                "completed": "[dim]✓ done[/]",
+                "failed": "[red]✗ failed[/]",
+            }
+            status = status_icons.get(s.status.value, f"? {s.status.value}")
+
+            # Add mode indicator
+            if s.mode.value == "async" and s.status.value == "active":
+                status = "[yellow]⟳ running[/]"
+
+            work_dir = session_dirs.get(sid, s.working_dir)
+            dir_display = str(work_dir.name) if work_dir else "."
+
+            table.add_row(
+                short_id(sid),
+                status,
+                s.adapter,
+                dir_display,
+                str(s.token_usage.get("total_tokens", 0)),
+                s.task_description[:32] + "..." if len(s.task_description) > 32 else s.task_description,
+            )
+
+        console.print(table)
+
+    def parse_spawn_args(args: list[str]) -> dict:
+        """Parse spawn command arguments."""
+        parser = argparse.ArgumentParser(add_help=False)
+        parser.add_argument("task", nargs="*")
+        parser.add_argument("--dir", "-d", type=Path, default=None)
+        parser.add_argument("--adapter", default=None)
+        parser.add_argument("--model", "-m", default=None)
+        parser.add_argument("--async", "-a", dest="is_async", action="store_true")
+
+        try:
+            parsed, _ = parser.parse_known_args(args)
+            return {
+                "task": " ".join(parsed.task) if parsed.task else "",
+                "dir": parsed.dir,
+                "adapter": parsed.adapter,
+                "model": parsed.model,
+                "is_async": parsed.is_async,
+            }
+        except SystemExit:
+            return {"error": "Invalid spawn arguments"}
+
+    def do_spawn(args: list[str]):
+        """Spawn a new session with optional per-session config."""
+        parsed = parse_spawn_args(args)
+
+        if "error" in parsed:
+            console.print(f"  [red]{parsed['error']}[/]")
+            console.print("  [dim]Usage: spawn \"task\" [--dir PATH] [--adapter NAME] [--async][/]")
+            return
+
+        if not parsed["task"]:
+            console.print("  [red]Task required[/]")
+            console.print("  [dim]Usage: spawn \"task\" [--dir PATH] [--adapter NAME] [--async][/]")
+            return
+
+        task = parsed["task"]
+        work_dir = (parsed["dir"] or default_dir).absolute()
+        adapter_name = parsed["adapter"] or default_adapter.value
+        adapter_model = parsed["model"] or model
+        mode = "async" if parsed["is_async"] else "sync"
+
+        # Validate directory exists
+        if not work_dir.exists():
+            console.print(f"  [red]Directory not found:[/] {work_dir}")
+            return
+
+        console.print(f"\n[dim]Spawning {mode} session...[/]")
+        console.print(f"  [dim]Dir: {work_dir}[/]")
+        console.print(f"  [dim]Adapter: {adapter_name}[/]")
+
+        try:
+            executor = get_or_create_adapter(adapter_name, adapter_model)
+            session = asyncio.run(
+                executor.start_session(
+                    task=task,
+                    working_dir=work_dir,
+                    mode=mode,
+                    model=adapter_model,
+                )
+            )
+
+            sessions[session.id] = session
+            session_dirs[session.id] = work_dir
+            session_adapters[session.id] = adapter_name
+
+            console.print(f"  [green]✓[/] Session: [cyan]{short_id(session.id)}[/]")
+            console.print(f"  Tokens: {session.token_usage.get('total_tokens', 0)}")
+
+            if mode == "sync" and session.messages:
+                for msg in session.messages:
+                    if msg.role == "assistant":
+                        console.print(f"\n[bold]Response:[/]")
+                        content = msg.content[:2000] + ("..." if len(msg.content) > 2000 else "")
+                        console.print(Panel(content, border_style="green"))
+            else:
+                console.print(f"  [dim]Async session started. Use '? {short_id(session.id)}' to check status.[/]")
+
+            # Save output for viewing
+            save_session_output(session)
+
+        except Exception as e:
+            console.print(f"  [red]Error:[/] {e}")
+            import traceback
+            console.print(f"  [dim]{traceback.format_exc()}[/]")
+
+    def do_converse(session_id: str, message: str):
+        session, sid = find_session(session_id)
+        if not session:
+            console.print(f"  [red]Session not found:[/] {session_id}")
+            console.print(f"  [dim]Use 'ls' to see available sessions[/]")
+            return
+
+        if session.mode.value != "sync":
+            console.print(f"  [yellow]Warning:[/] Session is async, can't converse")
+            return
+
+        if session.status.value != "active":
+            console.print(f"  [yellow]Warning:[/] Session is {session.status.value}")
+            return
+
+        console.print(f"\n[dim]Sending message to {short_id(session.id)}...[/]")
+
+        try:
+            adapter_name = session_adapters.get(sid, default_adapter.value)
+            executor = get_or_create_adapter(adapter_name)
+            response = asyncio.run(executor.send_message(session, message))
+            console.print(f"  [green]✓[/] Response received")
+            console.print(f"  Tokens: {session.token_usage.get('total_tokens', 0)}")
+            console.print(f"\n[bold]Response:[/]")
+            console.print(Panel(response[:2000] + ("..." if len(response) > 2000 else ""), border_style="green"))
+
+            # Update saved output
+            save_session_output(session)
+
+        except Exception as e:
+            console.print(f"  [red]Error:[/] {e}")
+
+    def do_check(session_id: str):
+        session, sid = find_session(session_id)
+        if not session:
+            console.print(f"  [red]Session not found:[/] {session_id}")
+            return
+
+        work_dir = session_dirs.get(sid, session.working_dir)
+
+        console.print(f"\n[bold]Session {short_id(session.id)}[/]")
+        console.print(f"  Status: {session.status.value}")
+        console.print(f"  Mode: {session.mode.value}")
+        console.print(f"  Adapter: {session.adapter}")
+        console.print(f"  Model: {session.model}")
+        console.print(f"  Directory: {work_dir}")
+        console.print(f"  Messages: {len(session.messages)}")
+        console.print(f"  Tokens: {session.token_usage}")
+        console.print(f"  Task: {session.task_description}")
+
+        if session.mode.value == "async" and session.status.value == "active":
+            try:
+                adapter_name = session_adapters.get(sid, default_adapter.value)
+                executor = get_or_create_adapter(adapter_name)
+                status = asyncio.run(executor.check_status(session))
+                console.print(f"\n[bold]Async status:[/]")
+                for k, v in status.items():
+                    if k != "events":  # Skip verbose events
+                        val_str = str(v)[:200] + "..." if len(str(v)) > 200 else str(v)
+                        console.print(f"  {k}: {val_str}")
+
+                # Update saved output after status check
+                save_session_output(session)
+
+            except Exception as e:
+                console.print(f"  [red]Status check error:[/] {e}")
+
+        # Show messages
+        if session.messages:
+            console.print(f"\n[bold]Messages:[/]")
+            for i, msg in enumerate(session.messages):
+                role_color = {"user": "blue", "assistant": "green", "system": "yellow"}.get(msg.role, "white")
+                content_preview = msg.content[:500] + "..." if len(msg.content) > 500 else msg.content
+                console.print(f"  [{role_color}]{msg.role}[/]: {content_preview}")
+
+    def do_view(session_id: str):
+        """Open session output in $EDITOR."""
+        session, sid = find_session(session_id)
+        if not session:
+            console.print(f"  [red]Session not found:[/] {session_id}")
+            return
+
+        output_file = save_session_output(session)
+        editor = os.environ.get("EDITOR", "less")
+
+        console.print(f"  [dim]Opening {output_file} in {editor}...[/]")
+        try:
+            sp.run([editor, str(output_file)])
+        except Exception as e:
+            console.print(f"  [red]Error opening editor:[/] {e}")
+            console.print(f"  [dim]File saved at: {output_file}[/]")
+
+    def do_raw(session_id: str):
+        """Show raw session data for debugging."""
+        session, _ = find_session(session_id)
+        if not session:
+            console.print(f"  [red]Session not found:[/] {session_id}")
+            return
+
+        import json
+        console.print(f"\n[bold]Raw session data for {short_id(session.id)}:[/]")
+        console.print(json.dumps(session.to_dict(), indent=2, default=str))
+
+    def do_kill(session_id: str):
+        session, sid = find_session(session_id)
+        if not session:
+            console.print(f"  [red]Session not found:[/] {session_id}")
+            return
+
+        try:
+            adapter_name = session_adapters.get(sid, default_adapter.value)
+            executor = get_or_create_adapter(adapter_name)
+            asyncio.run(executor.stop(session))
+            console.print(f"  [green]✓[/] Session {short_id(session.id)} killed")
+            save_session_output(session)
+        except Exception as e:
+            console.print(f"  [red]Error:[/] {e}")
+
+    def do_killall():
+        """Kill all running sessions."""
+        killed = 0
+        for sid, session in sessions.items():
+            if session.status.value == "active":
+                try:
+                    adapter_name = session_adapters.get(sid, default_adapter.value)
+                    executor = get_or_create_adapter(adapter_name)
+                    asyncio.run(executor.stop(session))
+                    killed += 1
+                except Exception:
+                    pass
+        console.print(f"  [green]✓[/] Killed {killed} sessions")
+
+    def do_refresh():
+        """Poll all async sessions for status updates."""
+        updated = 0
+        for sid, session in sessions.items():
+            if session.mode.value == "async" and session.status.value == "active":
+                try:
+                    adapter_name = session_adapters.get(sid, default_adapter.value)
+                    executor = get_or_create_adapter(adapter_name)
+                    status = asyncio.run(executor.check_status(session))
+                    save_session_output(session)
+                    updated += 1
+
+                    if status.get("status") in ("completed", "failed"):
+                        icon = "[green]✓[/]" if status["status"] == "completed" else "[red]✗[/]"
+                        console.print(f"  {icon} {short_id(sid)}: {status['status']}")
+                except Exception as e:
+                    console.print(f"  [red]✗[/] {short_id(sid)}: {e}")
+
+        if updated == 0:
+            console.print("  [dim]No async sessions to refresh[/]")
+        else:
+            console.print(f"  [dim]Refreshed {updated} sessions[/]")
+
+    # REPL loop
+    import shlex
+
+    while True:
+        try:
+            raw_input = console.input("[bold cyan]>[/] ").strip()
+            if not raw_input:
+                continue
+
+            # Parse command
+            try:
+                parts = shlex.split(raw_input)
+            except ValueError:
+                # Handle unclosed quotes
+                parts = raw_input.split()
+
+            cmd = parts[0].lower()
+            args = parts[1:]
+
+            if cmd in ("q", "quit", "exit"):
+                # Offer to kill running sessions
+                running = [s for s in sessions.values() if s.status.value == "active"]
+                if running:
+                    console.print(f"  [yellow]Warning:[/] {len(running)} sessions still running")
+                    console.print("  [dim]Use 'killall' first, or they'll continue in background[/]")
+                console.print("\n[dim]Goodbye![/]\n")
+                break
+
+            elif cmd in ("h", "help"):
+                show_help()
+
+            elif cmd in ("ls", "list"):
+                show_sessions()
+
+            elif cmd == "spawn":
+                do_spawn(args)
+
+            # Keep old shortcuts for convenience
+            elif cmd in ("d", "delegate"):
+                if not args:
+                    console.print("  [red]Usage:[/] d \"task\" or spawn \"task\" [options]")
+                else:
+                    do_spawn(args)  # Sync by default
+
+            elif cmd in ("a", "async"):
+                if not args:
+                    console.print("  [red]Usage:[/] a \"task\" or spawn \"task\" --async")
+                else:
+                    do_spawn(args + ["--async"])
+
+            elif cmd in ("c", "converse"):
+                if len(args) < 2:
+                    console.print("  [red]Usage:[/] c SESSION_ID \"message\"")
+                else:
+                    do_converse(args[0], " ".join(args[1:]))
+
+            elif cmd in ("?", "check"):
+                if not args:
+                    console.print("  [red]Usage:[/] ? SESSION_ID")
+                else:
+                    do_check(args[0])
+
+            elif cmd == "view":
+                if not args:
+                    console.print("  [red]Usage:[/] view SESSION_ID")
+                else:
+                    do_view(args[0])
+
+            elif cmd == "raw":
+                if not args:
+                    console.print("  [red]Usage:[/] raw SESSION_ID")
+                else:
+                    do_raw(args[0])
+
+            elif cmd == "kill":
+                if not args:
+                    console.print("  [red]Usage:[/] kill SESSION_ID")
+                else:
+                    do_kill(args[0])
+
+            elif cmd == "killall":
+                do_killall()
+
+            elif cmd == "refresh":
+                do_refresh()
+
+            elif cmd in ("e", "end"):
+                # Alias for kill
+                if not args:
+                    console.print("  [red]Usage:[/] kill SESSION_ID")
+                else:
+                    do_kill(args[0])
+
+            else:
+                console.print(f"  [yellow]Unknown command:[/] {cmd}")
+                console.print("  [dim]Type 'help' for available commands[/]")
+
+        except KeyboardInterrupt:
+            console.print("\n[dim](Ctrl+C to exit, or type 'quit')[/]")
+        except EOFError:
+            console.print("\n[dim]Goodbye![/]\n")
+            break
+        except Exception as e:
+            console.print(f"  [red]Error:[/] {e}")
+
+
 @app.callback(invoke_without_command=True)
 def main_callback(
     ctx: typer.Context,