gdmcode 0.1.0__py3-none-any.whl

src/commands.py

@@ -0,0 +1,1398 @@
+"""Slash-command dispatcher for the gdm REPL.
+
+Supported commands: /help /model /cost /tasks /btw /compact /clear /status
+/sessions /allow-all /exit /quit /diff /undo /rollback /branch /pr /commit /browser /replay
+/proxy
+"""
+from __future__ import annotations
+
+import logging
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable
+from urllib.parse import urlparse
+
+from rich.console import Console
+from rich.table import Table
+
+from src.git_workflow import GitWorkflow
+
+if TYPE_CHECKING:
+    from src.cost_tracker import CostTracker
+    from src.memory.db import GdmDatabase
+
+__all__ = ["CommandResult", "CommandDispatcher"]
+
+log = logging.getLogger(__name__)
+
+_VALID_TIERS: frozenset[str] = frozenset({"scout", "coder", "thinker", "reasoner", "debate"})
+
+
+def _relative_time(dt_str: str | None, now: datetime) -> str:
+    """Return a human-readable relative time string (e.g. '5m ago', '3h ago')."""
+    if not dt_str:
+        return "unknown"
+    try:
+        dt = datetime.fromisoformat(dt_str.replace("Z", "+00:00"))
+        delta = now - dt.astimezone(timezone.utc)
+        secs = int(delta.total_seconds())
+        if secs < 0:
+            return "just now"
+        if secs < 60:
+            return f"{secs}s ago"
+        if secs < 3600:
+            return f"{secs // 60}m ago"
+        if secs < 86400:
+            return f"{secs // 3600}h ago"
+        return f"{secs // 86400}d ago"
+    except (ValueError, AttributeError):
+        return dt_str[:16] if dt_str else "unknown"
+
+_COMMANDS: dict[str, str] = {
+    "/help": "Show this help message",
+    "/model [tier]": "Show or set model tier (scout|coder|thinker|reasoner|debate)",
+    "/cost": "Show session cost summary",
+    "/tasks": "List pending /btw notes and active tasks",
+    "/btw <message>": "Queue a background note for the agent",
+    "/compact": "Force context compression (evict old turns)",
+    "/clear": "Clear the terminal screen",
+    "/status": "Show session info (provider, model, cost, turns)",
+    "/sessions": "List recent sessions with ID, start time, turns, cost, status",
+    "/daemon [status]": "Show background daemon job queue",
+    "/resume [session_id]": "Restore a session transcript from checkpoint (defaults to most recent active)",
+    "/review": "Trigger a manual security review of recent writes",
+    "/allow-all": "Bypass permission prompts for this session",
+    "/diff": "Show git diff of pending gdm changes",
+    "/undo": "Undo last checkpoint commit (git reset HEAD~1)",
+    "/rollback": "Full rollback to pre-task state (confirms before executing)",
+    "/branch": "Show current task branch and checkpoint history",
+    "/pr": "Push task branch and generate a PR description",
+    "/commit [msg]": "Create a git checkpoint commit with optional message",
+    "/browser [start|stop|status]": "Manage the bridge server for browser automation",
+    "/remote [start|stop|status|qr]": "Manage remote tunnel (phone pairing via QR code)",
+    "/replay [session_id]": "Replay past session; compare/fork/export sub-commands available",
+    "/doctor": "Show resolved model IDs for every provider/tier",
+    "/reasoning [on|off|auto]": "Toggle per-turn reasoning tier (on=Reasoner, off=Scout, auto=classifier)",
+    "/artifacts [view|diff|search|export] ...": "List, view, diff, search, or export saved artifacts",
+    "/save [name]": "Save the last assistant response as a named artifact",
+    "/proxy [on|off|url <url>|token <tok>|status]": "Route LLM calls via proxy (for geo-blocked regions)",
+    "/exit, /quit": "Exit the REPL",
+}
+
+
+@dataclass
+class CommandResult:
+    """Result returned by CommandDispatcher.handle()."""
+
+    handled: bool
+    output: str = ""
+    should_exit: bool = False
+    force_compact: bool = False
+    new_model_tier: str | None = None
+    allow_all: bool = False
+    force_resume: bool = False
+    resume_session_id: str | None = None
+    new_reasoning_mode: str | None = None
+    save_artifact_name: str | None = None  # /save command: loop saves last assistant response
+    proxy_action: str | None = None  # "enable" | "disable"
+    proxy_url: str | None = None
+    proxy_token: str | None = None
+    prompt_secret: str | None = None  # if set, REPL prompts for hidden input then calls apply_proxy_token
+
+
+class CommandDispatcher:
+    """Parses and executes /commands typed in the REPL."""
+
+    def __init__(
+        self,
+        session_id: str,
+        db: "GdmDatabase",
+        cost_tracker: "CostTracker",
+        *,
+        current_tier: str = "coder",
+        provider: str = "grok",
+        console: Console | None = None,
+        project_root: Path | None = None,
+        confirm_fn: "Callable[[], str] | None" = None,
+        cfg: "object | None" = None,
+    ) -> None:
+        self._session_id = session_id
+        self._db = db
+        self._cost_tracker = cost_tracker
+        self._current_tier = current_tier
+        self._provider = provider
+        self._console = console or Console()
+        self._project_root: Path = project_root or Path.cwd()
+        # Callable used for destructive-action confirmation (e.g. /rollback).
+        # None means fall back to bare input() at call time (patchable in tests).
+        self._confirm_fn: "Callable[[], str] | None" = confirm_fn
+        # Optional GdmConfig for model-assisted features (PR description, etc.)
+        self._cfg = cfg
+        # Reasoning mode — shared with AgentLoop; /reasoning command updates both
+        self._reasoning_mode: str = "auto"
+        # Proxy state — initialised from cfg; kept in sync with AgentLoop
+        from src.models.definitions import PROXY_DEFAULT_URL
+        self._proxy_enabled: bool = getattr(cfg, "proxy_enabled", False)
+        self._proxy_url: str = getattr(cfg, "proxy_url", None) or PROXY_DEFAULT_URL
+        self._proxy_token: str = getattr(cfg, "proxy_token", None) or ""
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def is_command(self, text: str) -> bool:
+        """Return True if *text* looks like a slash command."""
+        return text.strip().startswith("/")
+
+    def handle(self, text: str) -> CommandResult:
+        """Parse and dispatch *text* as a slash command.
+
+        Returns CommandResult(handled=False) for unknown commands so the
+        caller can decide what to do (e.g. show an error or pass to agent).
+        """
+        stripped = text.strip()
+        parts = stripped.split(None, 2)
+        if not parts:
+            return CommandResult(handled=False)
+        cmd = parts[0].lower()
+        match cmd:
+            case "/help":
+                return self._cmd_help()
+            case "/model":
+                return self._cmd_model(parts[1:])
+            case "/cost":
+                return self._cmd_cost()
+            case "/tasks":
+                return self._cmd_tasks()
+            case "/btw":
+                return self._cmd_btw(stripped[len("/btw"):].strip())
+            case "/compact":
+                return CommandResult(handled=True, force_compact=True, output="Compressing context...")
+            case "/clear":
+                self._console.clear()
+                return CommandResult(handled=True)
+            case "/status":
+                return self._cmd_status()
+            case "/daemon":
+                return self._cmd_daemon()
+            case "/sessions":
+                return self._cmd_sessions()
+            case "/resume":
+                return self._cmd_resume(parts[1] if len(parts) > 1 else None)
+            case "/review":
+                return CommandResult(handled=True, output="[dim]Review gate is triggered automatically after security-sensitive writes.[/dim]")
+            case "/allow-all":
+                return CommandResult(
+                    handled=True,
+                    allow_all=True,
+                    output="[green]Permission checks bypassed for this session.[/green]",
+                )
+            case "/diff":
+                return self._cmd_diff()
+            case "/undo":
+                n = int(parts[1]) if len(parts) > 1 and parts[1].isdigit() else 1
+                return self._cmd_undo(n=n)
+            case "/rollback":
+                checkpoint_id = parts[1] if len(parts) > 1 else None
+                return self._cmd_rollback(checkpoint_id=checkpoint_id)
+            case "/branch":
+                return self._cmd_branch()
+            case "/pr":
+                return self._cmd_pr()
+            case "/commit":
+                return self._cmd_commit(parts[1:])
+            case "/browser":
+                return self._cmd_browser(parts[1:])
+            case "/remote":
+                return self._cmd_remote(parts[1:])
+            case "/replay":
+                return self._cmd_replay(parts[1:])
+            case "/doctor":
+                return self._cmd_doctor()
+            case "/reasoning":
+                return self._cmd_reasoning(parts[1:])
+            case "/artifacts":
+                return self._cmd_artifacts(parts[1:])
+            case "/save":
+                return self._cmd_save(parts[1] if len(parts) > 1 else "")
+            case "/proxy":
+                return self._cmd_proxy(parts[1:])
+            case "/exit" | "/quit":
+                return CommandResult(handled=True, should_exit=True)
+            case _:
+                return CommandResult(
+                    handled=False,
+                    output=f"[yellow]Unknown command: {cmd!r}. Type /help for help.[/yellow]",
+                )
+
+    # ------------------------------------------------------------------
+    # Command implementations
+    # ------------------------------------------------------------------
+
+    def _cmd_help(self) -> CommandResult:
+        """Display a table of all available slash commands."""
+        tbl = Table(title="gdm slash commands", header_style="bold cyan", show_lines=False)
+        tbl.add_column("Command", style="cyan", no_wrap=True)
+        tbl.add_column("Description")
+        for cmd, desc in _COMMANDS.items():
+            tbl.add_row(cmd, desc)
+        self._console.print(tbl)
+        return CommandResult(handled=True)
+
+    def _cmd_model(self, args: list[str]) -> CommandResult:
+        """Show current model tier, or change it to *args[0]*."""
+        if not args:
+            return CommandResult(
+                handled=True,
+                output=f"Current model tier: [cyan]{self._current_tier}[/cyan]",
+            )
+        tier = args[0].lower()
+        if tier not in _VALID_TIERS:
+            valid = ", ".join(sorted(_VALID_TIERS))
+            return CommandResult(
+                handled=True,
+                output=f"[red]Invalid tier {tier!r}.[/red] Choose from: {valid}",
+            )
+        self._current_tier = tier
+        return CommandResult(handled=True, new_model_tier=tier, output=f"Model tier set to [cyan]{tier}[/cyan]")
+
+    def _cmd_cost(self) -> CommandResult:
+        """Display a rich table of the session cost summary."""
+        summary = self._cost_tracker.summary()
+        tbl = Table(title="Session Cost", show_header=False, min_width=38)
+        tbl.add_column("Key", style="dim")
+        tbl.add_column("Value", style="bold")
+        for key, val in summary.items():
+            display = f"${val:.6f}" if key == "total_usd" else str(val)
+            tbl.add_row(key.replace("_", " "), display)
+        self._console.print(tbl)
+        return CommandResult(handled=True)
+
+    def _cmd_tasks(self) -> CommandResult:
+        """Show unread /btw notes and pending / in-progress tasks."""
+        self._show_btw_notes()
+        self._show_active_tasks()
+        return CommandResult(handled=True)
+
+    def _show_btw_notes(self) -> None:
+        """Print unread btw_queue rows for this session."""
+        try:
+            rows = self._db.execute_all(
+                "SELECT id, message, created_at FROM btw_queue "
+                "WHERE session_id = ? AND read_at IS NULL ORDER BY created_at",
+                (self._session_id,),
+            )
+        except Exception as exc:  # noqa: BLE001
+            log.warning("btw_queue read failed: %s", exc)
+            return
+        if not rows:
+            return
+        tbl = Table(title="Queued Notes (/btw)", header_style="bold yellow", show_lines=True)
+        tbl.add_column("#", style="dim", width=5)
+        tbl.add_column("Message")
+        tbl.add_column("Queued at", style="dim")
+        for row in rows:
+            tbl.add_row(str(row["id"]), row["message"], row["created_at"])
+        self._console.print(tbl)
+
+    def _show_active_tasks(self) -> None:
+        """Print pending/in-progress tasks from the tasks table for this session."""
+        try:
+            rows = self._db.execute_all(
+                "SELECT task_id, title, status FROM tasks "
+                "WHERE session_id = ? AND status IN ('pending','in_progress') ORDER BY status",
+                (self._session_id,),
+            )
+        except Exception as exc:  # noqa: BLE001
+            log.warning("tasks read failed: %s", exc)
+            return
+        if not rows:
+            self._console.print("[dim]No pending tasks.[/dim]")
+            return
+        tbl = Table(title="Active Tasks", header_style="bold cyan", show_lines=True)
+        tbl.add_column("Status", width=12)
+        tbl.add_column("ID", style="dim")
+        tbl.add_column("Title")
+        for row in rows:
+            colour = "yellow" if row["status"] == "in_progress" else "white"
+            tbl.add_row(f"[{colour}]{row['status']}[/{colour}]", row["task_id"], row["title"])
+        self._console.print(tbl)
+
+    def _cmd_btw(self, message: str) -> CommandResult:
+        """Insert *message* into btw_queue for the agent to pick up later."""
+        if not message:
+            return CommandResult(handled=True, output="[yellow]Usage: /btw <message>[/yellow]")
+
+        # Length guard — prevent transcript bloat / abuse
+        _BTW_MAX_LEN = 500
+        if len(message) > _BTW_MAX_LEN:
+            return CommandResult(
+                handled=True,
+                output=f"[red]Message too long[/red] ({len(message)} chars, max {_BTW_MAX_LEN}).",
+            )
+
+        # Injection check — warn but still enqueue (user is trusted; just advisory)
+        from src.security import check_user_injection
+        inj = check_user_injection(message)
+        if inj.is_injected:
+            log.warning("btw message looks like injection attempt: %s", inj.patterns)
+
+        ts = datetime.now(timezone.utc).isoformat()
+        try:
+            self._db.execute(
+                "INSERT INTO btw_queue (session_id, message, created_at) VALUES (?, ?, ?)",
+                (self._session_id, message, ts),
+            )
+        except Exception as exc:  # noqa: BLE001
+            log.warning("btw_queue insert failed: %s", exc)
+            return CommandResult(handled=True, output=f"[red]Queue failed:[/red] {exc}")
+        return CommandResult(handled=True, output=f"[green]Queued:[/green] {message}")
+
+    def _cmd_daemon(self) -> CommandResult:
+        """Show background daemon job queue status."""
+        try:
+            from src.agent.daemon import BackgroundDaemon
+            daemon = BackgroundDaemon(db=self._db)
+            pending = daemon.pending_count()
+            running = daemon.is_running
+            state = "[green]running[/green]" if running else "[dim]stopped[/dim]"
+            msg = f"Daemon: {state}  |  Pending jobs: [bold]{pending}[/bold]"
+        except Exception as exc:  # noqa: BLE001
+            msg = f"[yellow]Daemon unavailable:[/yellow] {exc}"
+        return CommandResult(handled=True, output=msg)
+
+    def _cmd_status(self) -> CommandResult:
+        """Display a session status table (provider, tier, cost, turns, tokens)."""
+        summary = self._cost_tracker.summary()
+        total_tokens = (
+            int(summary.get("input_tokens", 0)) + int(summary.get("output_tokens", 0))
+        )
+        tbl = Table(title="Session Status", show_header=False, min_width=38)
+        tbl.add_column("Field", style="dim")
+        tbl.add_column("Value", style="bold")
+        tbl.add_row("Provider", self._provider)
+        tbl.add_row("Model tier", self._current_tier)
+        tbl.add_row("Session ID", self._session_id[:8] + "...")
+        tbl.add_row("Turns used", str(summary.get("turns", 0)))
+        tbl.add_row("Cost so far", f"${summary.get('total_usd', 0.0):.6f}")
+        tbl.add_row("Total tokens", f"{total_tokens:,}")
+        self._console.print(tbl)
+        return CommandResult(handled=True)
+
+    def _cmd_sessions(self) -> CommandResult:
+        """List recent sessions with ID, start time, turns, cost, status."""
+        try:
+            rows = self._db.execute_all(
+                "SELECT session_id, created_at, updated_at, turn_count, cost_usd, status "
+                "FROM sessions ORDER BY updated_at DESC LIMIT 20"
+            )
+        except Exception as exc:  # noqa: BLE001
+            return CommandResult(handled=True, output=f"[red]Could not load sessions: {exc}[/red]")
+
+        if not rows:
+            return CommandResult(handled=True, output="[dim]No sessions found.[/dim]")
+
+        tbl = Table(
+            title="gdm sessions",
+            header_style="bold cyan",
+            show_lines=False,
+        )
+        tbl.add_column("#", style="dim", no_wrap=True)
+        tbl.add_column("Session ID", no_wrap=True)
+        tbl.add_column("Started", no_wrap=True)
+        tbl.add_column("Turns", justify="right")
+        tbl.add_column("Cost", justify="right")
+        tbl.add_column("Status")
+
+        now = datetime.now(timezone.utc)
+        for i, row in enumerate(rows, 1):
+            sid = row["session_id"]
+            short_id = sid[:8] + "..."
+            started = _relative_time(row["created_at"], now)
+            turns = str(row["turn_count"] or 0)
+            cost = f"${(row['cost_usd'] or 0.0):.4f}"
+            status = row["status"] or "active"
+            status_style = (
+                "[green]active ← resumable[/green]" if status == "active"
+                else f"[dim]{status}[/dim]"
+            )
+            tbl.add_row(str(i), short_id, started, turns, cost, status_style)
+
+        self._console.print(tbl)
+        return CommandResult(handled=True)
+
+    def _cmd_resume(self, session_id: str | None = None) -> CommandResult:
+        """Signal the REPL to restore a session transcript from checkpoint.
+
+        With no args, resumes the most recent active session.
+        With a session_id arg, resumes that specific session.
+        """
+        if session_id:
+            # Validate the session exists before committing to restore
+            try:
+                row = self._db.execute_one(
+                    "SELECT session_id FROM sessions WHERE session_id = ?",
+                    (session_id,),
+                )
+                if not row:
+                    # Try prefix match
+                    rows = self._db.execute_all(
+                        "SELECT session_id FROM sessions WHERE session_id LIKE ? LIMIT 2",
+                        (session_id + "%",),
+                    )
+                    if not rows:
+                        return CommandResult(
+                            handled=True,
+                            output=f"[red]Session {session_id!r} not found.[/red]",
+                        )
+                    if len(rows) > 1:
+                        return CommandResult(
+                            handled=True,
+                            output=f"[red]Ambiguous prefix {session_id!r} — matches multiple sessions. Use more characters.[/red]",
+                        )
+                    session_id = rows[0]["session_id"]
+            except Exception as exc:  # noqa: BLE001
+                return CommandResult(
+                    handled=True,
+                    output=f"[red]Could not look up session: {exc}[/red]",
+                )
+            return CommandResult(
+                handled=True,
+                force_resume=True,
+                resume_session_id=session_id,
+                output=f"[cyan]Restoring session {session_id[:8]}...[/cyan]",
+            )
+
+        # No session_id — find most recent active session
+        try:
+            sessions = self._db.list_incomplete_sessions(limit=1)
+        except Exception as exc:  # noqa: BLE001
+            sessions = []
+            log.warning("list_incomplete_sessions failed: %s", exc)
+
+        if not sessions:
+            return CommandResult(
+                handled=True,
+                output="[yellow]No active sessions found. Start a new conversation.[/yellow]",
+            )
+        target = sessions[0]["session_id"]
+        return CommandResult(
+            handled=True,
+            force_resume=True,
+            resume_session_id=target,
+            output=f"[cyan]Restoring session {target[:8]}...[/cyan]",
+        )
+
+    # ------------------------------------------------------------------
+    # Git commands
+    # ------------------------------------------------------------------
+
+    def _git_run(self, args: list[str]) -> tuple[int, str]:
+        """Run a git command in project_root. Returns (returncode, output)."""
+        try:
+            result = subprocess.run(
+                ["git"] + args,
+                cwd=str(self._project_root),
+                capture_output=True,
+                text=True,
+                timeout=15,
+            )
+            output = (result.stdout + result.stderr).strip()
+            return result.returncode, output
+        except FileNotFoundError:
+            return -1, "git not found in PATH"
+        except subprocess.TimeoutExpired:
+            return 1, "git command timed out"
+        except Exception as exc:  # noqa: BLE001
+            return 1, str(exc)
+
+    def _cmd_diff(self) -> CommandResult:
+        """Show git diff of staged + unstaged changes."""
+        rc, out = self._git_run(["diff", "HEAD"])
+        if rc == -1:
+            return CommandResult(handled=True, output=f"[red]{out}[/red]")
+        if not out:
+            rc2, stat = self._git_run(["status", "--short"])
+            if not stat:
+                return CommandResult(handled=True, output="[dim]No changes since last commit.[/dim]")
+            out = stat
+        # Truncate long diffs
+        if len(out) > 4000:
+            out = out[:4000] + "\n…(truncated)"
+        return CommandResult(handled=True, output=f"[dim]{out}[/dim]")
+
+    def _cmd_undo(self, n: int = 1) -> CommandResult:
+        """Soft-undo the last *n* [gdm-checkpoint] commits (keeps working tree).
+
+        Only operates on commits tagged [gdm-checkpoint] so it never undoes
+        user commits or moves HEAD past non-gdm history.
+        """
+        if n < 1:
+            n = 1
+        # Find the most recent N gdm-checkpoint commit SHAs
+        # --fixed-strings avoids BRE treating [...] as a character class
+        rc, log_out = self._git_run(
+            ["log", "--oneline", "--fixed-strings", "--grep=[gdm-checkpoint]", f"-{n}"]
+        )
+        if rc == -1:
+            return CommandResult(handled=True, output=f"[red]{log_out}[/red]")
+        if rc != 0 or not log_out.strip():
+            return CommandResult(
+                handled=True,
+                output="[yellow]No gdm checkpoint commits found. Nothing to undo.[/yellow]",
+            )
+        lines = [ln for ln in log_out.strip().splitlines() if ln]
+        if len(lines) < n:
+            return CommandResult(
+                handled=True,
+                output=f"[yellow]Only {len(lines)} checkpoint(s) found; cannot undo {n}.[/yellow]",
+            )
+        # Oldest among the N checkpoints is the last line; reset to its parent
+        oldest_sha = lines[-1].split()[0]
+        rc2, out2 = self._git_run(["reset", "--soft", f"{oldest_sha}~1"])
+        if rc2 != 0:
+            return CommandResult(handled=True, output=f"[red]undo failed:[/red] {out2[:300]}")
+        return CommandResult(
+            handled=True,
+            output=(
+                f"[green]✓ Undid {n} checkpoint commit(s).[/green] "
+                "Changes preserved in working tree."
+            ),
+        )
+
+    def _cmd_rollback(self, checkpoint_id: str | None = None) -> CommandResult:
+        """Hard rollback. Without arg: pre-task state. With arg: named checkpoint SHA."""
+        # Safety gate: refuse if working tree is dirty
+        wf = GitWorkflow(self._project_root)
+        if not wf.is_clean():
+            return CommandResult(
+                handled=True,
+                output=(
+                    "[red]⚠ Uncommitted changes detected. "
+                    "Commit ([bold]/commit[/bold]) or stash before rollback.[/red]"
+                ),
+            )
+
+        if checkpoint_id:
+            # Validate the SHA exists
+            rc_v, _ = self._git_run(["cat-file", "-t", checkpoint_id])
+            if rc_v != 0:
+                return CommandResult(
+                    handled=True,
+                    output=f"[red]Unknown checkpoint: {checkpoint_id!r}[/red]",
+                )
+            target_ref = checkpoint_id
+            description = f"checkpoint {checkpoint_id[:8]}"
+        else:
+            # Existing logic: find parent of first gdm-checkpoint commit
+            rc, log_out = self._git_run(
+                ["log", "--oneline", "--fixed-strings", "--grep=[gdm-checkpoint]", "--reverse"]
+            )
+            if rc == -1:
+                return CommandResult(handled=True, output=f"[red]{log_out}[/red]")
+            if rc != 0 or not log_out.strip():
+                return CommandResult(
+                    handled=True,
+                    output="[yellow]No gdm checkpoints found. Nothing to roll back to.[/yellow]",
+                )
+            first_sha = log_out.strip().splitlines()[0].split()[0]
+            target_ref = f"{first_sha}~1"
+            rc_p, pre_sha = self._git_run(["rev-parse", "--short", target_ref])
+            if rc_p != 0:
+                return CommandResult(
+                    handled=True,
+                    output=f"[red]Cannot find pre-task commit (is this the first commit?)[/red] {pre_sha}",
+                )
+            description = f"pre-task state ({pre_sha.strip()})"
+
+        # Confirmation prompt before destructive hard reset
+        self._console.print(
+            f"[bold red]⚠ Hard rollback[/bold red] to {description}.\n"
+            "[red]This DISCARDS all uncommitted and committed changes since that point.[/red]\n"
+            "Type [bold]YES[/bold] to confirm, anything else to cancel: ",
+            end="",
+        )
+        try:
+            confirm = (self._confirm_fn() if self._confirm_fn is not None else input()).strip()
+        except (EOFError, KeyboardInterrupt):
+            confirm = ""
+        if confirm != "YES":
+            return CommandResult(handled=True, output="[dim]Rollback cancelled.[/dim]")
+
+        rc2, out2 = self._git_run(["reset", "--hard", target_ref])
+        if rc2 != 0:
+            return CommandResult(handled=True, output=f"[red]rollback failed:[/red] {out2[:300]}")
+        return CommandResult(
+            handled=True,
+            output=f"[green]✓ Rolled back to {description}.[/green] All subsequent changes discarded.",
+        )
+
+    def _cmd_branch(self) -> CommandResult:
+        """Show current branch and gdm checkpoint history."""
+        rc1, branch = self._git_run(["branch", "--show-current"])
+        rc2, log_out = self._git_run(["log", "--oneline", "-10"])
+        tbl = Table(title="git branch", show_header=False, min_width=50)
+        tbl.add_column("Field", style="dim")
+        tbl.add_column("Value")
+        tbl.add_row("Branch", branch or "(unknown)")
+        tbl.add_row("Recent commits", log_out[:500] if log_out else "(no commits)")
+        self._console.print(tbl)
+        return CommandResult(handled=True)
+
+    def _cmd_pr(self) -> CommandResult:
+        """Push the current branch and generate a model-written PR description."""
+        rc1, branch = self._git_run(["branch", "--show-current"])
+        if not branch or not branch.startswith("gdm/"):
+            return CommandResult(
+                handled=True,
+                output="[yellow]Not on a gdm task branch. Run a task first.[/yellow]",
+            )
+        rc2, out2 = self._git_run(["push", "-u", "origin", branch])
+        if rc2 not in (0, 1):
+            return CommandResult(handled=True, output=f"[red]push failed:[/red] {out2[:400]}")
+
+        rc3, log_out = self._git_run(["log", "--oneline", f"origin/HEAD...{branch}"])
+        commit_log = log_out[:800] if log_out else "(no commits ahead of origin)"
+
+        rc4, diff_text = self._git_run(["diff", f"origin/HEAD...{branch}"])
+        description = self._generate_pr_description(branch, diff_text or "", commit_log)
+
+        # Copy to clipboard if pyperclip is available (soft dependency)
+        try:
+            import pyperclip  # type: ignore[import-untyped]
+            pyperclip.copy(description)
+            clipboard_note = "\n[dim]✓ PR description copied to clipboard.[/dim]"
+        except (ImportError, Exception):  # noqa: BLE001
+            clipboard_note = ""
+
+        msg = (
+            f"[green]✓ Pushed[/green] [cyan]{branch}[/cyan]\n\n"
+            f"{description}"
+            f"{clipboard_note}"
+        )
+        return CommandResult(handled=True, output=msg)
+
+    def _generate_pr_description(
+        self, branch: str, diff_text: str, commit_log: str
+    ) -> str:
+        """Call the Coder model to generate a structured PR description.
+
+        Prompt asks for ## Summary, ## Changes, ## Testing, ## Notes sections.
+        Falls back to the raw commit log on any exception.
+        """
+        if not self._cfg:
+            return f"Commits:\n{commit_log}\n\n[dim]Open a PR at your git hosting provider.[/dim]"
+
+        try:
+            from src.models.client import GdmClient
+            from src.models.definitions import ModelTier, get_model
+
+            model_def = get_model(ModelTier.CODER, getattr(self._cfg, "provider", "grok"))
+            model_id = model_def.id
+            client = GdmClient(self._cfg)  # type: ignore[arg-type]
+
+            prompt = (
+                "You are writing a GitHub pull request description.\n"
+                f"Branch: {branch}\n"
+                f"Commits:\n{commit_log}\n\n"
+                f"Diff summary (first 4000 chars):\n{diff_text[:4000]}\n\n"
+                "Write a PR description with these sections:\n"
+                "## Summary (2-3 sentences)\n"
+                "## Changes\n"
+                "## Testing\n"
+                "## Notes (optional)\n"
+                "Be precise and factual. Do not invent changes not in the diff."
+            )
+            response = client.complete(
+                messages=[{"role": "user", "content": prompt}],
+                model=model_id,
+                max_tokens=600,
+                temperature=0.2,
+            )
+            return response.choices[0].message.content.strip()
+        except Exception as exc:  # noqa: BLE001
+            log.warning("_generate_pr_description failed: %s", exc)
+            return f"Commits:\n{commit_log}\n\n[dim]Open a PR at your git hosting provider.[/dim]"
+
+    def _cmd_commit(self, args: list[str]) -> CommandResult:
+        """Create a manual checkpoint commit."""
+        msg = " ".join(args).strip() or "manual checkpoint"
+        rc1, _ = self._git_run(["add", "-A"])
+        rc2, out2 = self._git_run(["commit", "--allow-empty", "-m", f"[gdm-checkpoint] {msg}"])
+        if rc2 != 0:
+            return CommandResult(handled=True, output=f"[red]commit failed:[/red] {out2[:400]}")
+        rc3, sha = self._git_run(["rev-parse", "--short", "HEAD"])
+        return CommandResult(
+            handled=True,
+            output=f"[green]✓ Checkpoint commit {sha}:[/green] {msg}",
+        )
+
+    def _cmd_browser(self, args: list[str]) -> CommandResult:
+        """Manage the gdm bridge server for browser automation."""
+        import os
+        import platform
+        import subprocess
+        import sys
+
+        action = args[0].lower() if args else "status"
+        pid_file = self._project_root / ".gdm_bridge.pid"
+
+        match action:
+            case "start":
+                if pid_file.exists():
+                    try:
+                        pid = int(pid_file.read_text().strip())
+                        # Check if process is alive
+                        if platform.system() == "Windows":
+                            r = subprocess.run(
+                                ["tasklist", "/FI", f"PID eq {pid}", "/NH"],
+                                capture_output=True, text=True,
+                            )
+                            alive = str(pid) in r.stdout
+                        else:
+                            try:
+                                os.kill(pid, 0)
+                                alive = True
+                            except ProcessLookupError:
+                                alive = False
+                        if alive:
+                            return CommandResult(
+                                handled=True,
+                                output=f"[yellow]Bridge already running (PID {pid}).[/yellow]",
+                            )
+                    except Exception:  # noqa: BLE001
+                        pass
+
+                proc = subprocess.Popen(
+                    [sys.executable, "-m", "src.server.bridge_cli"],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                )
+                pid_file.write_text(str(proc.pid))
+                return CommandResult(
+                    handled=True,
+                    output=(
+                        f"[green]✓ Bridge server started (PID {proc.pid})[/green]\n"
+                        f"[dim]Load the gdm-chrome extension to connect. "
+                        f"Token at: ~/.config/gdm/browser.token[/dim]"
+                    ),
+                )
+
+            case "stop":
+                if not pid_file.exists():
+                    return CommandResult(handled=True, output="[yellow]Bridge not running.[/yellow]")
+                try:
+                    pid = int(pid_file.read_text().strip())
+                    if platform.system() == "Windows":
+                        subprocess.run(["taskkill", "/F", "/PID", str(pid)], capture_output=True)
+                    else:
+                        os.kill(pid, 15)  # SIGTERM
+                    pid_file.unlink(missing_ok=True)
+                    return CommandResult(
+                        handled=True,
+                        output=f"[green]✓ Bridge stopped (PID {pid}).[/green]",
+                    )
+                except Exception as exc:  # noqa: BLE001
+                    pid_file.unlink(missing_ok=True)
+                    return CommandResult(handled=True, output=f"[red]Stop failed:[/red] {exc}")
+
+            case "status":
+                if not pid_file.exists():
+                    return CommandResult(
+                        handled=True,
+                        output="[dim]Bridge not running. Use /browser start to launch it.[/dim]",
+                    )
+                try:
+                    pid = int(pid_file.read_text().strip())
+                    try:
+                        import httpx
+                        r = httpx.get("http://127.0.0.1:9321/health", timeout=2.0)
+                        data = r.json()
+                        clients = data.get("clients", {})
+                        queue = data.get("queue_depth", 0)
+                        return CommandResult(
+                            handled=True,
+                            output=(
+                                f"[green]✓ Bridge running[/green] (PID {pid})\n"
+                                f"  CLI clients: {clients.get('cli', 0)}  "
+                                f"Extension clients: {clients.get('extension', 0)}  "
+                                f"Queue depth: {queue}"
+                            ),
+                        )
+                    except Exception:  # noqa: BLE001
+                        return CommandResult(
+                            handled=True,
+                            output=f"[yellow]Bridge process running (PID {pid}) but health check failed.[/yellow]",
+                        )
+                except Exception as exc:  # noqa: BLE001
+                    return CommandResult(handled=True, output=f"[red]Status check failed:[/red] {exc}")
+
+            case _:
+                return CommandResult(
+                    handled=True,
+                    output="[yellow]Usage: /browser [start|stop|status][/yellow]",
+                )
+
+    def _cmd_remote(self, args: list[str]) -> CommandResult:
+        """Manage the gdm remote tunnel.
+
+        Usage:
+          /remote start [--port PORT]  - start tunnel, print URL and QR
+          /remote stop                 - tear down tunnel
+          /remote status               - show tunnel state
+          /remote qr                   - display QR code for active tunnel
+        """
+        import json
+        from pathlib import Path as _Path
+
+        action = (args[0] if args else "status").lower()
+        state_file = _Path.cwd() / ".gdm_remote.json"
+
+        match action:
+            case "start":
+                port = 8765
+                for i, a in enumerate(args[1:]):
+                    if a in ("--port", "-p") and i + 1 < len(args) - 1:
+                        try:
+                            port = int(args[i + 2])
+                        except ValueError:
+                            pass
+                try:
+                    from src.remote.tunnel import TunnelManager
+                    from src.remote.qr import make_pairing_url, render_qr
+                    from src.remote.token_manager import PairingTokenService
+
+                    mgr = TunnelManager(port=port)
+                    url = mgr.start()
+                    token_svc = PairingTokenService()
+                    token = token_svc.issue()
+                    pairing_url = make_pairing_url(url, token)
+                    st = mgr.status()
+                    state_file.write_text(
+                        json.dumps({
+                            "url": url,
+                            "pairing_url": pairing_url,
+                            "provider": st["provider"],
+                            "port": port,
+                        }),
+                        encoding="utf-8",
+                    )
+                    qr_text = render_qr(pairing_url)
+                    lines = [
+                        f"[green]Tunnel started:[/green] [cyan]{url}[/cyan]",
+                        f"  Provider: [bold]{st['provider']}[/bold]",
+                        "",
+                        qr_text,
+                        f"\n[dim]Pairing URL: {pairing_url}[/dim]",
+                    ]
+                    mgr.stop()
+                    return CommandResult(handled=True, output="\n".join(lines))
+                except Exception as exc:  # noqa: BLE001
+                    return CommandResult(handled=True, output=f"[red]Remote start failed:[/red] {exc}")
+
+            case "stop":
+                if not state_file.exists():
+                    return CommandResult(handled=True, output="[yellow]Remote tunnel not running.[/yellow]")
+                state_file.unlink(missing_ok=True)
+                return CommandResult(handled=True, output="[green]Remote tunnel stopped.[/green]")
+
+            case "status":
+                if not state_file.exists():
+                    return CommandResult(
+                        handled=True,
+                        output="[dim]Remote tunnel not running. Run: /remote start[/dim]",
+                    )
+                try:
+                    data = json.loads(state_file.read_text(encoding="utf-8"))
+                    url = data.get("url", "unknown")
+                    provider = data.get("provider", "unknown")
+                    return CommandResult(
+                        handled=True,
+                        output=(
+                            f"[green]Remote tunnel active[/green]\n"
+                            f"  URL: [cyan]{url}[/cyan]\n"
+                            f"  Provider: [bold]{provider}[/bold]"
+                        ),
+                    )
+                except Exception as exc:  # noqa: BLE001
+                    return CommandResult(
+                        handled=True, output=f"[yellow]Could not read tunnel state:[/yellow] {exc}"
+                    )
+
+            case "qr":
+                if not state_file.exists():
+                    return CommandResult(
+                        handled=True, output="[yellow]No active tunnel. Run: /remote start[/yellow]"
+                    )
+                try:
+                    from src.remote.qr import render_qr
+
+                    data = json.loads(state_file.read_text(encoding="utf-8"))
+                    pairing_url = data.get("pairing_url") or data.get("url", "")
+                    if not pairing_url:
+                        return CommandResult(handled=True, output="[red]No URL found in tunnel state.[/red]")
+                    qr_text = render_qr(pairing_url)
+                    return CommandResult(handled=True, output=f"{qr_text}\n[dim]{pairing_url}[/dim]")
+                except Exception as exc:  # noqa: BLE001
+                    return CommandResult(handled=True, output=f"[red]QR render failed:[/red] {exc}")
+
+            case _:
+                return CommandResult(
+                    handled=True,
+                    output="[yellow]Usage: /remote [start|stop|status|qr][/yellow]",
+                )
+
+    def _cmd_replay(self, args: list[str]) -> CommandResult:
+        """Replay, compare, fork, or export past sessions.
+
+        Usage:
+          /replay {session_id}                        — interactive step-through
+          /replay {session_id} --json                 — machine-readable summary
+          /replay compare {id1} {id2}                 — divergence summary
+          /replay fork {session_id} {turn_index}      — fork from turn N
+          /replay export {session_id} [--format fmt]  — export (openai|anthropic|raw)
+        """
+        from src.runtime.replay import ReplayError, SessionReplay
+
+        if not args:
+            return CommandResult(
+                handled=True,
+                output="[yellow]Usage: /replay {session_id} | compare {id1} {id2} | "
+                       "fork {id} {n} | export {id} [--format openai|anthropic|raw][/yellow]",
+            )
+
+        # handle() splits the input with maxsplit=2 so later tokens may be merged;
+        # re-split to get individual tokens.
+        args_flat: list[str] = []
+        for a in args:
+            args_flat.extend(a.split())
+        args = args_flat
+
+        sub = args[0].lower()
+
+        # --- /replay compare {id1} {id2} ---
+        if sub == "compare":
+            if len(args) < 3:
+                return CommandResult(
+                    handled=True,
+                    output="[yellow]Usage: /replay compare {session_id_a} {session_id_b}[/yellow]",
+                )
+            id_a, id_b = args[1], args[2]
+            try:
+                replay_a = SessionReplay(self._db, id_a)
+                replay_a.load_session()
+                diff = replay_a.compare(id_b)
+                summary = diff.divergence_summary()
+                lines = [
+                    f"[bold]Session A:[/bold] {id_a}  ({len(diff.frames_a)} turns, ${summary['cost_a_usd']:.6f})",
+                    f"[bold]Session B:[/bold] {id_b}  ({len(diff.frames_b)} turns, ${summary['cost_b_usd']:.6f})",
+                    f"[bold]Common prefix:[/bold] {summary['common_turns']} turns",
+                    f"[bold]Unique to A:[/bold] {summary['session_a_unique_turns']} turns",
+                    f"[bold]Unique to B:[/bold] {summary['session_b_unique_turns']} turns",
+                ]
+                return CommandResult(handled=True, output="\n".join(lines))
+            except ReplayError as exc:
+                return CommandResult(handled=True, output=f"[red]Replay error:[/red] {exc}")
+            except Exception as exc:  # noqa: BLE001
+                return CommandResult(handled=True, output=f"[red]Error:[/red] {exc}")
+
+        # --- /replay fork {session_id} {turn_index} ---
+        if sub == "fork":
+            if len(args) < 3:
+                return CommandResult(
+                    handled=True,
+                    output="[yellow]Usage: /replay fork {session_id} {turn_index}[/yellow]",
+                )
+            session_id, turn_str = args[1], args[2]
+            try:
+                turn_n = int(turn_str)
+            except ValueError:
+                return CommandResult(
+                    handled=True, output=f"[red]turn_index must be an integer, got {turn_str!r}[/red]"
+                )
+            try:
+                import uuid as _uuid
+                new_sid = str(_uuid.uuid4())
+                replay = SessionReplay(self._db, session_id)
+                replay.load_session()
+                replay.fork_from(turn_n, new_sid)
+                return CommandResult(
+                    handled=True,
+                    output=(
+                        f"[green]✓ Forked session {session_id[:8]}… at turn {turn_n}[/green]\n"
+                        f"New session: [cyan]{new_sid}[/cyan]"
+                    ),
+                )
+            except ReplayError as exc:
+                return CommandResult(handled=True, output=f"[red]Replay error:[/red] {exc}")
+            except Exception as exc:  # noqa: BLE001
+                return CommandResult(handled=True, output=f"[red]Error:[/red] {exc}")
+
+        # --- /replay export {session_id} [--format fmt] ---
+        if sub == "export":
+            if len(args) < 2:
+                return CommandResult(
+                    handled=True,
+                    output="[yellow]Usage: /replay export {session_id} [--format openai|anthropic|raw][/yellow]",
+                )
+            session_id = args[1]
+            fmt = "openai"
+            if "--format" in args:
+                idx = args.index("--format")
+                if idx + 1 < len(args):
+                    fmt = args[idx + 1]
+            try:
+                replay = SessionReplay(self._db, session_id)
+                replay.load_session()
+                records = replay.export(fmt)
+                import json as _json
+                lines_out = "\n".join(_json.dumps(r) for r in records)
+                return CommandResult(
+                    handled=True,
+                    output=f"[green]{len(records)} records exported ({fmt}):[/green]\n{lines_out[:2000]}",
+                )
+            except (ReplayError, ValueError) as exc:
+                return CommandResult(handled=True, output=f"[red]Export error:[/red] {exc}")
+            except Exception as exc:  # noqa: BLE001
+                return CommandResult(handled=True, output=f"[red]Error:[/red] {exc}")
+
+        # --- /replay {session_id} [--json] --- (default: interactive display)
+        session_id = args[0]
+        as_json = "--json" in args
+        try:
+            replay = SessionReplay(self._db, session_id)
+            replay.load_session()
+        except ReplayError as exc:
+            return CommandResult(handled=True, output=f"[red]Replay error:[/red] {exc}")
+        except Exception as exc:  # noqa: BLE001
+            return CommandResult(handled=True, output=f"[red]Error loading session:[/red] {exc}")
+
+        if as_json:
+            import json as _json
+            records = replay.export("raw")
+            return CommandResult(handled=True, output=_json.dumps(records, indent=2)[:4000])
+
+        # Non-blocking textual display: show all frames, then navigation hint
+        lines = [f"[bold]Session {session_id[:8]}…[/bold] — {replay.turn_count} turn(s)\n"]
+        for frame in replay._frames:
+            lines.append(
+                f"[cyan]Turn {frame.turn_index}[/cyan]  "
+                f"[dim]{frame.model}  ${frame.cost_usd:.6f}[/dim]"
+            )
+            if frame.user_message:
+                snippet = frame.user_message[:120].replace("\n", " ")
+                lines.append(f"  User: {snippet}")
+            if frame.assistant_text:
+                snippet = frame.assistant_text[:120].replace("\n", " ")
+                lines.append(f"  Asst: {snippet}")
+            if frame.tool_calls:
+                names = ", ".join(tc.get("tool_name", "?") for tc in frame.tool_calls)
+                lines.append(f"  Tools: {names}")
+            if frame.annotation:
+                lines.append(f"  [yellow]Annotation: {frame.annotation}[/yellow]")
+            lines.append("")
+
+        lines.append(
+            "[dim]Tip: /replay compare {id1} {id2}  |  /replay fork {id} {n}  |  "
+            "/replay export {id} --format openai[/dim]"
+        )
+        return CommandResult(handled=True, output="\n".join(lines))
+
+    def _cmd_doctor(self) -> CommandResult:
+        """Show resolved model IDs for all providers and tiers."""
+        from src.models.definitions import (
+            _CODEX_BY_TIER,
+            _GEMINI_BY_TIER,
+            _GROK_BY_TIER,
+        )
+
+        tbl = Table(title="Resolved Model IDs", header_style="bold cyan", show_lines=True)
+        tbl.add_column("Provider", style="bold")
+        tbl.add_column("Tier")
+        tbl.add_column("Model ID")
+        tbl.add_column("Context (K)")
+        tbl.add_column("$/1M in")
+        tbl.add_column("$/1M out")
+
+        for provider_label, tier_map in (
+            ("grok", _GROK_BY_TIER),
+            ("gemini", _GEMINI_BY_TIER),
+            ("codex", _CODEX_BY_TIER),
+        ):
+            for tier_name, model_def in sorted(tier_map.items()):
+                tbl.add_row(
+                    provider_label,
+                    tier_name,
+                    model_def.id,
+                    str(model_def.context_window // 1000),
+                    f"{model_def.input_per_m:.4f}",
+                    f"{model_def.output_per_m:.4f}",
+                )
+        self._console.print(tbl)
+        return CommandResult(handled=True)
+
+    def _cmd_reasoning(self, args: list[str]) -> CommandResult:
+        """Show or set the per-turn reasoning mode.
+
+        Usage:
+          /reasoning          — show current mode
+          /reasoning on       — force Reasoner tier every turn
+          /reasoning off      — force Scout tier every turn
+          /reasoning auto     — use the deterministic scoring classifier
+        """
+        _VALID_MODES: frozenset[str] = frozenset({"on", "off", "auto"})
+        if not args:
+            return CommandResult(
+                handled=True,
+                output=(
+                    f"[cyan]Reasoning mode:[/cyan] [bold]{self._reasoning_mode}[/bold]\n"
+                    "[dim]Use /reasoning on|off|auto to change.[/dim]"
+                ),
+            )
+        mode = args[0].lower().strip()
+        if mode not in _VALID_MODES:
+            return CommandResult(
+                handled=True,
+                output=f"[yellow]Unknown mode {mode!r}. Valid: on | off | auto[/yellow]",
+            )
+        self._reasoning_mode = mode
+        _DESCRIPTIONS = {
+            "on": "Force [bold]Reasoner[/bold] tier — highest quality, highest cost",
+            "off": "Force [bold]Scout[/bold] tier — cheapest, fastest",
+            "auto": "Use [bold]auto-classifier[/bold] — selects tier per turn by score",
+        }
+        return CommandResult(
+            handled=True,
+            new_reasoning_mode=mode,
+            output=f"[green]✓ Reasoning mode → {mode}[/green]  {_DESCRIPTIONS[mode]}",
+        )
+
+    # ------------------------------------------------------------------
+    # /artifacts and /save
+    # ------------------------------------------------------------------
+
+    def _cmd_artifacts(self, args: list[str]) -> CommandResult:
+        """Handle /artifacts [sub] [args]."""
+        from src.artifacts.artifact_store import ArtifactNotFoundError, ArtifactStore
+        store = ArtifactStore(self._db)
+
+        sub = args[0].lower() if args else ""
+        rest = args[1].split() if len(args) > 1 else []
+
+        if sub == "view":
+            name_or_id = rest[0] if rest else ""
+            if not name_or_id:
+                return CommandResult(handled=True, output="[red]Usage: /artifacts view {name|id}[/red]")
+            try:
+                art = store.get(name_or_id)
+            except ArtifactNotFoundError as exc:
+                return CommandResult(handled=True, output=f"[red]{exc}[/red]")
+            header = (
+                f"[bold]{art.name}[/bold]  [dim]{art.type}  v{art.version_num}  {art.updated_at[:16]}[/dim]\n"
+            )
+            return CommandResult(handled=True, output=header + art.content)
+
+        if sub == "diff":
+            ids = args[1].split() if len(args) > 1 else []
+            if len(ids) < 2:
+                return CommandResult(handled=True, output="[red]Usage: /artifacts diff {name1} {name2}[/red]")
+            try:
+                diff = store.diff(ids[0], ids[1])
+            except ArtifactNotFoundError as exc:
+                return CommandResult(handled=True, output=f"[red]{exc}[/red]")
+            except TypeError as exc:
+                return CommandResult(handled=True, output=f"[red]{exc}[/red]")
+            if not diff.unified_diff:
+                return CommandResult(handled=True, output="[dim]No differences.[/dim]")
+            return CommandResult(handled=True, output=diff.unified_diff)
+
+        if sub == "search":
+            query = " ".join(rest) if rest else (args[1] if len(args) > 1 else "")
+            if not query:
+                return CommandResult(handled=True, output="[red]Usage: /artifacts search {query}[/red]")
+            results = store.search(query)
+            if not results:
+                return CommandResult(handled=True, output=f"[dim]No artifacts matching {query!r}.[/dim]")
+            tbl = Table(title=f"Search: {query}", header_style="bold cyan")
+            tbl.add_column("Name", style="cyan")
+            tbl.add_column("Type")
+            tbl.add_column("v#")
+            tbl.add_column("Updated")
+            for art in results:
+                tbl.add_row(art.name, art.type, str(art.version_num), art.updated_at[:16])
+            self._console.print(tbl)
+            return CommandResult(handled=True)
+
+        if sub == "export":
+            export_args = args[1].split() if len(args) > 1 else []
+            if not export_args:
+                return CommandResult(handled=True, output="[red]Usage: /artifacts export {name|id} [--format raw|html][/red]")
+            name_or_id = export_args[0]
+            fmt = "raw"
+            if "--format" in export_args:
+                idx = export_args.index("--format")
+                if idx + 1 < len(export_args):
+                    fmt = export_args[idx + 1]
+            try:
+                content = store.export(name_or_id, fmt=fmt)
+            except ArtifactNotFoundError as exc:
+                return CommandResult(handled=True, output=f"[red]{exc}[/red]")
+            except ValueError as exc:
+                return CommandResult(handled=True, output=f"[red]{exc}[/red]")
+            return CommandResult(handled=True, output=content)
+
+        # Default: list all artifacts
+        artifacts = store.list()
+        if not artifacts:
+            return CommandResult(handled=True, output="[dim]No artifacts saved yet. Use /save [name] to save one.[/dim]")
+        tbl = Table(title="Saved Artifacts", header_style="bold cyan", show_lines=False)
+        tbl.add_column("Name", style="cyan", no_wrap=True)
+        tbl.add_column("Type")
+        tbl.add_column("Ver")
+        tbl.add_column("Session", style="dim")
+        tbl.add_column("Updated")
+        for art in artifacts:
+            session_abbrev = (art.session_id or "")[:8]
+            tbl.add_row(art.name, art.type, str(art.version_num), session_abbrev, art.updated_at[:16])
+        self._console.print(tbl)
+        return CommandResult(handled=True)
+
+    def _cmd_save(self, name_arg: str) -> CommandResult:
+        """Handle /save [name] — signals loop to save last assistant response."""
+        name = name_arg.strip() or "unnamed"
+        return CommandResult(
+            handled=True,
+            save_artifact_name=name,
+            output=f"[dim]Saving last response as artifact [cyan]{name!r}[/cyan]...[/dim]",
+        )
+
+    def _cmd_proxy(self, args: list[str]) -> CommandResult:
+        """Handle /proxy [on|off|url <url>|token <tok>|status]."""
+        from src.auth import CredentialStore
+        from src.models.definitions import PROXY_DEFAULT_URL
+
+        sub = args[0].lower() if args else "status"
+
+        if sub == "on":
+            if not self._proxy_token:
+                return CommandResult(
+                    handled=True,
+                    output=(
+                        "[red]No proxy token stored. Set one first:[/red]\n"
+                        "  /proxy token <your-token>"
+                    ),
+                )
+            if not self._proxy_url:
+                self._proxy_url = PROXY_DEFAULT_URL
+            self._proxy_enabled = True
+            return CommandResult(
+                handled=True,
+                output=f"[green]Proxy enabled:[/green] [cyan]{self._proxy_url}[/cyan]",
+                proxy_action="enable",
+                proxy_url=self._proxy_url,
+                proxy_token=self._proxy_token,
+            )
+
+        if sub == "off":
+            self._proxy_enabled = False
+            return CommandResult(
+                handled=True,
+                output="[yellow]Proxy disabled.[/yellow] Calls go directly to provider.",
+                proxy_action="disable",
+            )
+
+        if sub == "url":
+            if len(args) < 2:
+                return CommandResult(
+                    handled=True,
+                    output="[red]Usage:[/red] /proxy url <https://your-proxy/v1>",
+                )
+            url = args[1]
+            _parsed = urlparse(url)
+            _loopback = (
+                _parsed.scheme == "http"
+                and _parsed.hostname in ("localhost", "127.0.0.1", "::1")
+                and not _parsed.username  # reject http://localhost@evil.com/
+            )
+            if _parsed.scheme != "https" and not _loopback:
+                return CommandResult(
+                    handled=True,
+                    output=(
+                        "[red]Proxy URL must use HTTPS to protect your token in transit.[/red]\n"
+                        "Exception: http://localhost (exact loopback) is allowed for local testing."
+                    ),
+                )
+            self._proxy_url = url
+            return CommandResult(
+                handled=True,
+                output=f"Proxy URL set to [cyan]{url}[/cyan]. Run [cyan]/proxy on[/cyan] to activate.",
+            )
+
+        if sub == "token":
+            if len(args) < 2:
+                # Prompt for token via hidden input (never stored in history)
+                return CommandResult(
+                    handled=True,
+                    prompt_secret="Proxy token: ",
+                )
+            token = args[1]
+            self._proxy_token = token
+            try:
+                CredentialStore().set("proxy", token)
+                masked = "****" + token[-4:] if len(token) >= 4 else "****"
+                return CommandResult(
+                    handled=True,
+                    output=f"Proxy token saved to OS keychain ([cyan]{masked}[/cyan]).",
+                )
+            except Exception as exc:
+                log.warning("Could not save proxy token to keychain: %s", exc)
+                masked = "****" + token[-4:] if len(token) >= 4 else "****"
+                return CommandResult(
+                    handled=True,
+                    output=(
+                        f"Proxy token set for this session ([cyan]{masked}[/cyan]). "
+                        "[yellow]Keychain save failed — token will not persist.[/yellow]"
+                    ),
+                )
+
+        # /proxy status (default)
+        status = "[green]enabled[/green]" if self._proxy_enabled else "[dim]disabled[/dim]"
+        url = self._proxy_url or PROXY_DEFAULT_URL
+        masked = ("****" + self._proxy_token[-4:]) if len(self._proxy_token) >= 4 else ("[dim]not set[/dim]" if not self._proxy_token else "****")
+        lines = [
+            f"  Status: {status}",
+            f"  URL:    [cyan]{url}[/cyan]",
+            f"  Token:  {masked}",
+            "",
+            "Commands: [cyan]/proxy on[/cyan]  [cyan]/proxy off[/cyan]  "
+            "[cyan]/proxy url <url>[/cyan]  [cyan]/proxy token[/cyan] (prompts for token)",
+        ]
+        return CommandResult(handled=True, output="\n".join(lines))
+
+    def apply_proxy_token(self, token: str) -> CommandResult:
+        """Store proxy token received via hidden prompt (never written to history)."""
+        token = token.strip()
+        if not token:
+            return CommandResult(handled=True, output="[yellow]No token entered.[/yellow]")
+        self._proxy_token = token
+        try:
+            CredentialStore().set("proxy", token)
+            masked = "****" + token[-4:] if len(token) >= 4 else "****"
+            return CommandResult(
+                handled=True,
+                output=f"Proxy token saved to OS keychain ([cyan]{masked}[/cyan]).",
+                proxy_token=token,
+            )
+        except Exception as exc:
+            log.warning("Could not save proxy token to keychain: %s", exc)
+            masked = "****" + token[-4:] if len(token) >= 4 else "****"
+            return CommandResult(
+                handled=True,
+                output=(
+                    f"Proxy token set for this session ([cyan]{masked}[/cyan]). "
+                    "[yellow]Keychain save failed — token will not persist.[/yellow]"
+                ),
+                proxy_token=token,
+            )