refactorai-cli 0.1.0__py3-none-any.whl

refactor_cli/commands/run_cmds.py

@@ -0,0 +1,2159 @@
+"""Project/run commands.
+
+R7.2 adds central-store registration (`init`, `status`) and R7.3 adds the
+read-only review pipeline (`review`, `diff`). `code`/`apply` handle patch
+generation and application.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import uuid
+from pathlib import Path
+from typing import Callable
+
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from refactor_core.constitution import (
+    CONFIG_FILENAME,
+    CONSTITUTION_FILENAME,
+    DEFAULT_CONFIG,
+    DEFAULT_CONSTITUTION,
+    find_project_files,
+    has_raw_secret_literal,
+    load_config,
+    load_constitution,
+    raw_secret_matches,
+    raw_secret_matches_config,
+)
+from refactor_core.apply import (
+    ApplyError,
+    apply_changes,
+    compute_file_changes,
+    read_marker,
+    revert_from_backup,
+)
+from refactor_core.budgeting import compute_budget
+from refactor_core.capabilities import resolve_capabilities
+from refactor_core.execution import resolve_mode, run_with_mode
+from refactor_core.execution.rr_executor import run_refactor_requests
+from refactor_core.gate import evaluate_gate
+from refactor_core.refactor_requests import (
+    clear_requests,
+    create_requests,
+    list_requests,
+    pending_requests,
+)
+from refactor_core.indexing import index_target
+from refactor_core.models import Finding, GeneratedTest, PatchGroup, RunArtifact
+from refactor_core.pipeline import build_refactor_prompt, build_review_prompt
+from refactor_core.providers import get_provider, resolve_provider_name, supported_providers
+from refactor_core.rules import annotate_documents_with_rules, filter_documents_by_rules
+from refactor_core.sandbox_runtime import (
+    DEFAULT_IMAGE as SANDBOX_DEFAULT_IMAGE,
+    DEFAULT_SHELL as SANDBOX_DEFAULT_SHELL,
+    attach_shell as attach_sandbox_shell,
+    command_exists_in_sandbox,
+    detect_installer_in_sandbox,
+    ensure_sandbox,
+    exec_in_sandbox,
+    remove_sandbox_container,
+    sandbox_name,
+    resolve_runtime,
+    stop_sandbox,
+)
+from refactor_core.store import (
+    append_sandbox_install_history,
+    clear_sandbox_state,
+    create_run,
+    head_run_dir,
+    list_runs,
+    project_store_dir,
+    prune_runs,
+    read_findings,
+    read_report,
+    read_sandbox_install_history,
+    read_sandbox_preflight,
+    read_sandbox_state,
+    register_project,
+    write_sandbox_preflight,
+)
+from refactor_core.testcmd import resolve_test_command
+
+from refactor_cli.auth import AuthError, ensure_authenticated
+from refactor_cli.settings import platform_url
+
+console = Console()
+
+_SEVERITY_STYLE = {
+    "critical": "bold red",
+    "high": "red",
+    "medium": "yellow",
+    "low": "cyan",
+}
+
+_REQUIRED_ENV_BY_PROVIDER: dict[str, list[object]] = {
+    "openai": ["OPENAI_API_KEY"],
+    "openrouter": ["OPENROUTER_API_KEY"],
+    "nvidia": ["NVIDIA_API_KEY"],
+    "azure_openai": ["AZURE_OPENAI_API_KEY", "AZURE_OPENAI_ENDPOINT"],
+    "anthropic": ["ANTHROPIC_API_KEY"],
+    "vertex_ai": [("GOOGLE_OAUTH_ACCESS_TOKEN", "GCP_ACCESS_TOKEN"), "GOOGLE_CLOUD_PROJECT"],
+    "bedrock": [
+        ("AWS_BEARER_TOKEN_BEDROCK", "AWS_ACCESS_KEY_ID"),
+        # When using access keys, secret key is required too.
+        ("AWS_BEARER_TOKEN_BEDROCK", "AWS_SECRET_ACCESS_KEY"),
+    ],
+}
+
+
+def _agent_progress_logger(
+    stage: str, *, status=None, verbose_steps: bool = True
+) -> Callable[[dict], None]:
+    """Render live progress with spinner-friendly status updates.
+
+    Frequent step events update the status line (fast, low-noise). Important
+    milestones (plan, approvals, errors) are printed.
+    """
+
+    def _set_status(message: str) -> None:
+        if status is None:
+            return
+        try:
+            status.update(message)
+        except Exception:
+            return
+
+    def _log(event: dict) -> None:
+        phase = str(event.get("phase", "agentic"))
+        kind = str(event.get("event", "update"))
+        if phase == "indexing":
+            if kind == "start":
+                _set_status(f"[cyan]{stage}[/cyan] indexing target...")
+            elif kind == "done":
+                _set_status(
+                    f"[cyan]{stage}[/cyan] indexed {event.get('indexed_documents', 0)} document chunk(s)"
+                )
+            return
+        if phase == "baseline":
+            if kind == "start":
+                _set_status(
+                    f"[cyan]{stage}[/cyan] baseline review over {event.get('batches', 0)} batch(es)"
+                )
+            elif kind == "batch_done":
+                _set_status(
+                    f"[cyan]{stage}[/cyan] baseline batch {event.get('batch')}/{event.get('total_batches')} "
+                    f"(findings: {event.get('findings_so_far', 0)})"
+                )
+            elif kind == "done":
+                _set_status(
+                    f"[cyan]{stage}[/cyan] baseline complete ({event.get('floor_findings', 0)} finding(s))"
+                )
+            return
+        if phase != "agentic":
+            return
+        if kind == "start":
+            _set_status(
+                f"[cyan]{stage}[/cyan] agent loop started (max steps: {event.get('max_steps', 0)}; "
+                f"baseline: {event.get('floor_findings', 0)})"
+            )
+        elif kind == "plan_seed":
+            items = event.get("items", []) or []
+            if items:
+                console.print(f"[cyan]{stage}: agent plan[/cyan]")
+                for item in items[:6]:
+                    console.print(f"[dim]  - {item}[/dim]")
+        elif kind == "plan_proposed":
+            issues = event.get("issues", []) or []
+            if issues:
+                console.print(f"[cyan]{stage}: model plan proposal[/cyan]")
+                for issue in issues[:8]:
+                    issue_id = issue.get("issue_id", "?")
+                    sev = issue.get("severity", "?")
+                    title = issue.get("title", "")
+                    files = ", ".join(issue.get("files", [])[:3]) if isinstance(issue.get("files"), list) else ""
+                    console.print(f"[dim]  - [{sev}] {issue_id}: {title} ({files})[/dim]")
+        elif kind == "plan_locked":
+            ids = event.get("issue_ids", []) or []
+            if ids:
+                console.print(f"[green]{stage}: plan locked[/green] issue_ids={', '.join(ids)}")
+        elif kind == "phase_violation":
+            next_issue = str(event.get("next_issue", "") or "")
+            hint = f" Next: request_approval {next_issue}." if next_issue else ""
+            console.print(
+                f"[yellow]{stage}: exploration blocked after plan lock.{hint}[/yellow]"
+            )
+        elif kind == "plan_rejected":
+            console.print(
+                f"[yellow]{stage}: plan rejected[/yellow] ({event.get('reason', 'invalid plan')})."
+            )
+        elif kind == "approval_requested":
+            req = event.get("request", {}) or {}
+            console.print(
+                f"[magenta]{stage}: approval requested[/magenta] "
+                f"{req.get('issue_id', '?')} [{req.get('risk', 'medium')}] {req.get('title', '')}"
+            )
+        elif kind == "approval_decision":
+            status = "approved" if bool(event.get("approved")) else "denied"
+            color = "green" if status == "approved" else "yellow"
+            console.print(
+                f"[{color}]{stage}: approval {status}[/{color}] "
+                f"for issue {event.get('issue_id', '?')}"
+            )
+        elif kind == "tool_call":
+            action = str(event.get("action", "") or "")
+            reason = str(event.get("reason", "") or "")
+            confidence = event.get("confidence")
+            suffix = f" ({action})" if action else ""
+            reason_suffix = f" | why: {reason}" if reason else ""
+            conf_suffix = ""
+            if isinstance(confidence, (int, float)):
+                conf_suffix = f" | conf={max(0.0, min(1.0, float(confidence))):.2f}"
+            _set_status(
+                f"[cyan]{stage}[/cyan] step {event.get('step', '?')} -> `{event.get('tool', '?')}`{suffix}"
+            )
+            if verbose_steps:
+                console.print(
+                    f"[dim]{stage}: step {event.get('step', '?')} -> tool `{event.get('tool', '?')}`"
+                    f"{suffix}{reason_suffix}{conf_suffix}[/dim]"
+                )
+        elif kind == "tool_result":
+            summary = str(event.get("result", "") or "ok")
+            _set_status(f"[cyan]{stage}[/cyan] step {event.get('step', '?')} result -> {summary}")
+            if verbose_steps:
+                console.print(
+                    f"[dim]{stage}: step {event.get('step', '?')} result -> {summary}[/dim]"
+                )
+        elif kind == "tool_error":
+            console.print(
+                f"[yellow]{stage}: step {event.get('step', '?')} tool `{event.get('tool', '?')}` "
+                f"error: {event.get('error', 'unknown')}[/yellow]"
+            )
+        elif kind == "invalid_response":
+            console.print(f"[yellow]{stage}: step {event.get('step', '?')} returned invalid JSON tool call.[/yellow]")
+        elif kind == "transport_error":
+            console.print(
+                f"[yellow]{stage}: model transport error at step {event.get('step', '?')}: "
+                f"{event.get('error', 'unknown')}[/yellow]"
+            )
+        elif kind == "finish":
+            _set_status(
+                f"[green]{stage}[/green] finish at step {event.get('step', '?')} "
+                f"(merged findings: {event.get('merged_findings', 0)})"
+            )
+            if verbose_steps:
+                console.print(
+                    f"[dim]{stage}: finish at step {event.get('step', '?')} "
+                    f"(merged findings: {event.get('merged_findings', 0)}).[/dim]"
+                )
+        elif kind == "ended_without_finish":
+            console.print(
+                f"[yellow]{stage}: agent reached step limit ({event.get('steps_used', 0)}) "
+                "without finish; keeping baseline findings.[/yellow]"
+            )
+        elif kind == "step_limit_reached":
+            _set_status(
+                f"[yellow]{stage}[/yellow] step limit reached "
+                f"({event.get('steps_used', 0)}/{event.get('max_steps', 0)})"
+            )
+        elif kind == "step_limit_extended":
+            console.print(
+                f"[green]{stage}: continuing[/green] "
+                f"step budget {event.get('old_max_steps', 0)} -> {event.get('new_max_steps', 0)}"
+            )
+
+    return _log
+
+
+def _approval_prompt(stage: str, *, auto_approve: bool) -> Callable[[dict], bool]:
+    """Ask developer approval per issue for agentic code mode."""
+
+    def _ask(req: dict) -> bool:
+        if auto_approve:
+            return True
+        if not sys.stdin.isatty():
+            console.print(
+                f"[yellow]{stage}: non-interactive terminal; auto-denying issue "
+                f"{req.get('issue_id', '?')} (use --auto-approve to allow).[/yellow]"
+            )
+            return False
+        issue_id = str(req.get("issue_id", "?"))
+        title = str(req.get("title", "Untitled issue"))
+        summary = str(req.get("summary", "") or "")
+        risk = str(req.get("risk", "medium") or "medium")
+        console.print(f"\n[bold]Issue[/bold] {issue_id}  [dim]risk={risk}[/dim]")
+        console.print(f"[bold]Title:[/bold] {title}")
+        if summary:
+            console.print(f"[bold]Plan:[/bold] {summary}")
+        console.print("[dim]Approval input: type 'y' to approve; type 'n' (or press Enter) to deny.[/dim]")
+        raw = typer.prompt("Approve this issue implementation? (y/N)", default="N")
+        return raw.strip().lower() in {"y", "yes"}
+
+    return _ask
+
+
+def _rr_approval_prompt(*, auto_approve: bool) -> Callable[[dict], bool]:
+    """Ask developer approval for a single RR proposal, showing the diff."""
+
+    def _ask(req: dict) -> bool:
+        attempt = int(req.get("attempt", 1) or 1)
+        location = str(req.get("location", "?"))
+        summary = str(req.get("summary", "") or "")
+        risk = str(req.get("risk", "medium") or "medium")
+        diff_text = str(req.get("diff_text", "") or "")
+        console.print(f"\n[bold]Proposed change[/bold] for [cyan]{location}[/cyan] "
+                      f"[dim](attempt {attempt}/3, risk={risk})[/dim]")
+        if summary:
+            console.print(f"[bold]Change:[/bold] {summary}")
+        if diff_text:
+            console.print("[dim]--- diff preview ---[/dim]")
+            for line in diff_text.splitlines()[:60]:
+                if line.startswith("+") and not line.startswith("+++"):
+                    console.print(f"[green]{line}[/green]")
+                elif line.startswith("-") and not line.startswith("---"):
+                    console.print(f"[red]{line}[/red]")
+                else:
+                    console.print(f"[dim]{line}[/dim]")
+        if auto_approve:
+            console.print("[dim]--auto-approve: applying without prompt.[/dim]")
+            return True
+        if not sys.stdin.isatty():
+            console.print("[yellow]non-interactive terminal; auto-denying (use --auto-approve to allow).[/yellow]")
+            return False
+        console.print("[dim]Type 'y' to apply this change; 'n' (or press Enter) to skip the issue.[/dim]")
+        raw = typer.prompt("Apply this change? (y/N)", default="N")
+        return raw.strip().lower() in {"y", "yes"}
+
+    return _ask
+
+
+def _rr_progress_logger(status=None) -> Callable[[dict], None]:
+    """Render the per-RR interactive flow with clear, dynamic messages."""
+
+    def _log(event: dict) -> None:
+        if event.get("phase") not in {"rr", "indexing", "baseline"}:
+            return
+        ev = event.get("event")
+        if ev == "run_start":
+            if status:
+                status.update("[cyan]code[/cyan] starting refactor requests...")
+            cmd = event.get("test_command") or "(none; syntax/LSP only)"
+            container = str(event.get("container_name", "") or "")
+            env = str(event.get("execution_env", "host") or "host")
+            console.print(
+                f"[bold cyan]code:[/bold cyan] {event.get('total_requests', 0)} "
+                f"refactor request(s); test command: [dim]{cmd}[/dim]"
+            )
+            if env == "sandbox":
+                console.print(
+                    f"[bold cyan]code:[/bold cyan] running in sandbox: [dim]{cmd}[/dim] "
+                    f"(container={container or '?'})"
+                )
+        elif ev == "rr_start":
+            if status:
+                status.update(f"[cyan]code[/cyan] working on {event.get('location', '?')}...")
+            console.print(f"\n[bold]\u2192 Working on issue[/bold] [cyan]{event.get('location', '?')}[/cyan]")
+        elif ev == "test_generating":
+            if status:
+                status.update("[cyan]code[/cyan] generating characterization test...")
+            console.print("[dim]  generating characterization test...[/dim]")
+        elif ev == "baseline_test":
+            if status:
+                status.update("[cyan]code[/cyan] running baseline test...")
+            rr_id = str(event.get("rr_id", "?"))
+            outcome = "pass" if event.get("passed") else "fail"
+            env = str(event.get("execution_env", "host") or "host")
+            detail = str(event.get("detail", "") or "")
+            detail_snip = detail[:160] if detail else ""
+            console.print(
+                f"[dim]  rr={rr_id} baseline test: {outcome} ({env})"
+                f"{' - ' + detail_snip if detail_snip else ''}[/dim]"
+            )
+        elif ev == "approval_requested":
+            if status:
+                status.update("[cyan]code[/cyan] awaiting developer approval...")
+                # Approval is interactive input; pause the spinner so the full
+                # prompt line is visible and not visually overwritten.
+                try:
+                    status.stop()
+                except Exception:
+                    pass
+        elif ev == "approval_decision":
+            if status:
+                # Resume spinner after the interactive prompt returns.
+                try:
+                    status.start()
+                except Exception:
+                    pass
+                status.update("[cyan]code[/cyan] applying approved change...")
+        elif ev == "rr_applied":
+            if status:
+                status.update("[green]code[/green] change verified, moving to next issue...")
+            files = ", ".join(event.get("files", []) or [])
+            console.print(f"[green]  \u2713 applied & verified[/green] [dim]{files}[/dim]")
+        elif ev == "rr_reverted":
+            if status:
+                status.update("[yellow]code[/yellow] verification failed; reverting and retrying...")
+            console.print(
+                f"[yellow]  \u21ba reverted (attempt {event.get('attempt')}): "
+                f"{event.get('detail', '')[:160]}[/yellow]"
+            )
+        elif ev == "proposal_invalid":
+            if status:
+                status.update("[yellow]code[/yellow] proposal invalid; retrying...")
+            console.print(
+                f"[yellow]  proposal {event.get('attempt')} invalid: {event.get('reason', '')}[/yellow]"
+            )
+        elif ev == "preflight_failed":
+            if status:
+                status.update("[red]code[/red] preflight failed.")
+            console.print(f"[red]  ✗ preflight failed:[/red] {event.get('reason', '')}")
+        elif ev == "run_stopped":
+            if status:
+                status.update("[red]code[/red] stopped after repeated failures.")
+            console.print(f"[red]  \u2717 stopped:[/red] {event.get('reason', '')}")
+        elif ev == "run_done":
+            if status:
+                status.update("[green]code[/green] completed.")
+
+    return _log
+
+
+def _step_limit_prompt(stage: str) -> Callable[[dict], bool]:
+    """Ask whether to continue when agentic max-step budget is exhausted."""
+
+    def _ask(info: dict) -> bool:
+        steps_used = int(info.get("steps_used", 0) or 0)
+        max_steps = int(info.get("max_steps", 0) or 0)
+        extension = int(info.get("default_extension", max_steps) or max_steps or 1)
+        if not sys.stdin.isatty():
+            console.print(
+                f"[yellow]{stage}: step limit reached ({steps_used}/{max_steps}) in non-interactive terminal; "
+                "stopping. Re-run with higher `max_agent_steps` to continue.[/yellow]"
+            )
+            return False
+        console.print(
+            f"[yellow]{stage}: reached step limit ({steps_used}/{max_steps}).[/yellow] "
+            f"Increase by {extension} steps and continue?"
+        )
+        raw = typer.prompt("Continue agent loop? (y/N)", default="N")
+        return raw.strip().lower() in {"y", "yes"}
+
+    return _ask
+
+
+def _require_auth() -> None:
+    try:
+        ensure_authenticated()
+    except AuthError as exc:
+        console.print(f"[red]Blocked:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+
+def _is_cloud_mode(constitution) -> bool:
+    return str(constitution.get_setting("mode", "local") or "local").strip().lower() == "cloud_managed"
+
+
+def _cloud_inference(
+    *,
+    stage: str,
+    project_root: Path,
+    constitution,
+    target: str,
+    model_hint: str | None = None,
+) -> RunArtifact:
+    max_alerts = int(constitution.get_setting("max_alerts_per_run", 5) or 5)
+    gate_mode = str(constitution.get_setting("gate_mode", "strict") or "strict")
+    excludes = set(constitution.get_setting("exclude", []) or [])
+    documents = index_target(Path(project_root), target, excludes=excludes)
+    documents, _scope_meta = filter_documents_by_rules(documents, project_root=Path(project_root))
+    rule_meta = annotate_documents_with_rules(documents, project_root=Path(project_root))
+
+    if stage == "review":
+        system_prompt, user_prompt = build_review_prompt(constitution, documents, max_alerts)
+    else:
+        system_prompt, user_prompt = build_refactor_prompt(constitution, documents, [], max_alerts)
+
+    auth_ctx = ensure_authenticated(project_root)
+    payload = {
+        "stage": stage,
+        "constitution_hash": constitution.content_hash,
+        "system_prompt": system_prompt,
+        "user_prompt": user_prompt,
+        "max_alerts": max_alerts,
+        "model_hint": model_hint or str(constitution.get_setting("model_id", "managed-default") or "managed-default"),
+    }
+    try:
+        response = httpx.post(
+            f"{platform_url()}/v1/inference/refactor",
+            headers={
+                "Authorization": f"Bearer {auth_ctx.key.key}",
+                "Content-Type": "application/json",
+                "Idempotency-Key": uuid.uuid4().hex,
+            },
+            json=payload,
+            timeout=45.0,
+        )
+    except httpx.HTTPError as exc:
+        raise RuntimeError(f"Could not reach managed inference service: {exc}") from exc
+
+    if response.status_code == 401:
+        raise RuntimeError("Cloud inference unauthorized (developer key invalid or revoked).")
+    if response.status_code == 402:
+        raise RuntimeError("Cloud inference requires paid tier (`mode: cloud_managed`).")
+    if response.status_code == 429:
+        raise RuntimeError("Cloud inference quota exhausted or rate-limited.")
+    if response.status_code >= 400:
+        raise RuntimeError(f"Cloud inference failed ({response.status_code}): {response.text[:500]}")
+
+    data = response.json() if response.content else {}
+    findings = [Finding.model_validate(item) for item in (data.get("findings") or [])][:max_alerts]
+    patches = [PatchGroup.model_validate(item) for item in (data.get("patches") or [])][:max_alerts]
+    generated_tests = [
+        GeneratedTest.model_validate(item) for item in (data.get("generated_tests") or [])
+    ][:max_alerts]
+    gate = evaluate_gate(findings, [], mode=gate_mode)
+
+    run_id = uuid.uuid4().hex[:12]
+    if stage == "review":
+        summary = (
+            f"Cloud review of '{target}' produced {len(findings)} finding(s); "
+            f"gate={gate.status} (high_findings={gate.high_severity_findings})."
+        )
+    else:
+        summary = (
+            f"Cloud refactor of '{target}': {len(findings)} finding(s), {len(patches)} patch group(s), "
+            f"{len(generated_tests)} generated test(s); gate={gate.status}."
+        )
+    return RunArtifact(
+        run_id=run_id,
+        findings=findings,
+        patches=patches,
+        generated_tests=generated_tests,
+        gate=gate,
+        summary=summary,
+        constitution_hash=constitution.content_hash,
+        model_id=str(data.get("model_id") or payload["model_hint"]),
+        rule_source=rule_meta.get("rule_source", ""),
+        rule_pattern=rule_meta.get("rule_pattern", ""),
+        rule_hash=rule_meta.get("rule_hash", ""),
+    )
+
+
+def _load_project() -> tuple[Path, object, object]:
+    files = find_project_files()
+    if not files:
+        console.print(
+            f"[yellow]Missing {CONSTITUTION_FILENAME} or {CONFIG_FILENAME}.[/yellow] "
+            "Run `refactor init` first."
+        )
+        raise typer.Exit(code=1)
+    consti_path, config_path = files
+    constitution = load_constitution(consti_path)
+    config = load_config(config_path)
+    _warn_raw_key(constitution, config)
+    return consti_path.parent, constitution, config
+
+
+def _warn_raw_key(constitution, config) -> None:
+    if has_raw_secret_literal(constitution) or bool(raw_secret_matches_config(config)):
+        console.print(
+            "[yellow]Warning:[/yellow] literal credential-like value(s) appear in "
+            f"{CONSTITUTION_FILENAME} or {CONFIG_FILENAME}. "
+            "Prefer `${ENV_VAR}` references and keep secrets out of "
+            "version control. Run `refactor check --strict` in CI to enforce."
+        )
+
+
+def init(
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help=f"Overwrite existing {CONSTITUTION_FILENAME} and {CONFIG_FILENAME}.",
+    ),
+) -> None:
+    """Create `refactor.consti` + `refactor.config` and register the project."""
+    try:
+        project_root = Path.cwd()
+    except OSError:
+        console.print(
+            "[red]Could not resolve the current project directory.[/red] "
+            "Please switch to a valid directory and retry. "
+            "If the problem continues, update/reinstall Refactor."
+        )
+        raise typer.Exit(code=1) from None
+
+    consti_target = project_root / CONSTITUTION_FILENAME
+    config_target = project_root / CONFIG_FILENAME
+    if (consti_target.exists() or config_target.exists()) and not force:
+        console.print(
+            f"[yellow]{CONSTITUTION_FILENAME} or {CONFIG_FILENAME} already exists.[/yellow] "
+            "Use --force to overwrite."
+        )
+        raise typer.Exit(code=1)
+    consti_target.write_text(DEFAULT_CONSTITUTION, encoding="utf-8")
+    config_target.write_text(DEFAULT_CONFIG, encoding="utf-8")
+
+    constitution = load_constitution(consti_target)
+    record = register_project(project_root, constitution_hash=constitution.content_hash)
+    console.print(f"[green]Created[/green] {consti_target}")
+    console.print(f"[green]Created[/green] {config_target}")
+    console.print(
+        f"[green]Registered[/green] project in central store: {project_store_dir(project_root)}"
+    )
+    console.print(
+        f"Only {CONSTITUTION_FILENAME} and {CONFIG_FILENAME} are added to your repo; "
+        "all run state stays under ~/.refactor "
+        f"(encoded: {record['encoded']})."
+    )
+
+
+_ENV_ASSIGN_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=.*$")
+
+
+def _command_binary(command: str) -> str | None:
+    """Extract the executable from a shell command string."""
+    if not command:
+        return None
+    try:
+        tokens = shlex.split(command, posix=True)
+    except ValueError:
+        return None
+    while tokens and _ENV_ASSIGN_RE.match(tokens[0]):
+        tokens.pop(0)
+    return tokens[0] if tokens else None
+
+
+def _install_plan_for_missing_binary(
+    *, project_root: Path, binary: str, installer: str | None
+) -> list[str]:
+    """Return a conservative install plan for missing toolchain commands."""
+    if not installer:
+        return []
+    pkg_cmd = ""
+    if installer == "apk":
+        if binary in {"npm", "node"}:
+            pkg_cmd = "apk add --no-cache nodejs npm"
+        elif binary in {"python", "python3", "pip", "pip3", "pytest"}:
+            pkg_cmd = "apk add --no-cache python3 py3-pip"
+    elif installer == "apt-get":
+        if binary in {"npm", "node"}:
+            pkg_cmd = "apt-get update && apt-get install -y nodejs npm"
+        elif binary in {"python", "python3", "pip", "pip3", "pytest"}:
+            pkg_cmd = "apt-get update && apt-get install -y python3 python3-pip"
+    elif installer in {"dnf", "yum"}:
+        if binary in {"npm", "node"}:
+            pkg_cmd = f"{installer} install -y nodejs npm"
+        elif binary in {"python", "python3", "pip", "pip3", "pytest"}:
+            pkg_cmd = f"{installer} install -y python3 python3-pip"
+    plan: list[str] = []
+    if pkg_cmd:
+        plan.append(pkg_cmd)
+    # Dependency restore after toolchain install (best effort).
+    if (project_root / "package.json").is_file():
+        plan.append("npm install")
+    elif (project_root / "requirements.txt").is_file():
+        plan.append("pip install -r requirements.txt")
+    return plan
+
+
+def _node_toolchain_install(installer: str | None) -> str | None:
+    if installer == "apk":
+        return "apk add --no-cache nodejs npm"
+    if installer == "apt-get":
+        return "apt-get update && apt-get install -y nodejs npm"
+    if installer in {"dnf", "yum"}:
+        return f"{installer} install -y nodejs npm"
+    return None
+
+
+def _go_toolchain_install(installer: str | None) -> str | None:
+    if installer == "apk":
+        return "apk add --no-cache go"
+    if installer == "apt-get":
+        return "apt-get update && apt-get install -y golang-go"
+    if installer in {"dnf", "yum"}:
+        return f"{installer} install -y golang"
+    return None
+
+
+def _project_languages(project_root: Path) -> set[str]:
+    """Infer likely project languages from common manifest/build markers."""
+    langs: set[str] = set()
+    if (project_root / "package.json").is_file():
+        langs.update({"javascript", "typescript"})
+    if (project_root / "tsconfig.json").is_file():
+        langs.add("typescript")
+    if any((project_root / name).is_file() for name in ("requirements.txt", "pyproject.toml", "setup.py", "Pipfile")):
+        langs.add("python")
+    if (project_root / "go.mod").is_file():
+        langs.add("go")
+    if (project_root / "Cargo.toml").is_file():
+        langs.add("rust")
+    if any((project_root / name).is_file() for name in ("pom.xml", "build.gradle", "build.gradle.kts")):
+        langs.add("java")
+    if list(project_root.glob("*.csproj")) or list(project_root.glob("*.sln")):
+        langs.add("csharp")
+    if any((project_root / name).is_file() for name in ("CMakeLists.txt", "compile_commands.json")):
+        langs.update({"c", "cpp"})
+    return langs
+
+
+def _required_lsp_commands(project_root: Path) -> dict[str, str]:
+    """Return required LSP command -> friendly name based on inferred languages."""
+    from refactor_core.codeintel.lsp import LSP_SERVERS
+
+    required: dict[str, str] = {}
+    for language in sorted(_project_languages(project_root)):
+        entry = LSP_SERVERS.get(language)
+        if not entry:
+            continue
+        command, name = entry
+        required[command] = name
+    return required
+
+
+def _install_plan_for_missing_lsp(
+    *,
+    missing_commands: list[str],
+    installer: str | None,
+) -> tuple[list[str], list[str]]:
+    """Return (install_plan, unsupported_commands) for missing LSP binaries."""
+    plan: list[str] = []
+    unsupported: list[str] = []
+    for command in missing_commands:
+        if command == "typescript-language-server":
+            prereq = _node_toolchain_install(installer)
+            if prereq:
+                plan.append(prereq)
+            plan.append("npm install -g typescript typescript-language-server")
+            continue
+        if command == "pyright-langserver":
+            prereq = _node_toolchain_install(installer)
+            if prereq:
+                plan.append(prereq)
+            plan.append("npm install -g pyright")
+            continue
+        if command == "gopls":
+            prereq = _go_toolchain_install(installer)
+            if prereq:
+                plan.append(prereq)
+                plan.append("GOBIN=/usr/local/bin go install golang.org/x/tools/gopls@latest")
+            else:
+                unsupported.append(command)
+            continue
+        if command == "rust-analyzer":
+            if installer == "apk":
+                plan.append("apk add --no-cache rust-analyzer")
+            elif installer == "apt-get":
+                plan.append("apt-get update && apt-get install -y rust-analyzer")
+            elif installer in {"dnf", "yum"}:
+                plan.append(f"{installer} install -y rust-analyzer")
+            else:
+                unsupported.append(command)
+            continue
+        if command == "clangd":
+            if installer == "apk":
+                plan.append("apk add --no-cache clang-extra-tools")
+            elif installer == "apt-get":
+                plan.append("apt-get update && apt-get install -y clangd")
+            elif installer in {"dnf", "yum"}:
+                plan.append(f"{installer} install -y clang-tools-extra")
+            else:
+                unsupported.append(command)
+            continue
+        if command == "jdtls":
+            if installer == "apk":
+                plan.append("apk add --no-cache openjdk17-jre")
+            elif installer == "apt-get":
+                plan.append("apt-get update && apt-get install -y openjdk-17-jre-headless")
+                plan.append("apt-get update && apt-get install -y jdtls")
+            elif installer in {"dnf", "yum"}:
+                plan.append(f"{installer} install -y java-17-openjdk")
+            else:
+                unsupported.append(command)
+            continue
+        if command == "omnisharp":
+            # Distribution install varies widely; keep explicit unsupported for now.
+            unsupported.append(command)
+            continue
+        unsupported.append(command)
+    # Deduplicate while preserving order.
+    dedup_plan = list(dict.fromkeys(plan))
+    return dedup_plan, unsupported
+
+
+def _host_runtime_install_plan(runtime: str) -> list[str]:
+    """Return host-level install commands for a missing runtime binary."""
+    rt = (runtime or "").strip().lower()
+    if rt != "podman":
+        return []
+    if shutil.which("apt-get"):
+        return ["sudo apt-get update", "sudo apt-get install -y podman"]
+    if shutil.which("dnf"):
+        return ["sudo dnf install -y podman"]
+    if shutil.which("yum"):
+        return ["sudo yum install -y podman"]
+    if shutil.which("apk"):
+        return ["sudo apk add --no-cache podman"]
+    if shutil.which("pacman"):
+        return ["sudo pacman -Sy --noconfirm podman"]
+    if shutil.which("brew"):
+        return ["brew install podman"]
+    return []
+
+
+def _maybe_install_host_runtime(
+    *,
+    runtime: str,
+    reason: str,
+    auto_approve: bool,
+) -> tuple[bool, str]:
+    """Ask approval, install missing host runtime, and return status."""
+    plan = _host_runtime_install_plan(runtime)
+    if not plan:
+        return False, reason
+
+    console.print(f"[yellow]{reason}[/yellow]")
+    console.print(f"[bold]Host install plan for `{runtime}`:[/bold]")
+    for cmd in plan:
+        console.print(f"[dim]  - {cmd}[/dim]")
+
+    approved = auto_approve
+    if not auto_approve:
+        if not sys.stdin.isatty():
+            return (
+                False,
+                "Host runtime install plan requires approval in non-interactive mode "
+                "(use `refactor start --yes` to auto-approve, or install manually).",
+            )
+        raw = typer.prompt(f"Install {runtime} on host? (y/N)", default="N")
+        approved = raw.strip().lower() in {"y", "yes"}
+    if not approved:
+        return False, f"{runtime} install not approved."
+
+    for cmd in plan:
+        proc = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+        if proc.returncode != 0:
+            detail = (proc.stderr or proc.stdout or "").strip()[:500]
+            return False, f"Host install failed: `{cmd}` -> {detail}"
+    return True, f"{runtime} installed on host."
+
+
+def _sandbox_preflight(
+    *,
+    project_root: Path,
+    config_settings: dict,
+    auto_approve: bool,
+    no_install: bool,
+) -> tuple[bool, str]:
+    """Run sandbox preflight and optionally perform approved install plan."""
+    test_command = resolve_test_command(project_root, config_settings)
+    required_lsp = _required_lsp_commands(project_root)
+    missing_lsp = [
+        cmd for cmd in sorted(required_lsp) if not command_exists_in_sandbox(project_root=project_root, binary=cmd)
+    ]
+    missing_binary = ""
+    test_command_present = ""
+    if test_command:
+        binary = _command_binary(test_command)
+        if not binary:
+            write_sandbox_preflight(
+                project_root,
+                {
+                    "status": "blocked",
+                    "reason": "unparseable_test_command",
+                    "test_command": test_command,
+                    "missing_lsp_servers": missing_lsp,
+                },
+            )
+            return False, f"Could not parse test command: {test_command!r}"
+        test_command_present = binary
+        if not command_exists_in_sandbox(project_root=project_root, binary=binary):
+            missing_binary = binary
+
+    if not missing_binary and not missing_lsp:
+        write_sandbox_preflight(
+            project_root,
+            {
+                "status": "passed",
+                "reason": "requirements_present",
+                "test_command": test_command or "",
+                "required_binary": test_command_present,
+                "required_lsp_servers": sorted(required_lsp),
+                "missing_lsp_servers": [],
+            },
+        )
+        if not test_command:
+            return True, "No test command configured."
+        return True, f"Preflight ok: found '{test_command_present}' and required LSP server(s) in sandbox."
+
+    installer = detect_installer_in_sandbox(project_root=project_root)
+    plan: list[str] = []
+    if missing_binary:
+        plan.extend(
+            _install_plan_for_missing_binary(
+                project_root=project_root, binary=missing_binary, installer=installer
+            )
+        )
+    lsp_plan, unsupported_lsp = _install_plan_for_missing_lsp(
+        missing_commands=missing_lsp, installer=installer
+    )
+    plan.extend(lsp_plan)
+    plan = list(dict.fromkeys(plan))
+    if no_install:
+        write_sandbox_preflight(
+            project_root,
+            {
+                "status": "blocked",
+                "reason": "missing_binary_no_install",
+                "test_command": test_command or "",
+                "required_binary": missing_binary,
+                "install_plan": plan,
+                "missing_lsp_servers": missing_lsp,
+                "unsupported_lsp_servers": unsupported_lsp,
+            },
+        )
+        return (
+            False,
+            "Preflight failed with missing runtime requirements (test command and/or LSP servers). "
+            "Re-run without --no-install to approve and execute an install plan.",
+        )
+    if not plan and (missing_binary or missing_lsp):
+        write_sandbox_preflight(
+            project_root,
+            {
+                "status": "blocked",
+                "reason": "missing_binary_no_plan",
+                "test_command": test_command or "",
+                "required_binary": missing_binary,
+                "missing_lsp_servers": missing_lsp,
+                "unsupported_lsp_servers": unsupported_lsp,
+            },
+        )
+        return (
+            False,
+            "Preflight failed: missing test/LSP requirements and no install plan is available. "
+            "Configure sandbox image/dependencies, then retry.",
+        )
+
+    if missing_binary:
+        console.print(
+            f"[yellow]Preflight:[/yellow] missing required command [bold]{missing_binary}[/bold] "
+            f"for test command `{test_command}`."
+        )
+    if missing_lsp:
+        names = ", ".join(required_lsp.get(cmd, cmd) for cmd in missing_lsp)
+        console.print(f"[yellow]Preflight:[/yellow] missing LSP server(s): {names}")
+    if unsupported_lsp:
+        names = ", ".join(required_lsp.get(cmd, cmd) for cmd in unsupported_lsp)
+        console.print(
+            f"[yellow]Note:[/yellow] no automatic install recipe for: {names}. "
+            "Install manually in sandbox image if needed."
+        )
+    console.print("[bold]Install plan (sandbox):[/bold]")
+    for cmd in plan:
+        console.print(f"[dim]  - {cmd}[/dim]")
+
+    approved = auto_approve
+    if not auto_approve:
+        if not sys.stdin.isatty():
+            return (
+                False,
+                "Preflight failed and install approval is required in non-interactive terminal "
+                "(use --yes to auto-approve).",
+            )
+        raw = typer.prompt("Approve install plan? (y/N)", default="N")
+        approved = raw.strip().lower() in {"y", "yes"}
+    if not approved:
+        write_sandbox_preflight(
+            project_root,
+            {
+                "status": "blocked",
+                "reason": "install_plan_denied",
+                "test_command": test_command or "",
+                "required_binary": missing_binary,
+                "install_plan": plan,
+                "missing_lsp_servers": missing_lsp,
+                "unsupported_lsp_servers": unsupported_lsp,
+            },
+        )
+        append_sandbox_install_history(
+            project_root,
+            {
+                "approved": False,
+                "test_command": test_command or "",
+                "required_binary": missing_binary,
+                "missing_lsp_servers": missing_lsp,
+                "plan": plan,
+            },
+        )
+        return False, "Install plan not approved; preflight remains blocked."
+
+    entry = {
+        "approved": True,
+        "test_command": test_command or "",
+        "required_binary": missing_binary,
+        "missing_lsp_servers": missing_lsp,
+        "plan": plan,
+        "results": [],
+    }
+    for cmd in plan:
+        ok, output = exec_in_sandbox(project_root=project_root, command=cmd)
+        entry["results"].append({"command": cmd, "ok": ok, "output": (output or "")[:500]})
+        if not ok:
+            detail = output[:400] if output else "unknown error"
+            append_sandbox_install_history(project_root, entry)
+            write_sandbox_preflight(
+                project_root,
+                {
+                    "status": "blocked",
+                    "reason": "install_command_failed",
+                    "test_command": test_command or "",
+                    "required_binary": missing_binary,
+                    "install_plan": plan,
+                    "missing_lsp_servers": missing_lsp,
+                    "unsupported_lsp_servers": unsupported_lsp,
+                },
+            )
+            return False, f"Install command failed: `{cmd}` -> {detail}"
+    append_sandbox_install_history(project_root, entry)
+
+    if missing_binary and not command_exists_in_sandbox(project_root=project_root, binary=missing_binary):
+        write_sandbox_preflight(
+            project_root,
+            {
+                "status": "blocked",
+                "reason": "binary_still_missing_after_install",
+                "test_command": test_command or "",
+                "required_binary": missing_binary,
+                "install_plan": plan,
+                "missing_lsp_servers": missing_lsp,
+                "unsupported_lsp_servers": unsupported_lsp,
+            },
+        )
+        return False, f"Preflight still failed after install: '{missing_binary}' not found."
+    still_missing_lsp = [
+        cmd for cmd in missing_lsp if not command_exists_in_sandbox(project_root=project_root, binary=cmd)
+    ]
+    if still_missing_lsp:
+        write_sandbox_preflight(
+            project_root,
+            {
+                "status": "blocked",
+                "reason": "lsp_still_missing_after_install",
+                "test_command": test_command or "",
+                "required_binary": missing_binary,
+                "install_plan": plan,
+                "missing_lsp_servers": still_missing_lsp,
+                "unsupported_lsp_servers": unsupported_lsp,
+            },
+        )
+        names = ", ".join(required_lsp.get(cmd, cmd) for cmd in still_missing_lsp)
+        return False, f"Preflight still failed after install: missing LSP server(s): {names}."
+    write_sandbox_preflight(
+        project_root,
+        {
+            "status": "passed",
+            "reason": "requirements_found_after_install",
+            "test_command": test_command or "",
+            "required_binary": missing_binary,
+            "install_plan": plan,
+            "required_lsp_servers": sorted(required_lsp),
+            "missing_lsp_servers": [],
+        },
+    )
+    if missing_binary and missing_lsp:
+        return True, (
+            f"Preflight passed after install: found '{missing_binary}' and installed required LSP server(s)."
+        )
+    if missing_binary:
+        return True, f"Preflight passed after install: found '{missing_binary}'."
+    return True, "Preflight passed after install: required LSP server(s) installed."
+
+
+def _sandbox_settings(project_config) -> dict:
+    settings = dict(getattr(project_config, "settings", {}) or {})
+    sandbox_cfg = settings.get("sandbox", {})
+    return sandbox_cfg if isinstance(sandbox_cfg, dict) else {}
+
+
+def _sandbox_enabled(project_config) -> bool:
+    # Sandbox is now mandatory for local review/code execution.
+    return True
+
+
+def _sandbox_lifecycle(project_config) -> str:
+    lifecycle = str(_sandbox_settings(project_config).get("lifecycle", "per_run") or "per_run").strip().lower()
+    return lifecycle if lifecycle in {"per_project", "per_run"} else "per_run"
+
+
+def _ensure_sandbox_ready(
+    *,
+    project_root: Path,
+    project_config,
+    stage: str,
+    auto_approve_install: bool = False,
+    no_install: bool = False,
+) -> dict | None:
+    """Ensure sandbox lifecycle + preflight for stage execution."""
+    sandbox_cfg = _sandbox_settings(project_config)
+    lifecycle = _sandbox_lifecycle(project_config)
+    ephemeral = lifecycle == "per_run" and stage in {"review", "code"}
+    preferred_runtime = str(sandbox_cfg.get("runtime", "podman") or "podman")
+    resolved_runtime, reason = resolve_runtime(preferred_runtime)
+    if not resolved_runtime:
+        console.print(f"[red]{stage}: sandbox runtime unavailable:[/red] {reason}")
+        raise typer.Exit(code=1)
+    resolved_image = str(sandbox_cfg.get("image") or SANDBOX_DEFAULT_IMAGE)
+    workdir = str(sandbox_cfg.get("workdir", "/workspace") or "/workspace")
+    run_container = None
+    if ephemeral:
+        run_container = f"{sandbox_name(project_root)}-run-{uuid.uuid4().hex[:8]}"
+    ok, message, state = ensure_sandbox(
+        project_root=project_root,
+        runtime=resolved_runtime,
+        image=resolved_image,
+        rebuild=False,
+        workdir=workdir,
+        container_name=run_container,
+        persist_state=not ephemeral,
+    )
+    if not ok:
+        console.print(f"[red]{stage}: sandbox start failed:[/red] {message}")
+        raise typer.Exit(code=1)
+    console.print(
+        f"[green]{stage}: sandbox ready.[/green] runtime={resolved_runtime} "
+        f"container={state.get('container_name', '?')}"
+    )
+    settings = dict(getattr(project_config, "settings", {}) or {})
+    preflight_ok, preflight_msg = _sandbox_preflight(
+        project_root=project_root,
+        config_settings=settings,
+        auto_approve=auto_approve_install,
+        no_install=no_install,
+    )
+    if not preflight_ok:
+        console.print(f"[red]{stage}: {preflight_msg}[/red]")
+        raise typer.Exit(code=1)
+    console.print(f"[green]{stage}: {preflight_msg}[/green]")
+    return {
+        "ephemeral": ephemeral,
+        "runtime": resolved_runtime,
+        "container_name": state.get("container_name", ""),
+        "stage": stage,
+    }
+
+
+def _teardown_sandbox_context(project_root: Path, ctx: dict | None) -> None:
+    """Clean up ephemeral per-run sandboxes."""
+    if not ctx or not ctx.get("ephemeral"):
+        return
+    runtime = str(ctx.get("runtime") or "")
+    name = str(ctx.get("container_name") or "")
+    ok, msg = remove_sandbox_container(runtime=runtime, container_name=name)
+    color = "green" if ok else "yellow"
+    console.print(f"[{color}]sandbox cleanup[/{color}]: {msg}")
+    # Defensive: clear project-level state if a per-project name was accidentally used.
+    if name == sandbox_name(project_root):
+        clear_sandbox_state(project_root)
+
+
+def start(
+    rebuild: bool = typer.Option(False, "--rebuild", help="Recreate sandbox container from scratch."),
+    runtime: str = typer.Option("podman", "--runtime", help="Sandbox runtime (R11.1: podman)."),
+    image: str = typer.Option(
+        SANDBOX_DEFAULT_IMAGE,
+        "--image",
+        help="Sandbox base image used to run local commands.",
+    ),
+    yes: bool = typer.Option(False, "--yes", help="Auto-approve sandbox install plan."),
+    no_install: bool = typer.Option(
+        False, "--no-install", help="Run sandbox preflight only; do not install missing deps."
+    ),
+    shell: bool | None = typer.Option(
+        None,
+        "--shell/--no-shell",
+        help="Attach an interactive shell after sandbox is ready. "
+        "Defaults to disabled; use --shell for debug access.",
+    ),
+) -> None:
+    """Start (or reuse) the local project sandbox."""
+    _require_auth()
+    project_root, _constitution, project_config = _load_project()
+    register_project(project_root)
+
+    sandbox_cfg = _sandbox_settings(project_config)
+    preferred_runtime = str(runtime or sandbox_cfg.get("runtime", "podman") or "podman")
+    resolved_runtime, reason = resolve_runtime(preferred_runtime)
+    if not resolved_runtime:
+        installed, install_msg = _maybe_install_host_runtime(
+            runtime=preferred_runtime,
+            reason=f"Sandbox runtime unavailable: {reason}",
+            auto_approve=yes,
+        )
+        if not installed:
+            console.print(f"[red]Sandbox runtime unavailable:[/red] {install_msg}")
+            raise typer.Exit(code=1)
+        console.print(f"[green]{install_msg}[/green]")
+        resolved_runtime, reason = resolve_runtime(preferred_runtime)
+        if not resolved_runtime:
+            console.print(
+                f"[red]Sandbox runtime still unavailable after install:[/red] {reason}"
+            )
+            raise typer.Exit(code=1)
+
+    resolved_image = str(image or sandbox_cfg.get("image") or SANDBOX_DEFAULT_IMAGE)
+    workdir = str(sandbox_cfg.get("workdir", "/workspace") or "/workspace")
+    ok, message, state = ensure_sandbox(
+        project_root=project_root,
+        runtime=resolved_runtime,
+        image=resolved_image,
+        rebuild=rebuild,
+        workdir=workdir,
+    )
+    if not ok:
+        console.print(f"[red]Sandbox start failed:[/red] {message}")
+        raise typer.Exit(code=1)
+    console.print(
+        f"[green]Sandbox ready.[/green] runtime={resolved_runtime} "
+        f"container={state.get('container_name', '?')} image={resolved_image}"
+    )
+    settings = dict(getattr(project_config, "settings", {}) or {})
+    preflight_ok, preflight_msg = _sandbox_preflight(
+        project_root=project_root,
+        config_settings=settings,
+        auto_approve=yes,
+        no_install=no_install,
+    )
+    if not preflight_ok:
+        console.print(f"[red]{preflight_msg}[/red]")
+        raise typer.Exit(code=1)
+    console.print(f"[green]{preflight_msg}[/green]")
+
+    should_shell = bool(shell) if shell is not None else False
+    if not should_shell:
+        return
+    if not sys.stdin.isatty():
+        console.print("[yellow]Non-interactive terminal; cannot attach shell.[/yellow]")
+        raise typer.Exit(code=1)
+    shell_path = str(sandbox_cfg.get("shell", SANDBOX_DEFAULT_SHELL) or SANDBOX_DEFAULT_SHELL)
+    attached, detail = attach_sandbox_shell(project_root=project_root, shell_path=shell_path)
+    if not attached:
+        console.print(f"[red]Sandbox shell failed:[/red] {detail}")
+        raise typer.Exit(code=1)
+
+
+def stop() -> None:
+    """Stop the local sandbox for this project."""
+    _require_auth()
+    try:
+        project_root = Path.cwd()
+    except OSError:
+        console.print(
+            "[red]Could not resolve the current project directory.[/red] "
+            "Switch to a valid directory and retry."
+        )
+        raise typer.Exit(code=1) from None
+    ok, message = stop_sandbox(project_root=project_root)
+    if ok:
+        console.print(f"[green]{message}[/green]")
+        return
+    console.print(f"[yellow]{message}[/yellow]")
+    raise typer.Exit(code=1)
+
+
+def shell(
+    shell_path: str = typer.Option(
+        SANDBOX_DEFAULT_SHELL, "--shell-path", help="Shell executable inside sandbox."
+    ),
+) -> None:
+    """Attach an interactive shell to the current project's sandbox."""
+    _require_auth()
+    project_root, _constitution, _config = _load_project()
+    state = read_sandbox_state(project_root)
+    if not state:
+        console.print("[yellow]No sandbox found. Run `refactor start` first.[/yellow]")
+        raise typer.Exit(code=1)
+    if not sys.stdin.isatty():
+        console.print("[yellow]Non-interactive terminal; cannot attach shell.[/yellow]")
+        raise typer.Exit(code=1)
+    ok, message = attach_sandbox_shell(project_root=project_root, shell_path=shell_path)
+    if ok:
+        return
+    console.print(f"[red]Sandbox shell failed:[/red] {message}")
+    raise typer.Exit(code=1)
+
+
+def review(
+    target: str = typer.Argument(".", help="File, directory, or symbol to review."),
+    provider: str | None = typer.Option(
+        None,
+        "--provider",
+        help="Override provider for this run (takes precedence over env/constitution).",
+    ),
+    mode: str | None = typer.Option(
+        None,
+        "--mode",
+        help="Execution mode: auto | agentic | planner (default resolves from capability).",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Run review even if unapplied patches exist from a prior code run.",
+    ),
+) -> None:
+    """Run review (findings only) and store the result. Requires a valid key."""
+    _require_auth()
+    project_root, constitution, project_config = _load_project()
+    register_project(project_root, constitution_hash=constitution.content_hash)
+    _maybe_build_graph(project_root, project_config)
+    sandbox_ctx = None
+
+    try:
+        cloud = _is_cloud_mode(constitution)
+        if _sandbox_enabled(project_config):
+            if cloud:
+                console.print(
+                    "[dim]review: sandbox.enabled is ignored in cloud_managed mode.[/dim]"
+                )
+            else:
+                sandbox_ctx = _ensure_sandbox_ready(
+                    project_root=project_root,
+                    project_config=project_config,
+                    stage="review",
+                    auto_approve_install=False,
+                    no_install=False,
+                )
+        if cloud:
+            artifact = _cloud_inference(
+                stage="review",
+                project_root=project_root,
+                constitution=constitution,
+                target=target,
+                model_hint=provider,
+            )
+        else:
+            selected_provider = get_provider(
+                constitution, project_root=project_root, provider_name=provider
+            )
+            verbose_steps = bool(constitution.get_setting("agent_verbose_steps", True))
+            with console.status("[cyan]review[/cyan] preparing...", spinner="dots") as status:
+                progress_cb = _agent_progress_logger(
+                    "review", status=status, verbose_steps=verbose_steps
+                )
+                artifact = run_with_mode(
+                    project_root=project_root,
+                    constitution=constitution,
+                    provider=selected_provider,
+                    target=target,
+                    do_refactor=False,
+                    cli_mode=mode,
+                    progress_cb=progress_cb,
+                    step_limit_cb=_step_limit_prompt("review"),
+                )
+    except Exception as exc:  # provider/transport errors should not crash the CLI
+        console.print(f"[red]Review failed:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+    finally:
+        _teardown_sandbox_context(project_root, sandbox_ctx)
+
+    run_store = create_run(project_root, run_id=artifact.run_id)
+    run_store.write_artifact(artifact, target=target, status="completed")
+
+    _print_findings(artifact.findings)
+
+    # A fresh review supersedes prior refactor requests: replace them with one
+    # RR per finding (central-only; nothing is written into the project tree).
+    clear_requests(project_root)
+    requests = create_requests(project_root, artifact.findings, run_id=artifact.run_id)
+    if requests:
+        console.print(
+            f"\n[bold]Created {len(requests)} refactor request(s).[/bold] "
+            "[dim]Run `refactor code` to work through them one by one.[/dim]"
+        )
+
+    gate_color = "green" if artifact.gate.status == "passed" else "red"
+    mode_note = f" mode={artifact.execution_mode}" if artifact.execution_mode else ""
+    console.print(
+        f"\n[bold]gate[/bold]: [{gate_color}]{artifact.gate.status}[/{gate_color}] "
+        f"(high findings: {artifact.gate.high_severity_findings})  "
+        f"[dim]model={artifact.model_id}{mode_note} run={run_store.run_id}[/dim]"
+    )
+
+
+def code(
+    target: str = typer.Argument(".", help="File, directory, or symbol to refactor."),
+    apply: bool = typer.Option(False, "--apply", help="Apply approved patches in place."),
+    force: bool = typer.Option(False, "--force", help="Apply even if the quality gate blocks."),
+    provider: str | None = typer.Option(
+        None,
+        "--provider",
+        help="Override provider for this run (takes precedence over env/constitution).",
+    ),
+    mode: str | None = typer.Option(
+        None,
+        "--mode",
+        help="Execution mode: auto | agentic | planner (default resolves from capability).",
+    ),
+    auto_approve: bool = typer.Option(
+        False,
+        "--auto-approve",
+        help="Skip interactive issue approvals in agentic code mode.",
+    ),
+) -> None:
+    """Work through refactor requests one by one, applying & verifying each.
+
+    If no pending refactor requests exist, a review is run first to create them,
+    then code proceeds automatically with the first request. Requires a valid key.
+    """
+    _require_auth()
+    project_root, constitution, project_config = _load_project()
+    register_project(project_root, constitution_hash=constitution.content_hash)
+    _maybe_build_graph(project_root, project_config)
+    sandbox_ctx = None
+
+    try:
+        cloud = _is_cloud_mode(constitution)
+        sandbox_on = _sandbox_enabled(project_config)
+        if _sandbox_enabled(project_config):
+            if cloud:
+                console.print(
+                    "[dim]code: sandbox.enabled is ignored in cloud_managed mode.[/dim]"
+                )
+            else:
+                sandbox_ctx = _ensure_sandbox_ready(
+                    project_root=project_root,
+                    project_config=project_config,
+                    stage="code",
+                    auto_approve_install=auto_approve,
+                    no_install=False,
+                )
+        selected_provider = None
+        if not cloud:
+            selected_provider = get_provider(
+                constitution, project_root=project_root, provider_name=provider
+            )
+
+        # If no pending refactor requests exist, run review first to create them.
+        requests = pending_requests(project_root)
+        if not requests:
+            console.print("[dim]code: no pending refactor requests; running review first...[/dim]")
+            if cloud:
+                review_artifact = _cloud_inference(
+                    stage="review",
+                    project_root=project_root,
+                    constitution=constitution,
+                    target=target,
+                    model_hint=provider,
+                )
+            else:
+                with console.status("[cyan]review[/cyan] analyzing...", spinner="dots") as status:
+                    review_progress = _agent_progress_logger(
+                        "review", status=status, verbose_steps=True
+                    )
+                    review_artifact = run_with_mode(
+                        project_root=project_root,
+                        constitution=constitution,
+                        provider=selected_provider,
+                        target=target,
+                        do_refactor=False,
+                        cli_mode=mode,
+                        progress_cb=review_progress,
+                        step_limit_cb=_step_limit_prompt("review"),
+                    )
+            review_store = create_run(project_root, run_id=review_artifact.run_id)
+            review_store.write_artifact(review_artifact, target=target, status="completed")
+            _print_findings(review_artifact.findings)
+            clear_requests(project_root)
+            requests = create_requests(
+                project_root, review_artifact.findings, run_id=review_artifact.run_id
+            )
+            console.print(f"[bold]Created {len(requests)} refactor request(s).[/bold]")
+
+        if not requests:
+            console.print("[green]No issues to refactor.[/green]")
+            return
+
+        if cloud:
+            console.print(
+                f"[yellow]Created {len(requests)} refactor request(s).[/yellow] "
+                "The interactive apply-and-verify loop runs against a local provider; "
+                "configure a local provider/key to work through them with `refactor code`."
+            )
+            return
+
+        with console.status("[cyan]code[/cyan] running...", spinner="dots") as status:
+            artifact = run_refactor_requests(
+                project_root=project_root,
+                constitution=constitution,
+                provider=selected_provider,
+                requests=requests,
+                config=dict(getattr(project_config, "settings", {}) or {})
+                | ({"sandbox": {"enabled": True}} if sandbox_on else {})
+                or dict(getattr(constitution, "settings", {}) or {}),
+                progress_cb=_rr_progress_logger(status=status),
+                approval_cb=_rr_approval_prompt(auto_approve=auto_approve),
+            )
+    except Exception as exc:
+        console.print(f"[red]Refactor failed:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+    finally:
+        _teardown_sandbox_context(project_root, sandbox_ctx)
+
+    _print_rr_summary(artifact)
+    for note in getattr(artifact, "notes", []) or []:
+        console.print(f"[yellow]note:[/yellow] {note}")
+    gate_color = "green" if artifact.gate.status == "passed" else "red"
+    console.print(
+        f"\n[bold]result[/bold]: [{gate_color}]{artifact.gate.status}[/{gate_color}]  "
+        f"[dim]model={artifact.model_id} mode={artifact.execution_mode} run={artifact.run_id}[/dim]"
+    )
+
+
+def requests() -> None:
+    """List refactor requests and their status for this project."""
+    _require_auth()
+    project_root, _constitution, _config = _load_project()
+    rrs = list_requests(project_root)
+    if not rrs:
+        console.print("[dim]No refactor requests. Run `refactor review` to create them.[/dim]")
+        return
+    table = Table(title="Refactor requests", show_lines=False)
+    table.add_column("issue")
+    table.add_column("severity", no_wrap=True)
+    table.add_column("category")
+    table.add_column("status", no_wrap=True)
+    table.add_column("attempts", no_wrap=True)
+    color = {"applied": "green", "denied": "yellow", "failed": "red", "pending": "cyan", "in_progress": "cyan"}
+    for rr in rrs:
+        table.add_row(
+            rr.location,
+            rr.severity,
+            rr.category,
+            f"[{color.get(rr.status, 'white')}]{rr.status}[/{color.get(rr.status, 'white')}]",
+            str(rr.attempt_count),
+        )
+    console.print(table)
+
+
+def apply(
+    force: bool = typer.Option(False, "--force", help="Apply even if the quality gate blocks."),
+) -> None:
+    """Apply the latest run's patches in place (atomic, with backup). Requires a key."""
+    _require_auth()
+    project_root, constitution, project_config = _load_project()
+    run_dir = head_run_dir(project_root)
+    if not run_dir:
+        console.print("[yellow]No runs yet.[/yellow] Run `refactor code` first.")
+        raise typer.Exit(code=1)
+
+    patch_files = sorted((run_dir / "patches").glob("*.diff")) if (run_dir / "patches").is_dir() else []
+    if not patch_files:
+        console.print("[dim]No proposed patches in the latest run.[/dim]")
+        return
+
+    report = read_report(run_dir) or {}
+    gate_status = (report.get("gate") or {}).get("status", "unknown")
+    gate_mode = str(constitution.get_setting("gate_mode", "strict") or "strict")
+    diffs = [p.read_text(encoding="utf-8") for p in patch_files]
+    _apply_diffs(project_root, run_dir, diffs, gate_status, gate_mode, force, project_config)
+
+
+def revert() -> None:
+    """Restore files modified by the latest applied run from its backup."""
+    project_root, _, _ = _load_project()
+    run_dir = head_run_dir(project_root)
+    if not run_dir:
+        console.print("[yellow]No runs yet.[/yellow]")
+        raise typer.Exit(code=1)
+    try:
+        restored = revert_from_backup(project_root, run_dir)
+    except ApplyError as exc:
+        console.print(f"[yellow]Nothing to revert:[/yellow] {exc}")
+        raise typer.Exit(code=1) from exc
+    console.print(f"[green]Reverted[/green] {len(restored)} file(s): {', '.join(restored) or '(none)'}")
+
+
+def _apply_diffs(project_root, run_dir, diffs, gate_status, gate_mode, force, config=None) -> None:
+    if not diffs:
+        console.print("[dim]No patches to apply.[/dim]")
+        return
+    if gate_mode == "strict" and gate_status != "passed" and not force:
+        console.print(
+            f"[red]Apply blocked by quality gate[/red] (status={gate_status}). "
+            "Resolve high-severity findings or re-run with --force."
+        )
+        raise typer.Exit(code=1)
+
+    try:
+        changes = compute_file_changes(project_root, diffs)
+    except ApplyError as exc:
+        console.print(f"[red]Apply failed:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    settings = dict(getattr(config, "settings", {}) or {}) if config is not None else {}
+    if _verification_enabled(settings):
+        _apply_with_verification(project_root, run_dir, changes, settings)
+        return
+
+    try:
+        written = apply_changes(project_root, run_dir, changes)
+    except ApplyError as exc:
+        console.print(f"[red]Apply failed:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+    console.print(
+        f"[green]Applied[/green] {len(written)} file(s) in place: {', '.join(written)}. "
+        "Use `refactor revert` to undo."
+    )
+
+
+def _latest_unapplied_patch_run(project_root: Path) -> dict | None:
+    """Return newest run with unapplied patches, if any.
+
+    A run is considered pending when it has patch files and has not been marked
+    as applied in its `applied.json` marker.
+    """
+    for run_dir in list_runs(project_root):
+        patch_files = sorted((run_dir / "patches").glob("*.diff")) if (run_dir / "patches").is_dir() else []
+        if not patch_files:
+            continue
+        marker = read_marker(run_dir)
+        if marker and marker.get("status") == "applied":
+            continue
+        report = read_report(run_dir) or {}
+        return {
+            "run_id": report.get("run_id", run_dir.name),
+            "run_dir": run_dir,
+            "patch_count": len(patch_files),
+        }
+    return None
+
+
+def _verification_enabled(settings: dict) -> bool:
+    verification = settings.get("verification")
+    if not isinstance(verification, dict):
+        return False
+    return bool(
+        verification.get("syntax", True)
+        or verification.get("semantic", "auto") not in (False, "off")
+        or (verification.get("tests", {}) or {}).get("command")
+    )
+
+
+def _apply_with_verification(project_root, run_dir, changes, settings) -> None:
+    try:
+        from refactor_core.codeintel.verification import apply_and_verify
+    except Exception:
+        # codeintel unavailable: fall back to plain apply.
+        written = apply_changes(project_root, run_dir, changes)
+        console.print(f"[green]Applied[/green] {len(written)} file(s) (verification unavailable).")
+        return
+
+    try:
+        result = apply_and_verify(project_root, run_dir, changes, config=settings)
+    except ApplyError as exc:
+        console.print(f"[red]Apply failed:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    for rung in result.rungs:
+        if not rung.ran:
+            continue
+        color = "green" if rung.passed else "red"
+        console.print(f"  [{color}]verify:{rung.name}[/{color}] {'ok' if rung.passed else 'failed'}")
+        for detail in rung.details[:5]:
+            console.print(f"    [dim]{detail}[/dim]")
+
+    if result.passed:
+        console.print(
+            f"[green]Applied + verified[/green] {len(result.changed_files)} file(s): "
+            f"{', '.join(result.changed_files)}. Use `refactor revert` to undo."
+        )
+    else:
+        rolled = "rolled back" if result.rolled_back else "NOT rolled back (manual revert needed)"
+        console.print(f"[red]Verification failed[/red]; changes {rolled}.")
+        raise typer.Exit(code=1)
+
+
+def status() -> None:
+    """Show the latest run and its gate result."""
+    project_root, _, _ = _load_project()
+    run_dir = head_run_dir(project_root)
+    if not run_dir:
+        console.print(f"Project: {project_root}")
+        console.print("[dim]No runs yet. Run `refactor review` to create one.[/dim]")
+        return
+
+    report = read_report(run_dir) or {}
+    console.print(f"Project: {project_root}")
+    console.print(f"Latest run: [bold]{report.get('run_id', run_dir.name)}[/bold] ({report.get('created_at', '?')})")
+    console.print(f"Target: {report.get('target', '?')}  |  Summary: {report.get('summary', '')}")
+    gate = report.get("gate", {})
+    gate_status = gate.get("status", "unknown")
+    gate_color = "green" if gate_status == "passed" else "red"
+    console.print(
+        f"Findings: {report.get('findings_count', 0)}  |  "
+        f"Gate: [{gate_color}]{gate_status}[/{gate_color}]"
+    )
+    if report.get("rule_source"):
+        console.print(
+            "Rule trace: "
+            f"source={report.get('rule_source')} "
+            f"pattern={report.get('rule_pattern', '')} "
+            f"hash={str(report.get('rule_hash', ''))[:12]}"
+        )
+
+
+def _is_git_repo(project_root: Path) -> bool:
+    proc = subprocess.run(
+        ["git", "-C", str(project_root), "rev-parse", "--is-inside-work-tree"],
+        capture_output=True,
+        text=True,
+    )
+    return proc.returncode == 0 and proc.stdout.strip().lower() == "true"
+
+
+def _git_diff_text(project_root: Path, *, staged: bool) -> str:
+    cmd = ["git", "-C", str(project_root), "diff"]
+    if staged:
+        cmd.append("--staged")
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        return ""
+    return proc.stdout or ""
+
+
+def diff() -> None:
+    """Show proposed diffs, or applied RR diffs/summary for latest run."""
+    project_root, _, _ = _load_project()
+    run_dir = head_run_dir(project_root)
+    if not run_dir:
+        console.print("[dim]No runs yet.[/dim]")
+        return
+    report = read_report(run_dir) or {}
+    patches = sorted((run_dir / "patches").glob("*.diff")) if (run_dir / "patches").is_dir() else []
+    if patches:
+        for patch in patches:
+            console.print(f"[bold]{patch.name}[/bold]")
+            console.print(patch.read_text(encoding="utf-8"))
+        return
+
+    mode = str(report.get("execution_mode", "") or "")
+    trace = report.get("agent_trace_summary", {})
+    if not isinstance(trace, dict):
+        trace = {}
+    applied_count = int(trace.get("applied", 0) or 0)
+    if mode == "rr" and applied_count > 0:
+        if _is_git_repo(project_root):
+            unstaged = _git_diff_text(project_root, staged=False)
+            staged = _git_diff_text(project_root, staged=True)
+            if unstaged.strip() or staged.strip():
+                console.print("[bold]Applied changes (git working tree)[/bold]")
+                console.print("\n[bold]Unstaged changes[/bold]")
+                console.print(unstaged.strip() or "[dim](none)[/dim]")
+                console.print("\n[bold]Staged changes[/bold]")
+                console.print(staged.strip() or "[dim](none)[/dim]")
+                return
+        outcomes = trace.get("outcomes", [])
+        if not isinstance(outcomes, list):
+            outcomes = []
+        locations = []
+        for item in outcomes:
+            if not isinstance(item, dict):
+                continue
+            if str(item.get("outcome", "")) != "applied":
+                continue
+            location = str(item.get("location", "") or "").strip()
+            if location:
+                locations.append(location)
+        if locations:
+            console.print("[bold]Applied changes (RR run)[/bold]")
+            for location in locations:
+                console.print(f"  - {location}")
+            console.print("[dim]Tip: use `git diff` for line-by-line working-tree details.[/dim]")
+            return
+
+    console.print(
+        "[dim]No proposed changes in the latest run. "
+        "Run `refactor code .` to generate patches, then `refactor diff` again.[/dim]"
+    )
+
+
+def gc(
+    keep: int = typer.Option(20, "--keep", help="Number of most recent runs to retain."),
+) -> None:
+    """Prune old runs from the central store (keeps HEAD and the newest --keep)."""
+    project_root, _, _ = _load_project()
+    before = len(list_runs(project_root))
+    removed = prune_runs(project_root, keep=keep)
+    console.print(
+        f"[green]Pruned[/green] {len(removed)} run(s); kept {before - len(removed)} "
+        f"under {project_store_dir(project_root)}."
+    )
+
+
+def check(
+    strict: bool = typer.Option(False, "--strict", help="Exit non-zero if issues are found (for CI)."),
+) -> None:
+    """Check the constitution for committed secrets (developer/provider keys)."""
+    files = find_project_files()
+    if not files:
+        console.print(f"[yellow]Missing {CONSTITUTION_FILENAME} or {CONFIG_FILENAME}.[/yellow]")
+        raise typer.Exit(code=1 if strict else 0)
+    consti_path, config_path = files
+    constitution = load_constitution(consti_path)
+    config = load_config(config_path)
+    findings = raw_secret_matches(constitution) + raw_secret_matches_config(config)
+    if findings:
+        kinds = ", ".join(sorted({kind for kind, _ in findings}))
+        console.print(
+            f"[red]Found literal secret-like value(s)[/red] ({kinds}) in "
+            f"{consti_path} or {config_path}. Replace secrets with `${{ENV_VAR}}` references."
+        )
+        raise typer.Exit(code=1 if strict else 0)
+    console.print("[green]OK[/green]: no committed secret-like literals detected.")
+
+
+def _mask_secret(value: str) -> str:
+    value = value.strip()
+    if len(value) <= 8:
+        return "set (****)"
+    return f"set ({value[:4]}…{value[-4:]})"
+
+
+def _print_detected_credentials(provider_name: str) -> None:
+    """Show masked presence of resolved provider credentials (never the value)."""
+    for req in _REQUIRED_ENV_BY_PROVIDER.get(provider_name, []):
+        names = req if isinstance(req, tuple) else (str(req),)
+        for name in names:
+            raw = os.environ.get(name, "").strip()
+            if raw:
+                console.print(f"  [dim]{name}[/dim]: {_mask_secret(raw)}")
+                break
+
+
+def _missing_requirements(provider_name: str) -> list[str]:
+    requirements = _REQUIRED_ENV_BY_PROVIDER.get(provider_name, [])
+    missing: list[str] = []
+    for req in requirements:
+        if isinstance(req, tuple):
+            if not any(os.environ.get(name, "").strip() for name in req):
+                missing.append(" or ".join(req))
+        else:
+            if not os.environ.get(str(req), "").strip():
+                missing.append(str(req))
+    return missing
+
+
+def doctor(
+    provider: str | None = typer.Option(
+        None,
+        "--provider",
+        help="Provider override for diagnostics (default resolves from env/constitution).",
+    ),
+    skip_ping: bool = typer.Option(
+        False,
+        "--skip-ping",
+        help="Only validate configuration; do not call provider endpoint.",
+    ),
+    sandbox: bool = typer.Option(
+        False,
+        "--sandbox",
+        help="Show local sandbox diagnostics and persisted preflight/install history.",
+    ),
+) -> None:
+    """Preflight provider diagnostics: auth status, env checks, and live provider ping."""
+    files = find_project_files()
+    if not files:
+        console.print(
+            f"[yellow]Missing {CONSTITUTION_FILENAME} or {CONFIG_FILENAME}.[/yellow] "
+            "Run `refactor init` first."
+        )
+        raise typer.Exit(code=1)
+    consti_path, _ = files
+    constitution = load_constitution(consti_path)
+    project_config = load_config(consti_path.parent / CONFIG_FILENAME)
+    project_root = consti_path.parent
+
+    if sandbox:
+        _report_sandbox(project_root, project_config)
+        return
+
+    mode = str(constitution.get_setting("mode", "local") or "local")
+    provider_name = resolve_provider_name(constitution, provider_name=provider)
+
+    console.print(f"[bold]project[/bold]: {project_root}")
+    console.print(f"[bold]mode[/bold]: {mode}")
+    console.print(f"[bold]provider[/bold]: {provider_name}")
+    console.print(f"[bold]supported[/bold]: {', '.join(supported_providers())}")
+
+    try:
+        auth_ctx = ensure_authenticated(project_root)
+        cache_note = " (cached)" if auth_ctx.cached else ""
+        console.print(f"[green]developer key[/green]: OK account={auth_ctx.account_id}{cache_note}")
+    except AuthError as exc:
+        console.print(f"[yellow]developer key[/yellow]: {exc}")
+
+    missing = _missing_requirements(provider_name)
+    if missing:
+        console.print("[red]provider env[/red]: missing required values:")
+        for item in missing:
+            console.print(f"  - {item}")
+        raise typer.Exit(code=1)
+    console.print("[green]provider env[/green]: OK")
+    _print_detected_credentials(provider_name)
+
+    try:
+        selected = get_provider(constitution, project_root=project_root, provider_name=provider)
+    except Exception as exc:
+        console.print(f"[red]provider resolution failed[/red]: {exc}")
+        raise typer.Exit(code=1) from exc
+
+    capabilities = resolve_capabilities(selected, dict(getattr(constitution, "settings", {}) or {}))
+    resolution = resolve_mode(
+        capabilities,
+        config_mode=constitution.get_setting("agent_mode"),
+    )
+    console.print(
+        f"[bold]model[/bold]: {getattr(selected, 'model_id', 'unknown')}  "
+        f"(supports_refactor={getattr(selected, 'supports_refactor', True)})"
+    )
+    console.print(
+        f"[bold]capabilities[/bold]: supports_tools={capabilities.supports_tools} "
+        f"context_window={capabilities.context_window} "
+        f"max_output_tokens={capabilities.max_output_tokens} "
+        f"[dim](source={capabilities.source})[/dim]"
+    )
+    budget = compute_budget(
+        capabilities,
+        ratio=float(constitution.get_setting("context_budget_ratio", 0.55) or 0.55),
+    )
+    console.print(
+        f"[bold]execution mode[/bold]: {resolution.mode} "
+        f"[dim](requested={resolution.requested}, source={resolution.source})[/dim]"
+    )
+    console.print(
+        f"[bold]context budget[/bold]: input={budget.input_budget_tokens} tokens, "
+        f"reserved_output={budget.reserved_output_tokens} tokens"
+    )
+
+    _report_intelligence(project_root)
+
+    if skip_ping:
+        console.print("[dim]Skipping provider live ping (--skip-ping).[/dim]")
+        return
+
+    try:
+        _ = selected.review(
+            [{"path": "__doctor__.txt", "language": "text", "chunk_text": "doctor ping"}],
+            constitution,
+            1,
+        )
+    except Exception as exc:
+        console.print(f"[red]provider ping failed[/red]: {exc}")
+        raise typer.Exit(code=1) from exc
+    console.print("[green]provider ping[/green]: OK")
+
+
+def config() -> None:
+    """Show resolved settings from refactor.config and environment interpolation."""
+    files = find_project_files()
+    if not files:
+        console.print(
+            f"[yellow]Missing {CONSTITUTION_FILENAME} or {CONFIG_FILENAME}.[/yellow] "
+            "Run `refactor init` first."
+        )
+        raise typer.Exit(code=1)
+    consti_path, config_path = files
+    constitution = load_constitution(consti_path, config_path=config_path)
+    parsed_config = load_config(config_path)
+    console.print(f"[bold]constitution[/bold]: {consti_path}")
+    console.print(f"[bold]config[/bold]: {config_path}")
+    safe_settings = dict(parsed_config.settings)
+    if "developer_key" in safe_settings:
+        safe_settings["developer_key"] = "<set>" if safe_settings["developer_key"] else "<empty>"
+    for key, value in safe_settings.items():
+        console.print(f"  {key}: {value}")
+
+
+def _report_intelligence(project_root: Path) -> None:
+    """Report Tree-sitter grammars, LSP servers, and last graph build (R10)."""
+    try:
+        from refactor_core.codeintel.parsing import available_languages, tree_sitter_available
+        from refactor_core.codeintel.lsp import detect_servers
+        from refactor_core.store import read_symbol_graph
+    except Exception as exc:  # codeintel optional
+        console.print(f"[dim]code intelligence unavailable: {exc}[/dim]")
+        return
+
+    ts = tree_sitter_available()
+    ts_color = "green" if ts else "yellow"
+    console.print(
+        f"[{ts_color}]tree-sitter[/{ts_color}]: "
+        f"{'available' if ts else 'not installed (byte/line fallback)'}; "
+        f"languages={', '.join(available_languages())}"
+    )
+
+    servers = detect_servers()
+    present = sorted({v['name'] for v in servers.values() if v['present']})
+    missing = sorted({v['name'] for v in servers.values() if not v['present']})
+    console.print(f"[bold]lsp servers[/bold]: present={', '.join(present) or '(none)'}")
+    if missing:
+        console.print(f"  [dim]missing: {', '.join(missing)}[/dim]")
+
+    graph = read_symbol_graph(project_root)
+    if graph:
+        symbols = len(graph.get("symbols", []))
+        edges = len(graph.get("edges", []))
+        files = len(graph.get("files", {}))
+        console.print(
+            f"[bold]symbol graph[/bold]: {files} file(s), {symbols} symbol(s), {edges} edge(s)"
+        )
+    else:
+        console.print("[dim]symbol graph: not built yet (runs build it incrementally)[/dim]")
+
+
+def _report_sandbox(project_root: Path, config) -> None:
+    """Report local sandbox runtime state, latest preflight, and install history."""
+    settings = dict(getattr(config, "settings", {}) or {})
+    sandbox_cfg = settings.get("sandbox", {})
+    if not isinstance(sandbox_cfg, dict):
+        sandbox_cfg = {}
+    enabled = True
+    runtime_pref = str(sandbox_cfg.get("runtime", "podman") or "podman")
+    image = str(sandbox_cfg.get("image") or SANDBOX_DEFAULT_IMAGE)
+    resolved_runtime, reason = resolve_runtime(runtime_pref)
+
+    console.print(f"[bold]project[/bold]: {project_root}")
+    console.print(f"[bold]sandbox enabled[/bold]: {enabled} [dim](mandatory for local runs)[/dim]")
+    console.print(f"[bold]runtime pref[/bold]: {runtime_pref}")
+    if resolved_runtime:
+        console.print(f"[green]runtime[/green]: {resolved_runtime}")
+    else:
+        console.print(f"[red]runtime[/red]: unavailable ({reason})")
+    console.print(f"[bold]image[/bold]: {image}")
+
+    state = read_sandbox_state(project_root)
+    if not state:
+        console.print("[dim]sandbox state: not initialized (run `refactor start`).[/dim]")
+    else:
+        console.print(
+            f"[bold]sandbox state[/bold]: status={state.get('status', '?')} "
+            f"container={state.get('container_name', '?')} "
+            f"updated_at={state.get('updated_at', '?')}"
+        )
+
+    preflight = read_sandbox_preflight(project_root)
+    if not preflight:
+        console.print("[dim]preflight: none recorded yet.[/dim]")
+    else:
+        status = str(preflight.get("status", "unknown"))
+        color = "green" if status == "passed" else "red"
+        console.print(
+            f"[bold]preflight[/bold]: [{color}]{status}[/{color}] "
+            f"reason={preflight.get('reason', '?')} "
+            f"cmd={preflight.get('test_command', '(none)')}"
+        )
+
+    installs = read_sandbox_install_history(project_root)
+    if not installs:
+        console.print("[dim]install history: none.[/dim]")
+        return
+    latest = installs[-1]
+    console.print(
+        f"[bold]install history[/bold]: {len(installs)} entr{'y' if len(installs) == 1 else 'ies'} "
+        f"(latest at {latest.get('at', '?')})"
+    )
+    if isinstance(latest.get("plan"), list):
+        console.print(f"  [dim]latest plan steps: {len(latest.get('plan', []))}[/dim]")
+    if isinstance(latest.get("results"), list):
+        failures = sum(1 for r in latest.get("results", []) if not r.get("ok"))
+        console.print(f"  [dim]latest command results: {len(latest.get('results', []))} (failures={failures})[/dim]")
+
+
+def _maybe_build_graph(project_root: Path, config) -> None:
+    """Build + persist the symbol graph when intelligence.graph is enabled."""
+    settings = dict(getattr(config, "settings", {}) or {})
+    intel = settings.get("intelligence", {})
+    if not isinstance(intel, dict) or not intel.get("graph", True) or not intel.get("enabled", True):
+        return
+    try:
+        from refactor_core.codeintel.graph import build_symbol_graph
+        from refactor_core.codeintel.lsp import LspManager
+        from refactor_core.store import write_symbol_graph
+
+        excludes = set(settings.get("exclude", []) or [])
+        lsp_mode = str(intel.get("lsp", "auto"))
+        lsp_manager = LspManager(project_root, mode=lsp_mode) if lsp_mode != "off" else None
+        graph = build_symbol_graph(project_root, ".", excludes=excludes, lsp_manager=lsp_manager)
+        write_symbol_graph(project_root, graph.to_dict())
+    except Exception:
+        pass  # graph is best-effort; never block a run
+
+
+def _print_rr_summary(artifact) -> None:
+    """Per-RR outcome table from the RR run's trace summary."""
+    trace = getattr(artifact, "agent_trace_summary", {}) or {}
+    outcomes = trace.get("outcomes", []) or []
+    if not outcomes:
+        console.print("[dim]No refactor requests processed.[/dim]")
+        return
+    table = Table(title="Refactor request outcomes", show_lines=False)
+    table.add_column("issue")
+    table.add_column("outcome", no_wrap=True)
+    table.add_column("attempts", no_wrap=True)
+    color = {"applied": "green", "denied": "yellow", "failed": "red"}
+    for o in outcomes:
+        outcome = str(o.get("outcome", "?"))
+        table.add_row(
+            str(o.get("location", "?")),
+            f"[{color.get(outcome, 'white')}]{outcome}[/{color.get(outcome, 'white')}]",
+            str(o.get("attempts", 0)),
+        )
+    console.print(table)
+    console.print(
+        f"[dim]applied={trace.get('applied', 0)} denied={trace.get('denied', 0)} "
+        f"failed={trace.get('failed', 0)}[/dim]"
+    )
+
+
+def _print_patches(patches) -> None:
+    if not patches:
+        return
+    table = Table(title="Proposed patches", show_lines=False)
+    table.add_column("group")
+    table.add_column("risk", no_wrap=True)
+    table.add_column("files")
+    for patch in patches:
+        files = ", ".join(patch.metadata.get("affected_files", [])) if patch.metadata else ""
+        table.add_row(patch.group_name, str(patch.risk_score), files)
+    console.print(table)
+
+
+def _print_findings(findings) -> None:
+    if not findings:
+        console.print("[green]No findings.[/green]")
+        return
+    table = Table(title="Findings", show_lines=False)
+    table.add_column("severity", no_wrap=True)
+    table.add_column("category")
+    table.add_column("file:symbol")
+    table.add_column("recommendation")
+    for finding in findings:
+        style = _SEVERITY_STYLE.get(finding.severity, "white")
+        location = finding.file_path + (f":{finding.symbol}" if finding.symbol else "")
+        table.add_row(
+            f"[{style}]{finding.severity}[/{style}]",
+            finding.category,
+            location,
+            finding.recommendation,
+        )
+    console.print(table)