ltcai 0.1.9 → 0.1.16

package/server.py

@@ -11,6 +11,7 @@ import io
 import json
 import logging
 import os
+import platform
 import re
 import secrets
 import threading
@@ -19,6 +20,8 @@ import subprocess
 import sys
 import tempfile
 import time
+import urllib.error
+import urllib.request
 from contextlib import asynccontextmanager
 from pathlib import Path
 
@@ -29,7 +32,8 @@ try:
 except Exception as e:
     print(f"⚠️ MLX Metal context unavailable: {e}")
     mx = None
-from typing import AsyncIterator, Optional, List, Dict
+from enum import Enum
+from typing import AsyncIterator, Optional, List, Dict, TypedDict
 
 import uvicorn
 from fastapi import FastAPI, File, HTTPException, Request, Cookie, UploadFile
@@ -39,7 +43,7 @@ from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel
 from PIL import Image
 
-from llm_router import AsyncOpenAI, LLMRouter, OPENAI_COMPATIBLE_PROVIDERS, parse_model_ref, mx, normalize_branding
+from llm_router import AsyncOpenAI, LLMRouter, OPENAI_COMPATIBLE_PROVIDERS, HF_MODELS_ROOT, ensure_mlx_runtime, hf_model_dir, parse_model_ref, mx, normalize_branding
 from knowledge_graph import KnowledgeGraphStore
 from p_reinforce import BRAIN_DIR, PReinforceGardener
 from setup import get_recommendations, install_stream, open_url, scan_environment
@@ -65,12 +69,14 @@ from tools import (
     read_document,
     deploy_project,
     desktop_bridge_status,
+    edit_file,
     ensure_agent_root,
     execute_tool,
     git_diff,
     git_log,
     git_show,
     git_status,
+    grep,
     inspect_html,
     knowledge_save,
     knowledge_search,
@@ -87,6 +93,8 @@ from tools import (
     read_file,
     run_command,
     search_files,
+    todo_read,
+    todo_write,
     workspace_tree,
     write_file,
 )
@@ -99,19 +107,15 @@ except Exception:
 from datetime import datetime
 
 def detect_language(text: str) -> str:
-    """Detect language: 'ko' (Korean), 'zh' (Chinese), or 'en' (English)."""
+    """Detect language: 'ko' (Korean) or 'en' (English)."""
     total = max(len(text), 1)
     ko = sum(1 for c in text if '가' <= c <= '힣')
-    zh = sum(1 for c in text if '一' <= c <= '鿿')
     if ko / total > 0.05:
         return "ko"
-    if zh / total > 0.05:
-        return "zh"
     return "en"
 
 _LANG_HINT = {
     "ko": "Respond in Korean (한국어로 답변하세요).",
-    "zh": "Respond in Chinese (用中文回答).",
     "en": "Respond in English.",
 }
 
@@ -259,6 +263,30 @@ def _persist_sessions(sessions: Dict[str, tuple]) -> None:
 
 _sessions: Dict[str, tuple] = _load_sessions()
 
+# ── Rate limiting ─────────────────────────────────────────────────────────────
+_rate_windows: dict[tuple[str, str], list[float]] = {}
+_rate_lock = threading.Lock()
+
+def _check_rate_limit(ip: str, action: str, max_calls: int, window_secs: float) -> None:
+    key = (ip, action)
+    now = time.time()
+    cutoff = now - window_secs
+    with _rate_lock:
+        calls = [t for t in _rate_windows.get(key, []) if t > cutoff]
+        if len(calls) >= max_calls:
+            raise HTTPException(status_code=429, detail="요청이 너무 많습니다. 잠시 후 다시 시도하세요.")
+        calls.append(now)
+        _rate_windows[key] = calls
+
+def _client_ip(request: Request) -> str:
+    for header in ("CF-Connecting-IP", "X-Forwarded-For"):
+        val = request.headers.get(header)
+        if val:
+            return val.split(",")[0].strip()
+    return request.client.host if request.client else "unknown"
+
+# ─────────────────────────────────────────────────────────────────────────────
+
 def create_session(email: str) -> str:
     token = secrets.token_urlsafe(32)
     with _sessions_lock:
@@ -1526,6 +1554,13 @@ async def lifespan(app: FastAPI):
         yield
     finally:
         router.unload_all()
+        for proc in LOCAL_SERVER_PROCESSES.values():
+            try:
+                if proc.poll() is None:
+                    proc.terminate()
+                    proc.wait(timeout=5)
+            except Exception:
+                pass
 
 app = FastAPI(title=f"Lattice AI Server ({APP_MODE})", version="2.1.0", lifespan=lifespan)
 
@@ -1551,23 +1586,34 @@ if _ICONS_DIR.exists():
 ensure_agent_root()
 app.mount("/agent-files", StaticFiles(directory=str(AGENT_ROOT)), name="agent-files")
 
+OPEN_REGISTRATION = env_bool("LATTICEAI_OPEN_REGISTRATION", default=True)
+
 @app.post("/register")
-async def register(req: UserRegister):
+async def register(req: UserRegister, request: Request):
+    # 5 registration attempts per IP per hour
+    _check_rate_limit(_client_ip(request), "register", max_calls=5, window_secs=3600)
+    if not OPEN_REGISTRATION:
+        raise HTTPException(status_code=403, detail="회원가입이 비활성화되어 있습니다. 관리자에게 문의하세요.")
     users = load_users()
     if req.email in users:
         raise HTTPException(status_code=400, detail="이미 존재하는 이메일입니다.")
+    # First user to register on a fresh server becomes admin automatically
+    role = "admin" if not users else "user"
     users[req.email] = {
         "password": hash_password(req.password),
         "name": req.name,
         "nickname": req.nickname,
-        "role": "user",
+        "role": role,
         "disabled": False,
     }
     save_users(users)
-    return {"status": "ok", "message": "회원가입 성공!"}
+    msg = "회원가입 성공! 첫 번째 사용자로 관리자 권한이 부여되었습니다." if role == "admin" else "회원가입 성공!"
+    return {"status": "ok", "message": msg, "role": role}
 
 @app.post("/login")
-async def login(req: UserLogin):
+async def login(req: UserLogin, request: Request):
+    # 10 login attempts per IP per 5 minutes
+    _check_rate_limit(_client_ip(request), "login", max_calls=10, window_secs=300)
     users = load_users()
     user = users.get(req.email)
     if not user or not verify_and_migrate_password(req.email, req.password, user.get("password", ""), users):
@@ -1964,6 +2010,11 @@ class SetApiKeyRequest(BaseModel):
 class PullModelRequest(BaseModel):
     model: str
 
+class PrepareModelRequest(BaseModel):
+    model: str
+    engine: Optional[str] = None
+    user_email: Optional[str] = None
+
 class VerifyCloudRequest(BaseModel):
     force: bool = False
     provider: Optional[str] = None
@@ -1978,12 +2029,48 @@ class AgentRequest(BaseModel):
     message: str
     conversation_id: Optional[str] = None
     source: Optional[str] = None
-    max_steps: int = 6
+    max_steps: int = 25
     temperature: float = 0.1
     user_email: Optional[str] = None
     user_nickname: Optional[str] = None
 
 
+class AgentEvalRequest(BaseModel):
+    skill: str
+    case_id: Optional[str] = None
+
+
+class AgentState(str, Enum):
+    IDLE             = "IDLE"
+    PLANNING         = "PLANNING"
+    WAITING_APPROVAL = "WAITING_APPROVAL"
+    EXECUTING        = "EXECUTING"
+    VERIFYING        = "VERIFYING"
+    FAILED           = "FAILED"
+    ROLLBACK         = "ROLLBACK"
+    DONE             = "DONE"
+
+
+# Terminal states — the agent loop exits when reaching one of these
+AGENT_TERMINAL_STATES = frozenset({AgentState.DONE, AgentState.FAILED})
+
+
+class AgentRunContext:
+    """Mutable state carrier passed through all agent phases."""
+    __slots__ = ("state", "plan", "transcript", "retry_count",
+                 "state_history", "corrections", "final_message", "rollback_log")
+
+    def __init__(self) -> None:
+        self.state:         AgentState = AgentState.IDLE
+        self.plan:          dict       = {}
+        self.transcript:    list       = []
+        self.retry_count:   int        = 0
+        self.state_history: list       = []
+        self.corrections:   list       = []
+        self.final_message: str        = ""
+        self.rollback_log:  list       = []
+
+
 class ToolPathRequest(BaseModel):
     path: str = "."
 
@@ -2009,6 +2096,33 @@ class ToolSearchFilesRequest(BaseModel):
     max_results: int = 20
 
 
+class ToolReadFileRequest(BaseModel):
+    path: str
+    offset: int = 0
+    limit: int = 0
+    line_numbers: bool = True
+
+
+class ToolEditFileRequest(BaseModel):
+    path: str
+    old_string: str
+    new_string: str
+    replace_all: bool = False
+
+
+class ToolGrepRequest(BaseModel):
+    pattern: str
+    path: str = "."
+    glob: Optional[str] = None
+    max_results: int = 50
+    case_insensitive: bool = False
+    context_lines: int = 0
+
+
+class ToolTodoWriteRequest(BaseModel):
+    todos: List[Dict] = []
+
+
 class ToolWorkspaceTreeRequest(BaseModel):
     path: str = "."
     max_depth: int = 3
@@ -2171,6 +2285,7 @@ ENGINE_MODEL_CATALOG = {
         {"id": "ollama:llama3.1:70b", "name": "Llama 3.1 70B via Ollama", "family": "Llama 3.1", "tag": "local-server", "size": "pull required", "pullable": True},
     ],
     "vllm": [
+        {"id": "vllm:Qwen/Qwen2.5-0.5B-Instruct-AWQ", "name": "Qwen 2.5 0.5B AWQ via vLLM", "family": "Qwen 2.5", "tag": "local-light", "size": "0.5B", "pullable": True},
         {"id": "vllm:google/gemma-2-2b", "name": "Gemma 2 2B Base via vLLM", "family": "Gemma", "tag": "local-server", "size": "server model", "pullable": True},
         {"id": "vllm:google/gemma-2-2b-it", "name": "Gemma 2 2B via vLLM", "family": "Gemma", "tag": "local-server", "size": "server model", "pullable": True},
         {"id": "vllm:google/gemma-2-9b", "name": "Gemma 2 9B Base via vLLM", "family": "Gemma", "tag": "local-server", "size": "server model", "pullable": True},
@@ -2186,6 +2301,7 @@ ENGINE_MODEL_CATALOG = {
         {"id": "vllm:meta-llama/Llama-3.1-70B-Instruct", "name": "Llama 3.1 70B via vLLM", "family": "Llama 3.1", "tag": "local-server", "size": "server model", "pullable": True},
     ],
     "lmstudio": [
+        {"id": "lmstudio:https://huggingface.co/lmstudio-community/Qwen2.5-0.5B-Instruct-GGUF", "name": "Qwen 2.5 0.5B GGUF via LM Studio", "family": "Qwen 2.5", "tag": "local-light", "size": "0.5B", "pullable": True},
         {"id": "lmstudio:google/gemma-2-2b-it", "name": "Gemma 2 2B via LM Studio", "family": "Gemma", "tag": "local-server", "size": "server model", "pullable": True},
         {"id": "lmstudio:google/gemma-2-9b-it", "name": "Gemma 2 9B via LM Studio", "family": "Gemma", "tag": "local-server", "size": "server model", "pullable": True},
         {"id": "lmstudio:Qwen/Qwen2.5-3B-Instruct", "name": "Qwen 2.5 3B via LM Studio", "family": "Qwen 2.5", "tag": "local-server", "size": "server model", "pullable": True},
@@ -2199,9 +2315,9 @@ ENGINE_MODEL_CATALOG = {
         {"id": "lmstudio:meta-llama/Llama-3.1-70B-Instruct", "name": "Llama 3.1 70B via LM Studio", "family": "Llama 3.1", "tag": "local-server", "size": "server model", "pullable": True},
     ],
     "llamacpp": [
+        {"id": "llamacpp:lmstudio-community/Qwen2.5-0.5B-Instruct-GGUF", "name": "Qwen 2.5 0.5B GGUF via llama.cpp", "family": "Qwen 2.5", "tag": "gguf-q4", "size": "0.5B", "pullable": True},
         {"id": "llamacpp:unsloth/gemma-2-2b-it-GGUF", "name": "Gemma 2 2B GGUF via llama.cpp", "family": "Gemma", "tag": "gguf-q4", "size": "gguf", "pullable": True},
         {"id": "llamacpp:unsloth/gemma-2-9b-it-GGUF", "name": "Gemma 2 9B GGUF via llama.cpp", "family": "Gemma", "tag": "gguf-q4", "size": "gguf", "pullable": True},
-        {"id": "llamacpp:Qwen/Qwen2.5-3B-Instruct-GGUF", "name": "Qwen 2.5 3B GGUF via llama.cpp", "family": "Qwen 2.5", "tag": "gguf-q4", "size": "gguf", "pullable": True},
         {"id": "llamacpp:Qwen/Qwen2.5-7B-Instruct-GGUF", "name": "Qwen 2.5 7B GGUF via llama.cpp", "family": "Qwen 2.5", "tag": "local-server", "size": "gguf", "pullable": True},
         {"id": "llamacpp:Qwen/Qwen2.5-14B-Instruct-GGUF", "name": "Qwen 2.5 14B GGUF via llama.cpp", "family": "Qwen 2.5", "tag": "local-server", "size": "gguf", "pullable": True},
         {"id": "llamacpp:Qwen/Qwen2.5-32B-Instruct-GGUF", "name": "Qwen 2.5 32B GGUF via llama.cpp", "family": "Qwen 2.5", "tag": "gguf-q4", "size": "gguf", "pullable": True},
@@ -2228,6 +2344,299 @@ def _update_env_file(env_file: Path, key: str, value: str) -> None:
     env_file.write_text("\n".join(lines) + "\n", encoding="utf-8")
 
 
+LOCAL_SERVER_PROCESSES: Dict[str, subprocess.Popen] = {}
+VLLM_METAL_ENV = Path.home() / ".venv-vllm-metal"
+VLLM_METAL_BIN = VLLM_METAL_ENV / "bin" / "vllm"
+VLLM_METAL_PYTHON = VLLM_METAL_ENV / "bin" / "python"
+LMSTUDIO_BUNDLED_CLI = Path("/Applications/LM Studio.app/Contents/Resources/app/.webpack/lms")
+
+def find_lmstudio_cli() -> Optional[str]:
+    cli = shutil.which("lms")
+    if cli:
+        return cli
+    if LMSTUDIO_BUNDLED_CLI.exists():
+        return str(LMSTUDIO_BUNDLED_CLI)
+    return None
+
+
+def vllm_executable() -> Optional[str]:
+    found = shutil.which("vllm")
+    if found:
+        return found
+    if VLLM_METAL_BIN.exists():
+        return str(VLLM_METAL_BIN)
+    return None
+
+
+def vllm_metal_python() -> Optional[str]:
+    if VLLM_METAL_PYTHON.exists():
+        return str(VLLM_METAL_PYTHON)
+    return None
+
+
+def _json_request(
+    url: str,
+    *,
+    method: str = "GET",
+    payload: Optional[Dict[str, object]] = None,
+    headers: Optional[Dict[str, str]] = None,
+    timeout: float = 10.0,
+) -> Dict[str, object]:
+    data = None
+    req_headers = dict(headers or {})
+    if payload is not None:
+        data = json.dumps(payload).encode("utf-8")
+        req_headers.setdefault("Content-Type", "application/json")
+    req = urllib.request.Request(url, data=data, headers=req_headers, method=method)
+    with urllib.request.urlopen(req, timeout=timeout) as res:
+        raw = res.read().decode("utf-8", errors="replace")
+    if not raw.strip():
+        return {}
+    return json.loads(raw)
+
+
+def lmstudio_api_base() -> str:
+    return (os.getenv("LMSTUDIO_BASE_URL") or OPENAI_COMPATIBLE_PROVIDERS["lmstudio"]["base_url"]).rstrip("/")
+
+
+def lmstudio_native_api_base() -> str:
+    base = lmstudio_api_base()
+    return base[:-3] if base.endswith("/v1") else base
+
+
+def ensure_lmstudio_server() -> None:
+    base_url = lmstudio_native_api_base()
+    try:
+        _json_request(f"{base_url}/api/v1/models", headers={"Authorization": "Bearer lmstudio"}, timeout=2.5)
+        return
+    except Exception:
+        pass
+
+    cli = find_lmstudio_cli()
+    if not cli:
+        raise HTTPException(status_code=400, detail="LM Studio CLI를 찾지 못했습니다. LM Studio를 설치한 뒤 다시 시도하세요.")
+
+    try:
+        subprocess.Popen(
+            [cli, "server", "start"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"LM Studio 서버 시작 실패: {e}")
+
+    deadline = time.time() + 45
+    while time.time() < deadline:
+        try:
+            _json_request(f"{base_url}/api/v1/models", headers={"Authorization": "Bearer lmstudio"}, timeout=2.5)
+            return
+        except Exception:
+            time.sleep(1)
+    raise HTTPException(status_code=500, detail="LM Studio Local Server를 자동으로 시작하지 못했습니다.")
+
+
+_LMSTUDIO_MODELS_CACHE: List[Dict[str, object]] = []
+_LMSTUDIO_MODELS_CACHE_TS: float = 0.0
+_LMSTUDIO_MODELS_CACHE_TTL: float = 10.0
+
+
+def get_lmstudio_models(*, force: bool = False) -> List[Dict[str, object]]:
+    global _LMSTUDIO_MODELS_CACHE, _LMSTUDIO_MODELS_CACHE_TS
+    if not force and time.monotonic() - _LMSTUDIO_MODELS_CACHE_TS < _LMSTUDIO_MODELS_CACHE_TTL:
+        return _LMSTUDIO_MODELS_CACHE
+    try:
+        ensure_lmstudio_server()
+    except HTTPException:
+        return _LMSTUDIO_MODELS_CACHE
+    try:
+        payload = _json_request(
+            f"{lmstudio_native_api_base()}/api/v1/models",
+            headers={"Authorization": f"Bearer {os.getenv('LMSTUDIO_API_KEY') or 'lmstudio'}"},
+            timeout=5,
+        )
+    except Exception:
+        return _LMSTUDIO_MODELS_CACHE
+    models = payload.get("models")
+    _LMSTUDIO_MODELS_CACHE = models if isinstance(models, list) else []
+    _LMSTUDIO_MODELS_CACHE_TS = time.monotonic()
+    return _LMSTUDIO_MODELS_CACHE
+
+
+def _lmstudio_candidate_keys(model_name: str) -> List[str]:
+    raw = model_name.strip()
+    if not raw:
+        return []
+    slug = raw.split("/")[-1].lower()
+    slug = slug.replace("-gguf", "").replace("-awq", "")
+    parts = [p for p in slug.split("-") if p]
+    candidates = [raw.lower(), slug]
+    if parts:
+        candidates.append("-".join(parts[: min(4, len(parts))]))
+    return list(dict.fromkeys(candidates))
+
+
+def _find_lmstudio_model_key(model_name: str, models: List[Dict[str, object]]) -> Optional[str]:
+    if not models:
+        return None
+    candidate_keys = _lmstudio_candidate_keys(model_name)
+    exact = []
+    fuzzy = []
+    for item in models:
+        if not isinstance(item, dict):
+            continue
+        key = str(item.get("key") or "").strip()
+        display_name = str(item.get("display_name") or "").strip()
+        haystacks = [key.lower(), display_name.lower()]
+        if any(raw == key.lower() for raw in candidate_keys):
+            exact.append(key)
+            continue
+        if any(token and token in hay for token in candidate_keys for hay in haystacks):
+            fuzzy.append(key)
+    return (exact or fuzzy or [None])[0]
+
+
+def ensure_lmstudio_model(model_name: str) -> Dict[str, object]:
+    ensure_lmstudio_server()
+    auth_header = {"Authorization": f"Bearer {os.getenv('LMSTUDIO_API_KEY') or 'lmstudio'}"}
+    models = get_lmstudio_models()
+    found_key = _find_lmstudio_model_key(model_name, models)
+    model_key = found_key or model_name
+
+    if not found_key:
+        try:
+            job = _json_request(
+                f"{lmstudio_native_api_base()}/api/v1/models/download",
+                method="POST",
+                payload={"model": model_name},
+                headers=auth_header,
+                timeout=30,
+            )
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", errors="replace")[-2000:]
+            raise HTTPException(status_code=500, detail=f"LM Studio 모델 다운로드 실패: {detail or e.reason}")
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"LM Studio 모델 다운로드 실패: {e}")
+
+        status = str(job.get("status") or "")
+        job_id = str(job.get("job_id") or "")
+        if status not in {"completed", "already_downloaded"} and job_id:
+            deadline = time.time() + 3600
+            while time.time() < deadline:
+                polled = _json_request(
+                    f"{lmstudio_native_api_base()}/api/v1/models/download/status/{job_id}",
+                    headers=auth_header,
+                    timeout=30,
+                )
+                polled_status = str(polled.get("status") or "")
+                if polled_status == "completed":
+                    break
+                if polled_status == "failed":
+                    raise HTTPException(status_code=500, detail=f"LM Studio 모델 다운로드 실패: {polled}")
+                time.sleep(2)
+            else:
+                raise HTTPException(status_code=408, detail="LM Studio 모델 다운로드 시간이 초과되었습니다.")
+
+        models = get_lmstudio_models(force=True)
+        model_key = _find_lmstudio_model_key(model_name, models) or model_name
+
+    target = next((item for item in models if isinstance(item, dict) and item.get("key") == model_key), None)
+    loaded_instances = target.get("loaded_instances") if isinstance(target, dict) else None
+    if loaded_instances:
+        return {"provider": "lmstudio", "model": model_name, "resolved_model": model_key, "server_ready": True, "cached": True}
+
+    try:
+        loaded = _json_request(
+            f"{lmstudio_native_api_base()}/api/v1/models/load",
+            method="POST",
+            payload={"model": model_key, "context_length": 4096},
+            headers=auth_header,
+            timeout=120,
+        )
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode("utf-8", errors="replace")[-2000:]
+        raise HTTPException(status_code=500, detail=f"LM Studio 모델 로드 실패: {detail or e.reason}")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"LM Studio 모델 로드 실패: {e}")
+
+    if str(loaded.get("status") or "") != "loaded":
+        raise HTTPException(status_code=500, detail=f"LM Studio 모델 로드 실패: {loaded}")
+
+    return {
+        "provider": "lmstudio",
+        "model": model_name,
+        "resolved_model": model_key,
+        "instance_id": loaded.get("instance_id"),
+        "server_ready": True,
+        "cached": False,
+    }
+
+def engine_support_status(engine: str) -> Dict[str, object]:
+    if engine != "vllm":
+        return {"supported": True, "reason": None}
+    is_apple_silicon = sys.platform == "darwin" and platform.machine() == "arm64"
+    if sys.platform == "darwin" and not is_apple_silicon:
+        return {"supported": False, "reason": "vLLM Metal 자동 설치는 Apple Silicon macOS에서만 지원됩니다."}
+    if sys.version_info >= (3, 13) and is_apple_silicon:
+        return {"supported": True, "reason": "현재 환경에서는 vLLM Metal 전용 런타임으로 설치합니다."}
+    if sys.version_info >= (3, 13):
+        return {"supported": False, "reason": "vLLM 설치는 현재 Python 3.13 이하 또는 별도 전용 런타임이 필요합니다."}
+    return {"supported": True, "reason": None}
+
+def hf_model_ready(repo_id: str, provider: str = "local_mlx") -> bool:
+    model_dir = hf_model_dir(repo_id)
+    if provider == "vllm" and (not model_dir.exists() or not model_dir.is_dir()):
+        hf_cache_repo = Path.home() / ".cache" / "huggingface" / "hub" / f"models--{repo_id.replace('/', '--')}"
+        if hf_cache_repo.exists() and any(hf_cache_repo.glob("snapshots/*")):
+            return True
+        return False
+    if not model_dir.exists() or not model_dir.is_dir():
+        return False
+    if provider == "llamacpp":
+        return any(model_dir.rglob("*.gguf"))
+    has_config = (model_dir / "config.json").exists()
+    has_weights = any(model_dir.glob("*.safetensors")) or any(model_dir.glob("*.bin"))
+    has_tokenizer = (
+        (model_dir / "tokenizer.json").exists()
+        or (model_dir / "tokenizer.model").exists()
+        or (model_dir / "tokenizer_config.json").exists()
+    )
+    return has_config and has_weights and has_tokenizer
+
+def download_hf_model(repo_id: str, provider: str = "local_mlx") -> Dict[str, object]:
+    if importlib.util.find_spec("huggingface_hub") is None:
+        raise HTTPException(status_code=400, detail="huggingface_hub가 없습니다. 먼저 MLX runtime 설치를 진행해 주세요.")
+
+    target_dir = hf_model_dir(repo_id)
+    if hf_model_ready(repo_id, provider):
+        return {"model": repo_id, "path": str(target_dir), "cached": True}
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        from huggingface_hub import HfApi, hf_hub_download, snapshot_download
+
+        if provider == "llamacpp":
+            files = HfApi().list_repo_files(repo_id)
+            ggufs = sorted([name for name in files if name.lower().endswith(".gguf")])
+            if not ggufs:
+                raise RuntimeError("GGUF 파일을 찾지 못했습니다.")
+            preference = ("q4_k_m", "q4_0", "q4_k_s", "q3_k_m", "q2_k")
+            filename = next(
+                (name for pref in preference for name in ggufs if pref in name.lower()),
+                ggufs[0],
+            )
+            hf_hub_download(repo_id=repo_id, filename=filename, local_dir=str(target_dir))
+        else:
+            snapshot_download(repo_id=repo_id, local_dir=str(target_dir), resume_download=True)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"{repo_id} 다운로드 실패: {str(e)[-2000:]}")
+
+    if not hf_model_ready(repo_id, provider):
+        raise HTTPException(status_code=500, detail=f"{repo_id} 다운로드가 완료되지 않았습니다. 모델 파일을 찾지 못했습니다.")
+
+    return {"model": repo_id, "path": str(target_dir), "cached": False}
+
+
 def get_ollama_pulled_models() -> set:
     if not shutil.which("ollama"):
         return set()
@@ -2243,15 +2652,183 @@ def get_ollama_pulled_models() -> set:
         return set()
 
 
+def get_openai_compatible_server_models(provider: str) -> List[str]:
+    if provider == "lmstudio":
+        models = []
+        for item in get_lmstudio_models():
+            if not isinstance(item, dict):
+                continue
+            key = str(item.get("key") or "").strip()
+            loaded_instances = item.get("loaded_instances") or []
+            if loaded_instances:
+                instance_ids = [
+                    str(instance.get("id") or "").strip()
+                    for instance in loaded_instances
+                    if isinstance(instance, dict) and instance.get("id")
+                ]
+                models.extend(instance_ids or ([key] if key else []))
+        return list(dict.fromkeys([model for model in models if model]))
+
+    config = OPENAI_COMPATIBLE_PROVIDERS.get(provider) or {}
+    base_url = os.getenv(config.get("base_url_env", "")) if config.get("base_url_env") else None
+    base_url = (base_url or config.get("base_url") or "").rstrip("/")
+    if not base_url:
+        return []
+
+    api_key = os.getenv(config.get("env_key", "")) or config.get("api_key_fallback") or provider
+    req = urllib.request.Request(
+        f"{base_url}/models",
+        headers={"Authorization": f"Bearer {api_key}"},
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=2.5) as res:
+            payload = json.loads(res.read().decode("utf-8", errors="replace"))
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError, OSError):
+        return []
+
+    models = []
+    for item in payload.get("data") or []:
+        model_id = item.get("id") if isinstance(item, dict) else None
+        if model_id:
+            models.append(str(model_id))
+    return models
+
+
+def ensure_ollama_server() -> None:
+    if not shutil.which("ollama"):
+        raise HTTPException(status_code=400, detail="Ollama가 설치되지 않았습니다.")
+    try:
+        probe = subprocess.run(["ollama", "list"], capture_output=True, text=True, timeout=3, check=False)
+        if probe.returncode == 0:
+            return
+    except Exception:
+        pass
+    subprocess.Popen(
+        ["ollama", "serve"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    deadline = time.time() + 20
+    while time.time() < deadline:
+        try:
+            probe = subprocess.run(["ollama", "list"], capture_output=True, text=True, timeout=3, check=False)
+            if probe.returncode == 0:
+                return
+        except Exception:
+            pass
+        time.sleep(0.5)
+    raise HTTPException(status_code=500, detail="Ollama 서버를 자동으로 시작하지 못했습니다.")
+
+
+def wait_for_openai_compatible_server(provider: str, model_name: Optional[str] = None, timeout: int = 45) -> bool:
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        models = get_openai_compatible_server_models(provider)
+        if models and (not model_name or model_name in models):
+            return True
+        time.sleep(1)
+    return False
+
+
+def ensure_vllm_server(model_name: str) -> None:
+    served_models = get_openai_compatible_server_models("vllm")
+    if model_name in served_models:
+        return
+    vllm_bin = vllm_executable()
+    vllm_metal_py = vllm_metal_python()
+    if not vllm_bin and not vllm_metal_py and importlib.util.find_spec("vllm") is None:
+        raise HTTPException(status_code=400, detail="vLLM runtime이 설치되지 않았습니다.")
+
+    local_dir = hf_model_dir(model_name)
+    if not vllm_metal_py and not hf_model_ready(model_name, "vllm"):
+        download_hf_model(model_name, "vllm")
+
+    running = LOCAL_SERVER_PROCESSES.get("vllm")
+    if running and running.poll() is None:
+        running.terminate()
+        try:
+            running.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            running.kill()
+    elif served_models:
+        raise HTTPException(status_code=409, detail="다른 vLLM 서버가 이미 실행 중입니다. 현재 서버를 종료한 뒤 다시 시도하세요.")
+
+    running = LOCAL_SERVER_PROCESSES.get("vllm")
+    if running and running.poll() is None:
+        return
+
+    _host_args = ["--host", "127.0.0.1", "--port", "8000"]
+    if vllm_metal_py:
+        command = [vllm_metal_py, "-m", "vllm_metal.server", "--model", model_name, *_host_args]
+    elif vllm_bin:
+        command = [vllm_bin, "serve", str(local_dir), "--served-model-name", model_name, *_host_args]
+    else:
+        command = [sys.executable, "-m", "vllm.entrypoints.openai.api_server", "--model", str(local_dir), "--served-model-name", model_name, *_host_args]
+    LOCAL_SERVER_PROCESSES["vllm"] = subprocess.Popen(
+        command,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    if not wait_for_openai_compatible_server("vllm", model_name, timeout=90):
+        raise HTTPException(status_code=500, detail="vLLM 서버가 모델을 자동 로드하지 못했습니다.")
+
+
+def ensure_llamacpp_server(model_name: str) -> None:
+    served_models = get_openai_compatible_server_models("llamacpp")
+    if model_name in served_models:
+        return
+    running = LOCAL_SERVER_PROCESSES.get("llamacpp")
+    if running and running.poll() is None:
+        running.terminate()
+        try:
+            running.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            running.kill()
+    elif served_models:
+        raise HTTPException(status_code=409, detail="다른 llama.cpp 서버가 이미 실행 중입니다. 현재 서버를 종료한 뒤 다시 시도하세요.")
+    if not shutil.which("llama-server"):
+        raise HTTPException(status_code=400, detail="llama.cpp가 설치되지 않았습니다.")
+    if not hf_model_ready(model_name, "llamacpp"):
+        download_hf_model(model_name, "llamacpp")
+
+    gguf_files = sorted(hf_model_dir(model_name).rglob("*.gguf"))
+    if not gguf_files:
+        raise HTTPException(status_code=500, detail="다운로드된 GGUF 파일을 찾지 못했습니다.")
+
+    preferred = next((p for p in gguf_files if "q4_k_m" in p.name.lower()), None)
+    model_file = preferred or gguf_files[0]
+    LOCAL_SERVER_PROCESSES["llamacpp"] = subprocess.Popen(
+        [
+            "llama-server",
+            "-m",
+            str(model_file),
+            "--alias",
+            model_name,
+            "--host",
+            "127.0.0.1",
+            "--port",
+            "8080",
+        ],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    if not wait_for_openai_compatible_server("llamacpp", model_name, timeout=45):
+        raise HTTPException(status_code=500, detail="llama.cpp 서버가 모델을 자동 로드하지 못했습니다.")
+
+
 def engine_installed(engine: str) -> bool:
     if engine == "local_mlx":
-        return bool(mx is not None)
+        return bool(importlib.util.find_spec("mlx") and importlib.util.find_spec("mlx_lm"))
     if engine == "ollama":
         return shutil.which("ollama") is not None
     if engine == "vllm":
-        return importlib.util.find_spec("vllm") is not None
+        return vllm_metal_python() is not None or vllm_executable() is not None or importlib.util.find_spec("vllm") is not None
     if engine == "lmstudio":
-        return shutil.which("lms") is not None or Path("/Applications/LM Studio.app").exists()
+        return find_lmstudio_cli() is not None or Path("/Applications/LM Studio.app").exists()
     if engine == "llamacpp":
         return shutil.which("llama-server") is not None
     if engine in {"openai", "openrouter", "groq", "together", "xai"}:
@@ -2271,31 +2848,52 @@ def engine_status() -> List[Dict]:
         pull_name = m["id"].removeprefix("ollama:")
         ollama_models.append({**m, "pulled": pull_name in pulled})
 
-    hf_models_root = Path.home() / ".latticeai" / "hf-models"
-    hf_models_root.mkdir(parents=True, exist_ok=True)
+    HF_MODELS_ROOT.mkdir(parents=True, exist_ok=True)
     mlx_models = []
     for m in ENGINE_MODEL_CATALOG.get("local_mlx", []):
         repo_id = m["id"]
-        marker = hf_models_root / repo_id.replace("/", "__")
-        mlx_models.append({**m, "pulled": marker.exists()})
+        mlx_models.append({**m, "pulled": hf_model_ready(repo_id, "local_mlx")})
 
     vllm_models = []
     for m in ENGINE_MODEL_CATALOG.get("vllm", []):
         repo_id = m["id"].removeprefix("vllm:")
-        marker = hf_models_root / repo_id.replace("/", "__")
-        vllm_models.append({**m, "pulled": marker.exists()})
+        vllm_models.append({**m, "pulled": hf_model_ready(repo_id, "vllm")})
 
     lmstudio_models = []
-    for m in ENGINE_MODEL_CATALOG.get("lmstudio", []):
-        repo_id = m["id"].removeprefix("lmstudio:")
-        marker = hf_models_root / repo_id.replace("/", "__")
-        lmstudio_models.append({**m, "pulled": marker.exists()})
+    downloaded_lmstudio = get_lmstudio_models()
+    downloaded_by_key = {}
+    for item in downloaded_lmstudio:
+        if not isinstance(item, dict):
+            continue
+        key = str(item.get("key") or "").strip()
+        if not key:
+            continue
+        downloaded_by_key[key] = item
+        loaded_instances = item.get("loaded_instances") or []
+        lmstudio_models.append({
+            "id": f"lmstudio:{key}",
+            "name": item.get("display_name") or f"LM Studio · {key}",
+            "family": item.get("architecture") or item.get("publisher") or "LM Studio",
+            "tag": "loaded-server-model" if loaded_instances else "downloaded",
+            "size": item.get("params_string") or item.get("format") or "LM Studio",
+            "pullable": True,
+            "pulled": True,
+        })
+
+    if not lmstudio_models:
+        for m in ENGINE_MODEL_CATALOG.get("lmstudio", []):
+            lmstudio_models.append({**m, "pulled": False})
+    else:
+        known_ids = {item["id"] for item in lmstudio_models}
+        for m in ENGINE_MODEL_CATALOG.get("lmstudio", []):
+            repo_id = m["id"].removeprefix("lmstudio:")
+            if f"lmstudio:{repo_id}" not in known_ids and repo_id not in downloaded_by_key:
+                lmstudio_models.append({**m, "pulled": False})
 
     llamacpp_models = []
     for m in ENGINE_MODEL_CATALOG.get("llamacpp", []):
         repo_id = m["id"].removeprefix("llamacpp:")
-        marker = hf_models_root / repo_id.replace("/", "__")
-        llamacpp_models.append({**m, "pulled": marker.exists()})
+        llamacpp_models.append({**m, "pulled": hf_model_ready(repo_id, "llamacpp")})
 
     local_server_specs = [
         {
@@ -2303,12 +2901,19 @@ def engine_status() -> List[Dict]:
             "name": "vLLM",
             "description": "vLLM OpenAI 호환 서버(예: http://localhost:8000/v1)에 연결합니다.",
             "requires": "VLLM_BASE_URL",
+            "note": engine_support_status("vllm").get("reason"),
         },
         {
             "id": "lmstudio",
             "name": "LM Studio",
             "description": "LM Studio 로컬 OpenAI 호환 서버에 연결합니다.",
             "requires": "LMSTUDIO_BASE_URL",
+            "note": (
+                "다운로드된 모델은 자동 감지하고, 선택 시 필요하면 다운로드 후 바로 로드합니다."
+                if downloaded_lmstudio else
+                "LM Studio 설치 후 모델을 선택하면 Local Server 시작, 다운로드, 로드를 자동으로 진행합니다."
+            ),
+            "server_ready": bool(downloaded_lmstudio),
         },
         {
             "id": "llamacpp",
@@ -2341,13 +2946,16 @@ def engine_status() -> List[Dict]:
         },
     ]
     for spec in local_server_specs:
+        support = engine_support_status(spec["id"])
         engines.append({
             "id": spec["id"],
             "name": spec["name"],
             "kind": "local-server",
             "description": spec["description"],
             "installed": engine_installed(spec["id"]),
-            "installable": spec["id"] in ENGINE_INSTALLERS,
+            "supported": support["supported"],
+            "support_reason": support["reason"],
+            "installable": support["supported"] and spec["id"] in ENGINE_INSTALLERS,
             "install_label": ENGINE_INSTALLERS.get(spec["id"], {}).get("label"),
             "requires": spec["requires"],
             "models": (
@@ -2356,7 +2964,8 @@ def engine_status() -> List[Dict]:
                 else llamacpp_models if spec["id"] == "llamacpp"
                 else ENGINE_MODEL_CATALOG.get(spec["id"], [])
             ),
-            "note": f"{spec['requires']} 설정 시 활성화됩니다.",
+            "note": spec.get("note") or support["reason"] or f"{spec['requires']} 설정 시 활성화됩니다.",
+            "server_ready": spec.get("server_ready"),
         })
     for provider in ["openai", "openrouter", "groq", "together", "xai"]:
         env_key = next((item.get("requires") for item in cloud_by_provider.get(provider, []) if item.get("requires")), None)
@@ -2423,20 +3032,32 @@ def install_engine(engine: str) -> Dict:
     required_binary = installer.get("requires_binary")
     if required_binary and shutil.which(required_binary) is None:
         raise HTTPException(status_code=400, detail=f"{required_binary}가 설치되어 있지 않아 자동 설치할 수 없습니다.")
+    command = installer["command"]
+    run_kwargs = {
+        "cwd": str(Path(__file__).resolve().parent),
+        "capture_output": True,
+        "text": True,
+        "timeout": 900,
+        "check": False,
+    }
+
+    if engine == "vllm" and sys.platform == "darwin" and platform.machine() == "arm64":
+        command = [
+            "/bin/bash",
+            "-lc",
+            "set -euo pipefail; "
+            "if [ ! -x /opt/homebrew/bin/python3.12 ]; then brew install python@3.12; fi; "
+            "/opt/homebrew/bin/python3.12 -m venv ~/.venv-vllm-metal; "
+            "~/.venv-vllm-metal/bin/pip install -U pip setuptools wheel; "
+            "~/.venv-vllm-metal/bin/pip install vllm-metal",
+        ]
     try:
-        completed = subprocess.run(
-            installer["command"],
-            cwd=str(Path(__file__).resolve().parent),
-            capture_output=True,
-            text=True,
-            timeout=900,
-            check=False,
-        )
+        completed = subprocess.run(command, **run_kwargs)
     except subprocess.TimeoutExpired:
         raise HTTPException(status_code=408, detail="엔진 설치 시간이 초과되었습니다.")
     result = {
         "engine": engine,
-        "command": " ".join(installer["command"]),
+        "command": " ".join(command),
         "returncode": completed.returncode,
         "stdout": completed.stdout[-12000:],
         "stderr": completed.stderr[-12000:],
@@ -2467,6 +3088,119 @@ def install_engine(engine: str) -> Dict:
                 result["daemon_started"] = False
     return result
 
+
+def normalize_local_model_request(model_id: str, engine: Optional[str] = None) -> str:
+    model_id = model_id.strip()
+    engine = (engine or "").strip().lower()
+    if engine in {"local_mlx", "mlx"} and model_id.startswith(("local_mlx:", "mlx:")):
+        return model_id.split(":", 1)[1].strip()
+    if engine and engine not in {"local_mlx", "mlx"} and ":" not in model_id:
+        return f"{engine}:{model_id}"
+    return model_id
+
+
+def ensure_engine_ready(engine: str) -> Dict[str, object]:
+    engine = "local_mlx" if engine == "mlx" else engine
+    if engine not in ENGINE_INSTALLERS and engine not in OPENAI_COMPATIBLE_PROVIDERS:
+        raise HTTPException(status_code=400, detail=f"지원하지 않는 엔진입니다: {engine}")
+    support = engine_support_status(engine)
+    if not support["supported"]:
+        raise HTTPException(status_code=400, detail=str(support["reason"]))
+
+    if engine_installed(engine):
+        if engine == "local_mlx":
+            ensure_mlx_runtime()
+        return {"engine": engine, "installed": True, "installed_now": False}
+
+    if engine not in ENGINE_INSTALLERS:
+        raise HTTPException(status_code=400, detail=f"{engine} 엔진 설치 방법이 등록되어 있지 않습니다.")
+
+    result = install_engine(engine)
+    if result.get("returncode") not in (0, None) or not engine_installed(engine):
+        detail = result.get("stderr") or result.get("stdout") or f"{engine} 설치에 실패했습니다."
+        raise HTTPException(status_code=500, detail=str(detail)[-2000:])
+
+    if engine == "local_mlx":
+        ensure_mlx_runtime()
+    return {"engine": engine, "installed": True, "installed_now": True, "install": result}
+
+
+async def prepare_and_load_model(
+    model_id: str,
+    request: Request,
+    engine: Optional[str] = None,
+    user_email: Optional[str] = None,
+    adapter_path: Optional[str] = None,
+    draft_model_id: Optional[str] = None,
+) -> Dict[str, object]:
+    model_id = normalize_local_model_request(model_id, engine)
+    if not model_id:
+        raise HTTPException(status_code=400, detail="모델 식별자가 비어 있습니다.")
+
+    parsed_provider, parsed_model = parse_model_ref(model_id)
+    if parsed_provider == "mlx":
+        parsed_provider = "local_mlx"
+
+    local_engines = {"local_mlx", "ollama", "vllm", "lmstudio", "llamacpp"}
+    install_result: Dict[str, object] = {}
+    download_result: Optional[Dict[str, object]] = None
+
+    if parsed_provider in local_engines:
+        install_result = ensure_engine_ready(parsed_provider)
+
+    if parsed_provider == "local_mlx":
+        explicit_path = Path(parsed_model).expanduser()
+        if not explicit_path.exists() and not hf_model_ready(parsed_model, "local_mlx"):
+            download_result = download_hf_model(parsed_model, "local_mlx")
+    elif parsed_provider == "ollama":
+        ensure_ollama_server()
+        if parsed_model not in get_ollama_pulled_models():
+            completed = subprocess.run(
+                ["ollama", "pull", parsed_model],
+                capture_output=True,
+                text=True,
+                timeout=900,
+                check=False,
+            )
+            if completed.returncode != 0:
+                raise HTTPException(status_code=500, detail=completed.stderr[-2000:] or "Ollama 모델 다운로드 실패")
+            download_result = {"provider": "ollama", "model": parsed_model, "returncode": completed.returncode}
+    elif parsed_provider == "vllm":
+        ensure_vllm_server(parsed_model)
+        download_result = {"provider": "vllm", "model": parsed_model, "server_ready": True}
+    elif parsed_provider == "llamacpp":
+        ensure_llamacpp_server(parsed_model)
+        download_result = {"provider": "llamacpp", "model": parsed_model, "server_ready": True}
+    elif parsed_provider == "lmstudio":
+        ensured = ensure_lmstudio_model(parsed_model)
+        resolved_model = str(
+            ensured.get("instance_id")
+            or ensured.get("resolved_model")
+            or parsed_model
+        ).strip()
+        parsed_model = resolved_model
+        model_id = f"lmstudio:{resolved_model}"
+        download_result = ensured
+
+    effective_email = (user_email or get_current_user(request) or "").strip()
+    user_api_key = get_user_api_key(effective_email, parsed_provider) if parsed_provider != "local_mlx" else None
+    msg = await router.load_model(
+        model_id,
+        adapter_path,
+        draft_model_id=draft_model_id,
+        api_key_override=user_api_key,
+        owner=effective_email or None,
+    )
+    return {
+        "status": "ok",
+        "message": msg,
+        "model": model_id,
+        "current": router.current_model_id,
+        "engine": parsed_provider,
+        "installed_now": bool(install_result.get("installed_now")),
+        "download": download_result,
+    }
+
 CLOUD_VERIFY_CACHE: Dict[str, Dict] = {}
 CLOUD_VERIFY_TTL_SECONDS = 600
 
@@ -2531,6 +3265,7 @@ async def health(request: Request):
     base = {"status": "ok", "version": "2.1.0", "mode": APP_MODE}
     if not get_current_user(request) and REQUIRE_AUTH:
         return base
+    engines = await asyncio.to_thread(engine_status)
     return {
         **base,
         "current_model": router.current_model_id,
@@ -2538,7 +3273,7 @@ async def health(request: Request):
         "device": "Apple Silicon MLX" if not IS_PUBLIC_MODE else "Public cloud/API runtime",
         "features": runtime_features(),
         "providers": router.detected_cloud_models(),
-        "engines": engine_status(),
+        "engines": engines,
     }
 
 
@@ -2550,7 +3285,7 @@ async def mode():
 
 @app.get("/engines")
 async def engines():
-    return {"engines": engine_status(), "current": router.current_model_id}
+    return {"engines": await asyncio.to_thread(engine_status), "current": router.current_model_id}
 
 
 @app.post("/engines/install")
@@ -2583,8 +3318,7 @@ async def pull_ollama_model(req: PullModelRequest, request: Request):
         raise HTTPException(status_code=400, detail="모델 이름이 비어 있습니다.")
 
     if provider == "ollama":
-        if not shutil.which("ollama"):
-            raise HTTPException(status_code=400, detail="Ollama가 설치되지 않았습니다.")
+        ensure_ollama_server()
         try:
             completed = subprocess.run(
                 ["ollama", "pull", model_name],
@@ -2596,25 +3330,35 @@ async def pull_ollama_model(req: PullModelRequest, request: Request):
             raise HTTPException(status_code=500, detail=completed.stderr[-2000:] or "pull 실패")
         return {"provider": provider, "model": model_name, "returncode": completed.returncode}
 
-    if provider in {"vllm", "lmstudio", "llamacpp", "local_mlx", "mlx"}:
-        if importlib.util.find_spec("huggingface_hub") is None:
-            raise HTTPException(status_code=400, detail="huggingface_hub가 없습니다. 먼저 엔진 설치를 진행해 주세요.")
-        target_dir = Path.home() / ".latticeai" / "hf-models" / model_name.replace("/", "__")
-        target_dir.mkdir(parents=True, exist_ok=True)
-        try:
-            completed = subprocess.run(
-                [sys.executable, "-m", "huggingface_hub", "download", model_name, "--local-dir", str(target_dir)],
-                capture_output=True, text=True, timeout=3600, check=False,
-            )
-        except subprocess.TimeoutExpired:
-            raise HTTPException(status_code=408, detail=f"{provider} 모델 다운로드 시간이 초과되었습니다.")
-        if completed.returncode != 0:
-            raise HTTPException(status_code=500, detail=completed.stderr[-2000:] or f"{provider} 모델 다운로드 실패")
-        return {"provider": provider, "model": model_name, "returncode": completed.returncode, "path": str(target_dir)}
+    if provider == "lmstudio":
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                "LM Studio 모델은 Lattice에서 Hugging Face로 pull하지 않습니다. "
+                "LM Studio 앱에서 모델을 다운로드하고 Local Server를 켠 뒤 모델을 로드하세요. "
+                "그러면 모델 선택창에 실제 /v1/models 항목이 표시됩니다."
+            ),
+        )
+
+    if provider in {"vllm", "llamacpp", "local_mlx", "mlx"}:
+        download_provider = "local_mlx" if provider == "mlx" else provider
+        result = download_hf_model(model_name, download_provider)
+        return {"provider": provider, "model": model_name, "returncode": 0, **result}
 
     raise HTTPException(status_code=400, detail=f"{provider} 엔진 모델 다운로드는 아직 자동화되지 않았습니다.")
 
 
+@app.post("/engines/prepare-model")
+async def engines_prepare_model(req: PrepareModelRequest, request: Request):
+    require_user(request)
+    return await prepare_and_load_model(
+        req.model,
+        request,
+        engine=req.engine,
+        user_email=req.user_email,
+    )
+
+
 @app.post("/setup/set-api-key")
 async def set_api_key(req: SetApiKeyRequest, request: Request):
     from llm_router import OPENAI_COMPATIBLE_PROVIDERS
@@ -2661,7 +3405,7 @@ async def list_models():
     return {
         "recommended": recommended,
         "cloud": router.detected_cloud_models(),
-        "engines": engine_status(),
+        "engines": await asyncio.to_thread(engine_status),
         "loaded": router.loaded_model_ids,
         "current": router.current_model_id,
     }
@@ -2680,21 +3424,14 @@ async def load_model(req: LoadModelRequest, request: Request):
                 status_code=400,
                 detail="Public mode blocks local MLX model loading. Use openai:, openrouter:, groq:, together:, or set LATTICEAI_ALLOW_LOCAL_MODELS=true.",
             )
-        if req.engine and req.engine not in {"local_mlx", "mlx"} and ":" not in model_id:
-            model_id = f"{req.engine}:{model_id}"
-        effective_email = (req.user_email or get_current_user(request) or "").strip()
-        user_api_key = None
-        if ":" in model_id:
-            provider = model_id.split(":", 1)[0]
-            user_api_key = get_user_api_key(effective_email, provider)
-        msg = await router.load_model(
+        return await prepare_and_load_model(
             model_id,
-            req.adapter_path,
+            request,
+            engine=req.engine,
+            user_email=req.user_email,
+            adapter_path=req.adapter_path,
             draft_model_id=req.draft_model_id,
-            api_key_override=user_api_key,
-            owner=effective_email or None,
         )
-        return {"status": "ok", "message": msg, "current": router.current_model_id}
     except HTTPException:
         raise
     except Exception as e:
@@ -3078,130 +3815,462 @@ async def _stream_chat(req: ChatRequest, context: str = "", image_data: str = No
 
 # ── Local Computer Agent ──────────────────────────────────────────────────────
 
-AGENT_SYSTEM_PROMPT = """You are Lattice AI Agent, a local computer-use coding assistant.
-You have full access to the local filesystem via local_list / local_read / local_write tools.
-Use read_file / write_file for paths inside the agent workspace (relative paths).
-Use local_read / local_write for any absolute path on the system (e.g. ~/Downloads, ~/Desktop).
+# ── Agent Role Prompts (Planner / Executor / Critic / Memory Updater) ─────────
+
+_TOOL_CATALOG_BRIEF = """
+FILESYSTEM  : list_dir  workspace_tree  read_file  write_file  edit_file  grep  search_files  inspect_html  preview_url
+PLANNING    : todo_read  todo_write
+PROJECT     : run_command  build_project  deploy_project  create_web_project
+GIT (read)  : git_status  git_diff  git_log  git_show
+LOCAL FS    : local_list  local_read  local_write  read_document
+DOCS        : create_docx  create_xlsx  create_pptx  create_pdf
+KNOWLEDGE   : knowledge_save  knowledge_search  knowledge_tree
+COMPUTER    : computer_screenshot  computer_open_app  computer_open_url  computer_click  computer_type  computer_key
+MISC        : network_status  clear_history  final
+"""
 
-Available actions:
-- list_dir: {"action":"list_dir","args":{"path":"."}}
-- workspace_tree: {"action":"workspace_tree","args":{"path":".","max_depth":3}}
-- read_file: {"action":"read_file","args":{"path":"relative/path.txt"}}
-- write_file: {"action":"write_file","args":{"path":"relative/path.txt","content":"complete file content"}}
-- search_files: {"action":"search_files","args":{"query":"text","path":".","max_results":20}}
-- clear_history: {"action":"clear_history","args":{"keep_last":0}}
-- inspect_html: {"action":"inspect_html","args":{"path":"index.html"}}
-- preview_url: {"action":"preview_url","args":{"path":"index.html"}}
-- create_docx: {"action":"create_docx","args":{"title":"title","body":"paragraphs","filename":"document.docx"}}
-- create_xlsx: {"action":"create_xlsx","args":{"rows":[["A","B"],[1,2]],"filename":"spreadsheet.xlsx","sheet_name":"Sheet1"}}
-- create_pptx: {"action":"create_pptx","args":{"title":"title","slides":[{"title":"Slide","bullets":["point"]}],"filename":"presentation.pptx"}}
-- create_pdf: {"action":"create_pdf","args":{"title":"title","body":"paragraphs","filename":"document.pdf"}}
-- create_web_project: {"action":"create_web_project","args":{"path":"my_app","framework":"react","template":"vite"}} — scaffold a runnable web app project
-- local_list: {"action":"local_list","args":{"path":"/Users/username/Downloads"}} — lists any local folder (UI will request user permission first)
-- local_read: {"action":"local_read","args":{"path":"/Users/username/Documents/note.txt"}} — reads any local file (UI will request user permission first)
-- local_write: {"action":"local_write","args":{"path":"/Users/username/Desktop/output.txt","content":"..."}} — writes any local file (UI will request user permission first)
-- read_document: {"action":"read_document","args":{"path":"/absolute/path/to/file.pdf"}} — extract text from PDF, DOCX, XLSX, PPTX, TXT, MD, CSV
-- computer_screenshot: {"action":"computer_screenshot","args":{}} — capture current screen as base64 PNG
-- computer_open_app: {"action":"computer_open_app","args":{"app":"Google Chrome"}} — open or focus a Mac app
-- computer_open_url: {"action":"computer_open_url","args":{"url":"https://example.com","app":"Google Chrome"}} — open URL in app
-- computer_click: {"action":"computer_click","args":{"x":500,"y":300,"button":"left","double":false}}
-- computer_type: {"action":"computer_type","args":{"text":"hello"}}
-- computer_key: {"action":"computer_key","args":{"key":"command+c"}} — e.g. return, escape, tab, command+v
-- computer_scroll: {"action":"computer_scroll","args":{"x":500,"y":300,"direction":"down","clicks":3}}
-- computer_move: {"action":"computer_move","args":{"x":500,"y":300}}
-- computer_drag: {"action":"computer_drag","args":{"x1":100,"y1":100,"x2":500,"y2":500}}
-- computer_status: {"action":"computer_status","args":{}} — check if Computer Use is available
-- chrome_status: {"action":"chrome_status","args":{}}
-- computer_use_status: {"action":"computer_use_status","args":{}}
-- knowledge_save: {"action":"knowledge_save","args":{"folder":"30_Projects","title":"short title","content":"note"}}
-- knowledge_search: {"action":"knowledge_search","args":{"query":"keyword","max_results":5}}
-- knowledge_tree: {"action":"knowledge_tree","args":{}}
-- obsidian_save: {"action":"obsidian_save","args":{"folder":"30_Projects","title":"short title","content":"note"}}
-- obsidian_search: {"action":"obsidian_search","args":{"query":"keyword","max_results":5}}
-- obsidian_tree: {"action":"obsidian_tree","args":{}}
-- git_status: {"action":"git_status","args":{}}
-- git_diff: {"action":"git_diff","args":{"path":"optional/relative/path"}}
-- git_log: {"action":"git_log","args":{"max_count":5}}
-- git_show: {"action":"git_show","args":{"revision":"HEAD"}}
-- network_status: {"action":"network_status","args":{}} — get current local/private IP, public IP, hostname, and Wi-Fi info
-- run_command: {"action":"run_command","args":{"command":"python3 app.py","cwd":"."}}
-- build_project: {"action":"build_project","args":{"cwd":".","script":"build"}}
-- deploy_project: {"action":"deploy_project","args":{"cwd":".","script":"deploy"}}
-- final: {"action":"final","message":"short Korean summary of what you did"}
+PLANNER_PROMPT = """You are the PLANNER role in Lattice AI's multi-role agent harness.
+Your ONLY job: analyze the request and produce a structured execution plan.
+You do NOT call tools or write code.
+
+Respond with exactly ONE JSON object (no markdown, no fences):
+{
+  "action": "plan",
+  "state": "PLANNING",
+  "goal": "one-sentence goal in the user's language",
+  "steps": [
+    {"id": 1, "description": "what this step does", "action": "expected_tool", "purpose": "why needed"}
+  ],
+  "requires_approval": true,
+  "rollback_strategy": "git",
+  "estimated_steps": 3
+}
 
 Rules:
-- Respond with exactly one JSON object. No markdown, no code fences, no extra text.
-- Use relative paths only.
-- Create complete files, not fragments.
-- Prefer simple, verifiable steps.
-- Use inspect_html and preview_url for generated web UI.
-- Use build_project when the user asks to build, compile, typecheck, or run a package build script.
-- Use deploy_project when the user asks to deploy, preview, release, or package installers (pkg/exe) and package.json defines that script (e.g. package, dist, make, build:pkg, build:exe).
-- If the user asks for app/service/web creation, prefer create_web_project first, then edit files with write_file/read_file and verify with build_project or run_command.
-- If the user asks for installer outputs (.pkg/.exe), set up packaging config (for example Electron/electron-builder or equivalent), create package scripts in package.json, then run deploy_project for installer scripts.
-- If .exe cannot be built on current OS/toolchain, still generate the full packaging config and scripts for Windows and report the exact missing prerequisite.
-- Do not claim you cannot build or deploy. If a script, token, or platform config is missing, inspect the workspace and explain the exact missing piece.
-- Use knowledge tools when the user asks to remember, search memory, or organize project context.
-- Use run_command for local inspection, tests, and short development commands after files are written.
-- For data analysis tasks, read the provided files first (read_document/local_read), compute with run_command when needed, and return concrete findings plus output artifact paths when created.
-- Use clear_history when the user asks to forget, clear, delete, reset, or speed up chat history.
-- Git is read-only: status, diff, log, and show only. Never commit, push, pull, fetch, clone, reset, or checkout.
-- If the user asks for something unsafe or outside the workspace, explain the limitation with final.
-- IMPORTANT: When user asks to create any document (docx, pdf, xlsx, pptx, word, excel, powerpoint, 문서, 파일, 엑셀, 파워포인트, PPT, 피피티), ALWAYS use the appropriate create_* action immediately with full, rich content. Never say you cannot create files.
+- requires_approval = true if ANY step uses write/exec tools (edit_file, write_file, run_command, etc.)
+- rollback_strategy = "git" if steps modify existing files; "none" otherwise
+- Keep steps realistic: 2-4 for simple tasks, up to 10 for complex ones
+- Do NOT specify full tool args — that is the Executor's job
+
+Available tools:""" + _TOOL_CATALOG_BRIEF
+
+EXECUTOR_PROMPT = """You are the EXECUTOR role in Lattice AI's multi-role agent harness.
+You have a plan from the Planner. Execute it step by step using exactly one tool per response.
+
+You think and act like a senior software engineer:
+- Read (read_file, grep) BEFORE editing — never guess at file contents
+- Prefer edit_file over write_file for existing files
+- Keep changes small and precise
+- Verify after changes with build_project or run_command
+
+Respond with exactly ONE JSON object per step:
+{"thoughts": "what you learned / why this next action", "action": "tool_name", "args": {...}}
+
+When the task is fully done AND a tool result in this run confirms it:
+{"thoughts": "verified", "action": "final", "message": "한국어로 무엇을 했고 어디서 검증했는지 요약"}
+
+ANTI-PATTERNS (will halt the loop):
+- Editing without reading first → read_file + grep BEFORE edit_file
+- Repeating the same action+args → check the transcript
+- Claiming done without a verification tool result in transcript
+- Hallucinating imports or file paths that were never confirmed by a tool result
+
+Available tools:""" + _TOOL_CATALOG_BRIEF
+
+CRITIC_PROMPT = """You are the CRITIC / REVIEWER role in Lattice AI's multi-role agent harness.
+Review the execution transcript and determine whether the goal was achieved.
+
+Respond with exactly ONE JSON object:
+{
+  "action": "verdict",
+  "state": "VERIFYING",
+  "verdict": "PASS",
+  "reason": "why you think it passed or failed (cite specific tool results)",
+  "corrections": [],
+  "confidence": 0.95,
+  "next_state": "DONE"
+}
+
+verdict: "PASS" | "FAIL"
+next_state:
+  "DONE"      — task succeeded; finish
+  "EXECUTING" — task failed but corrections can fix it (use corrections field for retry)
+  "ROLLBACK"  — task failed AND file changes should be undone
+
+Criteria for PASS: a tool result in the transcript explicitly confirms success.
+Be strict. Claiming done without evidence = FAIL."""
+
+MEMORY_UPDATER_PROMPT = """You are the MEMORY UPDATER role in Lattice AI's multi-role agent harness.
+After a completed task, extract reusable learnings.
+
+Respond with exactly ONE JSON object:
+{
+  "action": "memory",
+  "state": "DONE",
+  "learnings": ["one concise fact about this codebase or task"],
+  "artifacts": ["relative/path/to/created_or_modified_file"],
+  "save_to_knowledge": false
+}
+
+Rules:
+- max 5 learnings, one sentence each
+- save_to_knowledge = true only if learnings are genuinely useful across future sessions
+- artifacts = files the Executor actually created or modified (from transcript)
+"""
+
+# Keep backward-compat alias used by any existing callers
+AGENT_SYSTEM_PROMPT = EXECUTOR_PROMPT
+
+# Marker: the old monolithic prompt was replaced by 4-role prompts above.
+# Legacy variable kept so Telegram bot / VS Code extension still work.
+
+_ORIGINAL_MONOLITHIC_PROMPT_NOTE = """You are Lattice AI Agent — a local, professional-grade coding assistant.
+You have full access to a sandboxed workspace and (with user approval) the wider filesystem.
+You think and work like a senior software engineer, not like an autocompleter.
+
+================================================================================
+HOW A PROFESSIONAL DEVELOPER THINKS — your operating loop
+================================================================================
+Every multi-step task follows four phases. Skipping phases is the #1 cause of bad
+output. Do not skip them.
+
+1) DISCOVER (read first, then act)
+   - Map the territory before changing it. Use workspace_tree, list_dir, grep,
+     and read_file BEFORE writing or editing anything.
+   - When the user names a file/feature/function, locate it (grep) and read the
+     surrounding code BEFORE proposing a change.
+   - Read package.json, pyproject.toml, requirements.txt, tsconfig.json, and
+     other config files before assuming a library/version/tool is available.
+   - Never guess at APIs, imports, file paths, function signatures, or types.
+     If you don't know, look it up with grep/read_file. Hallucinated code is
+     the worst possible output.
+
+2) PLAN (write the plan down)
+   - For any task with 3+ distinct steps, call todo_write FIRST with a concrete
+     checklist (3–10 items). Keep exactly one item in_progress at a time.
+   - The plan should describe WHAT will change and HOW you'll verify it works,
+     not vague intentions ("look at code", "fix bugs"). Bad plans produce bad code.
+   - Update the todo list (todo_write again) as items complete or new ones emerge.
+
+3) IMPLEMENT (small, precise diffs)
+   - Prefer edit_file over write_file when modifying existing files. edit_file
+     requires exact byte-level old_string match — read the file first and copy
+     the surrounding context verbatim. This forces correctness.
+   - Use write_file only for brand-new files or when fully rewriting a file you
+     understand end-to-end.
+   - Keep diffs as small as the task requires. Don't refactor "while you're
+     there." Don't add abstractions for hypothetical future needs.
+   - Code quality:
+       * No new comments unless the WHY is non-obvious (a subtle invariant, a
+         workaround for a specific bug, behavior that would surprise a reader).
+         Never write comments that just restate what the code does.
+       * No backward-compat shims, no dead code, no unused imports/variables.
+       * No defensive try/except around code that can't fail. Trust internal
+         contracts; validate only at system boundaries (user input, network).
+       * Match the surrounding code's style (indent, quotes, naming).
+
+4) VERIFY (prove it works before claiming done)
+   - After code changes, RUN something that confirms correctness:
+       * build_project for build/typecheck/test scripts
+       * run_command for python/node scripts and tests
+       * inspect_html + preview_url for generated UI
+   - If verification fails, treat the failure as the new task. Diagnose root
+     cause; do not paper over it (no try/except shortcuts, no --no-verify, no
+     disabling tests). Re-enter Discover phase if needed.
+   - Never claim a task is "complete," "saved," "fixed," "working," or
+     "deployed" unless a tool result in this same agent run confirms it.
+
+================================================================================
+RESPONSE FORMAT (strict)
+================================================================================
+Respond with exactly ONE JSON object per step. No markdown, no code fences, no
+extra prose. Include a short `thoughts` field that records your current reasoning
+(what you just learned, what you'll do next, why). The user does not see it
+directly — it exists so you can plan across steps.
+
+  {"thoughts": "Need to read App.tsx before editing the import. Workspace tree
+   confirms only one App.tsx exists.",
+   "action": "read_file",
+   "args": {"path": "src/App.tsx"}}
+
+When the task is fully complete AND verified:
+  {"thoughts": "Build passed, file written, ready to summarize.",
+   "action": "final",
+   "message": "한국어로 간결하게 무엇을 만들었고 어디서 검증했는지 요약."}
+
+If you cannot proceed (missing tool, blocked path, ambiguous user intent), use
+`final` and clearly state the blocker and the smallest next step the user can
+take to unblock it. Do NOT loop on the same failing action.
+
+================================================================================
+TOOL CATALOG
+================================================================================
+Filesystem (workspace, relative paths):
+  list_dir        {"path":"."}
+  workspace_tree  {"path":".", "max_depth":3}
+  read_file       {"path":"src/App.tsx", "offset":0, "limit":0, "line_numbers":true}
+                  — returns numbered view + total_lines. Use offset/limit for big files.
+  write_file      {"path":"new_file.py", "content":"..."}   — new files / full rewrites
+  edit_file       {"path":"existing.py", "old_string":"exact text", "new_string":"new text",
+                   "replace_all":false}
+                  — preferred for existing files. old_string MUST appear once
+                    (unless replace_all=true). Include enough surrounding context
+                    to make it unique.
+  grep            {"pattern":"regex", "path":".", "glob":"*.py", "max_results":50,
+                   "case_insensitive":false, "context_lines":2}
+                  — regex search across the codebase. Use this before assuming a
+                    symbol exists.
+  search_files    {"query":"substring", "path":".", "max_results":20}   — legacy substring search
+  inspect_html    {"path":"index.html"}
+  preview_url     {"path":"index.html"}
+
+Planning:
+  todo_read       {}
+  todo_write      {"todos":[{"id":"1","content":"...","status":"pending"}]}
+                  — status ∈ pending|in_progress|completed.
+                    Use proactively for any task with 3+ steps.
+
+Project ops:
+  run_command     {"command":"python3 app.py", "cwd":"."}
+                  — allowed binaries: pwd ls find cat sed head tail wc rg python python3 node npm npx
+                  — git is NOT allowed here; use the git_* tools below (read-only).
+  build_project   {"cwd":".", "script":"build"}    — also: compile, typecheck, test
+  deploy_project  {"cwd":".", "script":"deploy"}   — also: preview, release, package, dist, make, build:pkg, build:exe
+  create_web_project {"path":"my_app", "framework":"react", "template":"vite"}
+
+Git (read-only):
+  git_status, git_diff, git_log, git_show
+  — Never commit/push/pull/fetch/clone/reset/checkout. Lattice agent does not author git history.
+
+Local filesystem (outside workspace; UI prompts user for approval):
+  local_list      {"path":"/Users/.../Downloads"}
+  local_read      {"path":"/abs/path/file.txt"}
+  local_write     {"path":"/abs/path/file.txt", "content":"..."}
+  read_document   {"path":"/abs/path/report.pdf"}   — PDF, DOCX, XLSX, PPTX, TXT, MD, CSV
+
+Document generation (written to workspace generated_* folders):
+  create_docx     {"title":"...", "body":"...", "filename":"doc.docx"}
+  create_xlsx     {"rows":[["A","B"],[1,2]], "filename":"sheet.xlsx", "sheet_name":"Sheet1"}
+  create_pptx     {"title":"...", "slides":[{"title":"...","bullets":["..."]}], "filename":"deck.pptx"}
+  create_pdf      {"title":"...", "body":"...", "filename":"doc.pdf"}
+
+Knowledge / memory (Obsidian-compatible Markdown vault):
+  knowledge_save  {"folder":"30_Projects", "title":"...", "content":"..."}
+  knowledge_search {"query":"...", "max_results":5}
+  knowledge_tree  {}
+  obsidian_save / obsidian_search / obsidian_tree  — same as knowledge_*, with vault URIs
+
+Computer use (macOS desktop control, requires Accessibility permission):
+  computer_screenshot, computer_open_app, computer_open_url, computer_click,
+  computer_type, computer_key, computer_scroll, computer_move, computer_drag,
+  computer_status, chrome_status, computer_use_status
+  — Use screenshot to ground state; click/type to interact. Verify with another screenshot.
+
+Misc:
+  network_status  {}
+  clear_history   {"keep_last":0}
+  final           {"message":"..."}
+
+================================================================================
+DOMAIN RULES (keep in mind)
+================================================================================
+- Frontend: don't assume Tailwind/framer-motion/TypeScript exist. Read
+  package.json first. If a dependency is missing, either add it explicitly to
+  package.json (and create the config files it needs) or pick a simpler stack
+  that already works.
+- Installers (.pkg/.exe): set up the packaging config (e.g. electron-builder)
+  with full scripts in package.json, then run deploy_project. If the current
+  OS/toolchain can't produce the artifact, still generate complete config and
+  state the exact missing prerequisite — do not say "I can't."
+- Data analysis: read the data files (read_document/local_read), compute with
+  run_command, report concrete findings plus output artifact paths.
+- Document requests (docx/xlsx/pptx/pdf, 문서/엑셀/PPT/피피티/파워포인트): call
+  the matching create_* action immediately with rich, complete content. Never
+  say you cannot create files.
+- Korean/English: answer in the language the user used; default to Korean
+  if mixed or ambiguous.
+
+================================================================================
+ANTI-PATTERNS (will be flagged by the orchestrator)
+================================================================================
+- Editing without reading first → use read_file + grep before edit_file.
+- Repeating the same action with the same args → the loop will halt you.
+- Claiming "done" without a verification tool result in the transcript.
+- Adding new dependencies without updating package.json / requirements.txt.
+- Producing fragments when the user asked for a complete file or runnable app.
+- Stuffing speculative features beyond the user's actual request.
+- Decorative placeholder URLs / fake data when real data is available.
 """
 
 
-_FILE_CREATE_ACTIONS = {"create_docx", "create_xlsx", "create_pptx", "create_pdf", "write_file", "create_web_project"}
+_FILE_CREATE_ACTIONS = {"create_docx", "create_xlsx", "create_pptx", "create_pdf", "write_file", "edit_file", "create_web_project"}
 
 # Harness risk level per tool action.
 # low    — read-only, no side effects
 # medium — write/create files or knowledge entries
 # high   — execute commands, control computer, write to arbitrary FS paths
-_TOOL_RISK: Dict[str, str] = {
-    # read-only workspace tools
-    "list_dir": "low", "workspace_tree": "low", "read_file": "low",
-    "search_files": "low", "inspect_html": "low",
-    # read-only local FS
-    "local_list": "low", "local_read": "low",
-    # read-only git
-    "git_status": "low", "git_log": "low", "git_diff": "low", "git_show": "low",
-    # read-only knowledge / computer
-    "knowledge_search": "low", "knowledge_tree": "low",
-    "obsidian_search": "low", "obsidian_tree": "low",
-    "computer_screenshot": "low", "computer_status": "low",
-    # write workspace
-    "write_file": "medium", "create_web_project": "medium",
-    "create_docx": "medium", "create_xlsx": "medium",
-    "create_pptx": "medium", "create_pdf": "medium",
-    # write knowledge
-    "knowledge_save": "medium", "obsidian_save": "medium",
-    # write local FS (arbitrary path — treated as medium; blocked from system roots below)
-    "local_write": "medium",
-    # preview
-    "preview_url": "medium",
-    # execute commands
-    "run_command": "high",
-    # computer control
-    "computer_click": "high", "computer_type": "high", "computer_key": "high",
-    "computer_scroll": "high", "computer_drag": "high", "computer_move": "high",
-    "computer_open_app": "high", "computer_open_url": "high",
+class ToolPolicy(TypedDict):
+    risk: str         # "read" | "write" | "exec" | "destructive"
+    destructive: bool # True = data loss possible, no auto-undo
+    shell: bool       # True = spawns a subprocess
+    network: bool     # True = makes external network calls
+    auto_approve: bool# True = agent may call without human confirmation
+    sandbox: str      # "workspace" | "home" | "system"
+    rollback: str     # "none" | "backup" | "git"
+
+
+_R = lambda s, sb="workspace", ro="none": ToolPolicy(risk="read",        destructive=False, shell=False, network=False, auto_approve=True,  sandbox=sb, rollback=ro)
+_RS = lambda s, sb="workspace", ro="none": ToolPolicy(risk="read",       destructive=False, shell=True,  network=False, auto_approve=True,  sandbox=sb, rollback=ro)
+_RN = lambda s, sb="system",    ro="none": ToolPolicy(risk="read",       destructive=False, shell=True,  network=True,  auto_approve=True,  sandbox=sb, rollback=ro)
+_W = lambda s, sb="workspace", ro="none": ToolPolicy(risk="write",       destructive=False, shell=False, network=False, auto_approve=False, sandbox=sb, rollback=ro)
+_E = lambda s, sb="workspace", ro="none": ToolPolicy(risk="exec",        destructive=False, shell=True,  network=False, auto_approve=False, sandbox=sb, rollback=ro)
+_EN = lambda s, sb="workspace", ro="none": ToolPolicy(risk="exec",       destructive=False, shell=True,  network=True,  auto_approve=False, sandbox=sb, rollback=ro)
+_EC = lambda s, sb="system",   ro="none": ToolPolicy(risk="exec",        destructive=False, shell=False, network=False, auto_approve=False, sandbox=sb, rollback=ro)
+_D = lambda s, sb="workspace", ro="none": ToolPolicy(risk="destructive", destructive=True,  shell=True,  network=False, auto_approve=False, sandbox=sb, rollback=ro)
+
+TOOL_GOVERNANCE: Dict[str, ToolPolicy] = {
+    # ── read-only / workspace ──────────────────────────────────────────────────
+    "list_dir":           _R("list_dir"),
+    "workspace_tree":     _R("workspace_tree"),
+    "read_file":          _R("read_file"),
+    "search_files":       _R("search_files"),
+    "grep":               _R("grep"),
+    "inspect_html":       _R("inspect_html"),
+    "todo_read":          _R("todo_read"),
+    # ── read-only / home FS ───────────────────────────────────────────────────
+    "local_list":         _R("local_list",  sb="home"),
+    "local_read":         _R("local_read",  sb="home"),
+    # ── read-only / git (spawns subprocess, read-only) ───────────────────────
+    "git_status":         _RS("git_status"),
+    "git_diff":           _RS("git_diff"),
+    "git_log":            _RS("git_log"),
+    "git_show":           _RS("git_show"),
+    # ── read-only / knowledge ─────────────────────────────────────────────────
+    "knowledge_search":   _R("knowledge_search", sb="home"),
+    "knowledge_tree":     _R("knowledge_tree",   sb="home"),
+    "obsidian_search":    _R("obsidian_search",  sb="home"),
+    "obsidian_tree":      _R("obsidian_tree",    sb="home"),
+    # ── read-only / system ────────────────────────────────────────────────────
+    "computer_screenshot":_R("computer_screenshot", sb="system"),
+    "computer_status":    _R("computer_status",     sb="system"),
+    "chrome_status":      _R("chrome_status",       sb="system"),
+    "computer_use_status":_R("computer_use_status", sb="system"),
+    "network_status":     _RN("network_status"),
+    # ── write / workspace ─────────────────────────────────────────────────────
+    "write_file":         _W("write_file",       ro="git"),
+    "edit_file":          _W("edit_file",        ro="git"),
+    "create_web_project": _W("create_web_project"),
+    "create_docx":        _W("create_docx"),
+    "create_xlsx":        _W("create_xlsx"),
+    "create_pptx":        _W("create_pptx"),
+    "create_pdf":         _W("create_pdf"),
+    "preview_url":        _W("preview_url"),
+    "todo_write":         _W("todo_write"),
+    # ── write / home FS ───────────────────────────────────────────────────────
+    "knowledge_save":     _W("knowledge_save",  sb="home"),
+    "obsidian_save":      _W("obsidian_save",   sb="home"),
+    "local_write":        _W("local_write",     sb="home"),
+    # ── exec / workspace ──────────────────────────────────────────────────────
+    "run_command":        _E("run_command"),
+    "build_project":      _E("build_project"),
+    # ── exec / network ────────────────────────────────────────────────────────
+    "deploy_project":     _EN("deploy_project"),
+    # ── exec / computer use (system-level input injection) ───────────────────
+    "computer_click":     _EC("computer_click"),
+    "computer_type":      _EC("computer_type"),
+    "computer_key":       _EC("computer_key"),
+    "computer_scroll":    _EC("computer_scroll"),
+    "computer_drag":      _EC("computer_drag"),
+    "computer_move":      _EC("computer_move"),
+    "computer_open_app":  _EC("computer_open_app"),
+    "computer_open_url":  ToolPolicy(risk="exec", destructive=False, shell=False, network=True,  auto_approve=False, sandbox="system",    rollback="none"),
 }
 
-# Paths that local_write must never target (system-level protection)
+_TOOL_GOVERNANCE_DEFAULT = ToolPolicy(
+    risk="write", destructive=False, shell=False, network=False,
+    auto_approve=False, sandbox="workspace", rollback="none",
+)
+
+# Tools that require admin role — computer control + shell execution
+ADMIN_ONLY_TOOLS: frozenset[str] = frozenset(
+    name for name, policy in TOOL_GOVERNANCE.items()
+    if policy["sandbox"] == "system" or policy["risk"] in {"exec", "destructive"}
+)
+
+def _check_tool_role(tool_name: str, current_user: str) -> None:
+    if tool_name not in ADMIN_ONLY_TOOLS:
+        return
+    users = load_users()
+    if get_user_role(current_user, users) != "admin":
+        raise HTTPException(
+            status_code=403,
+            detail=f"'{tool_name}' 툴은 관리자 전용입니다.",
+        )
+
+# Paths that local_write / local_list must never target
 _LOCAL_WRITE_BLOCKED_PREFIXES = (
     "/etc/", "/usr/", "/bin/", "/sbin/", "/System/", "/private/etc/",
     "/Library/LaunchDaemons/", "/Library/LaunchAgents/",
 )
 
+# Backward-compat: map policy risk → legacy low/medium/high string
+_RISK_LEVEL_MAP = {"read": "low", "write": "medium", "exec": "high", "destructive": "high"}
 
-def _agent_risk(action_name: str, args: dict) -> str:
-    """Return risk level for an action, upgrading local_write to 'high' for system paths."""
-    risk = _TOOL_RISK.get(action_name, "medium")
+
+def _agent_policy(action_name: str, args: dict) -> ToolPolicy:
+    """Return the full governance policy for an action.
+
+    Upgrades local_write to destructive risk when targeting system paths.
+    """
+    policy = TOOL_GOVERNANCE.get(action_name, _TOOL_GOVERNANCE_DEFAULT)
     if action_name == "local_write":
         path = str(args.get("path", ""))
         if any(path.startswith(p) for p in _LOCAL_WRITE_BLOCKED_PREFIXES):
-            risk = "high"
-    return risk
+            policy = ToolPolicy(
+                risk="destructive", destructive=True, shell=False, network=False,
+                auto_approve=False, sandbox="system", rollback="none",
+            )
+    return policy
+
+
+def _agent_risk(action_name: str, args: dict) -> str:
+    """Return legacy low/medium/high risk string (kept for transcript backward-compat)."""
+    return _RISK_LEVEL_MAP.get(_agent_policy(action_name, args)["risk"], "medium")
+
+
+# ── Tool Permission Layer ─────────────────────────────────────────────────────
+# A compact, public-facing view of each tool's authorization profile, derived
+# from TOOL_GOVERNANCE. Designed for client UIs / approval dialogs that don't
+# need the full 7-dimensional governance object.
+#
+# Example:
+#   { "tool": "shell", "risk": "high", "requires_approval": true, "network": false }
+
+class ToolPermission(TypedDict):
+    tool: str
+    risk: str                 # "low" | "medium" | "high"
+    requires_approval: bool   # inverse of governance.auto_approve
+    network: bool             # tool makes external network calls
+
+
+def get_tool_permission(name: str, args: Optional[dict] = None) -> ToolPermission:
+    """Return the simplified permission view for a tool name.
+
+    `args` lets path-sensitive tools (e.g. local_write to /etc) escalate risk;
+    omit it for static catalog views.
+    """
+    policy = _agent_policy(name, args or {})
+    return ToolPermission(
+        tool=name,
+        risk=_RISK_LEVEL_MAP.get(policy["risk"], "medium"),
+        requires_approval=not policy["auto_approve"],
+        network=policy["network"],
+    )
+
+
+def list_tool_permissions() -> list:
+    """Return permission views for every governed tool, sorted by tool name."""
+    return [get_tool_permission(name) for name in sorted(TOOL_GOVERNANCE.keys())]
 
 
 def _collect_created_files(transcript: list) -> list:
@@ -3250,142 +4319,421 @@ def _extract_agent_action(raw: str) -> Dict:
     return action
 
 
-@app.post("/agent")
-async def agent(req: AgentRequest, request: Request):
-    """Natural-language local agent loop for Telegram and future clients."""
-    current_user = require_user(request)
-    enforce_rate_limit(current_user, "agent")
-    if not router.current_model_id:
-        raise HTTPException(status_code=400, detail="No model loaded. Call /models/load first.")
+# ── Agent State Machine — Phase Functions ─────────────────────────────────────
 
-    ensure_agent_root()
-    transcript = []
-    max_steps = max(1, min(req.max_steps, 10))
-    lang = detect_language(req.message)
-    lang_hint = _LANG_HINT[lang]
+async def _phase_plan(
+    ctx: AgentRunContext, req: AgentRequest, router, lang_hint: str, current_user: str,
+) -> None:
+    """PLAN: Planner role produces a structured plan JSON."""
+    context = (
+        f"{PLANNER_PROMPT}\n\n"
+        f"[LANGUAGE HINT: {lang_hint}]\n"
+        f"Workspace root: {AGENT_ROOT}\n\n"
+        f"User request: {req.message}"
+    )
+    raw = await router.generate(
+        message="Produce a JSON execution plan for this request.",
+        context=context, max_tokens=1024, temperature=0.1,
+    )
+    try:
+        plan = _extract_agent_action(str(raw))
+    except ValueError:
+        plan = {
+            "action": "plan", "state": "PLAN",
+            "goal": req.message, "steps": [],
+            "requires_approval": False, "rollback_strategy": "none", "estimated_steps": 1,
+        }
+    ctx.plan = plan
+    ctx.transcript.append({
+        "state": AgentState.PLANNING.value,
+        "goal": plan.get("goal", req.message),
+        "steps": plan.get("steps", []),
+        "requires_approval": plan.get("requires_approval", False),
+        "rollback_strategy": plan.get("rollback_strategy", "none"),
+        "estimated_steps": plan.get("estimated_steps", 1),
+    })
+    ctx.state = AgentState.WAITING_APPROVAL
+
+
+def _phase_approval(ctx: AgentRunContext, current_user: str) -> None:
+    """APPROVAL: Check governance, log decision, auto-approve (future: UI prompt)."""
+    auto_approve_tools = {name for name, p in TOOL_GOVERNANCE.items() if p["auto_approve"]}
+    steps = ctx.plan.get("steps", [])
+    non_auto = [s.get("action") for s in steps if s.get("action") not in auto_approve_tools]
+    requires = ctx.plan.get("requires_approval", False) or bool(non_auto)
+
+    ctx.transcript.append({
+        "state": AgentState.WAITING_APPROVAL.value,
+        "requires_approval": requires,
+        "non_auto_approve_steps": non_auto,
+        "decision": "auto_approved",
+    })
+    append_audit_event(
+        "agent_approval", user_email=current_user,
+        requires_approval=requires, non_auto_steps=non_auto, decision="auto_approved",
+    )
+    ctx.state = AgentState.EXECUTING
+
+
+async def _phase_execute(
+    ctx: AgentRunContext, req: AgentRequest, router, lang_hint: str,
+    current_user: str, max_steps: int,
+) -> None:
+    """EXECUTE: Executor role calls tools one at a time until final or budget exhausted."""
+    exec_count = sum(1 for s in ctx.transcript if s.get("state") == AgentState.EXECUTING.value)
+    budget = max(1, max_steps - exec_count)
+
+    for _ in range(budget):
+        corrections_hint = (
+            "\n\nCritic corrections from previous attempt:\n"
+            + "\n".join(f"- {c}" for c in ctx.corrections)
+        ) if ctx.corrections else ""
 
-    for step in range(max_steps):
-        recent_context = build_recent_chat_context(conversation_id=req.conversation_id)
         context = (
-            f"{AGENT_SYSTEM_PROMPT}\n\n"
-            f"[LANGUAGE: {lang_hint}]\n\n"
+            f"{EXECUTOR_PROMPT}\n\n"
+            f"[LANGUAGE HINT: {lang_hint}]\n"
             f"Workspace root: {AGENT_ROOT}\n\n"
-            f"Recent conversation:\n{recent_context or '(none)'}\n\n"
-            f"User request:\n{req.message}\n\n"
-            f"Previous tool results:\n{json.dumps(transcript, ensure_ascii=False, indent=2)}"
+            f"PLAN:\n{json.dumps(ctx.plan, ensure_ascii=False)}\n\n"
+            f"Recent conversation:\n{build_recent_chat_context(conversation_id=req.conversation_id) or '(none)'}\n\n"
+            f"User request: {req.message}{corrections_hint}\n\n"
+            f"Execution transcript:\n{json.dumps(ctx.transcript, ensure_ascii=False, indent=2)}"
         )
         raw = await router.generate(
-            message="Choose the next agent action.",
-            context=context,
-            max_tokens=4096,
-            temperature=req.temperature,
+            message="Execute the next step.",
+            context=context, max_tokens=4096, temperature=req.temperature,
         )
-
         try:
             action = _extract_agent_action(str(raw))
         except ValueError as exc:
-            transcript.append({"step": step + 1, "action": "parse_error", "raw": str(raw), "error": str(exc)})
-            message = "작업 계획을 안정적으로 해석하지 못해 자동 실행을 중단했습니다. 요청을 더 짧고 구체적으로 다시 시도해 주세요."
-            save_to_history("user", req.message, source=req.source or "web", conversation_id=req.conversation_id)
-            save_to_history("assistant", message, source=req.source or "web", conversation_id=req.conversation_id)
-            created_files = _collect_created_files(transcript)
-            return {
-                "status": "ok",
-                "response": message,
-                "workspace": str(AGENT_ROOT),
-                "steps": transcript,
-                "created_files": created_files,
-            }
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value, "action": "parse_error",
+                "raw": str(raw)[:400], "error": str(exc),
+            })
+            break
+
+        name     = action.get("action")
+        thoughts = str(action.get("thoughts") or "")[:600]
+        args     = action.get("args") or {}
 
-        name = action.get("action")
         if name == "final":
-            message = action.get("message", "작업을 완료했습니다.")
-            save_to_history("user", req.message, source=req.source or "web", conversation_id=req.conversation_id)
-            save_to_history("assistant", message, source=req.source or "web", conversation_id=req.conversation_id)
-            created_files = _collect_created_files(transcript)
-            return {"status": "ok", "response": message, "workspace": str(AGENT_ROOT), "steps": transcript, "created_files": created_files}
-
-        # Prevent repeated file/project creation loops with identical action+args.
-        last_step = transcript[-1] if transcript else None
-        current_args = action.get("args") or {}
+            ctx.final_message = action.get("message", "작업을 완료했습니다.")
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value, "action": "final", "thoughts": thoughts,
+            })
+            ctx.state = AgentState.VERIFYING
+            return
+
+        # Loop guard
+        exec_steps = [s for s in ctx.transcript if s.get("state") == AgentState.EXECUTING.value]
+        last = exec_steps[-1] if exec_steps else None
         if (
-            name in _FILE_CREATE_ACTIONS
-            and last_step
-            and last_step.get("action") == name
-            and (last_step.get("args") or {}) == current_args
-            and "result" in last_step
+            name in _FILE_CREATE_ACTIONS and last
+            and last.get("action") == name
+            and (last.get("args") or {}) == args
+            and "result" in last
         ):
-            message = "요청한 파일 생성을 이미 완료해서 반복 실행을 중단했습니다."
-            save_to_history("user", req.message, source=req.source or "web", conversation_id=req.conversation_id)
-            save_to_history("assistant", message, source=req.source or "web", conversation_id=req.conversation_id)
-            created_files = _collect_created_files(transcript)
-            return {"status": "ok", "response": message, "workspace": str(AGENT_ROOT), "steps": transcript, "created_files": created_files}
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value, "action": name,
+                "error": "LOOP_DETECTED: identical action+args repeated — halted.",
+            })
+            break
 
         if name == "clear_history":
-            result = clear_history(current_args.get("keep_last", 0))
-            append_audit_event(
-                "history_delete",
-                user_email=current_user,
-                source=req.source or "agent",
-                keep_last=current_args.get("keep_last", 0),
-                removed=result.get("removed", 0),
-                kept=result.get("kept", 0),
-            )
-            transcript.append({"step": step + 1, "action": name, "args": current_args, "result": result})
+            result = clear_history(args.get("keep_last", 0))
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value, "action": name,
+                "thoughts": thoughts, "args": args, "result": result,
+            })
             continue
 
-        risk = _agent_risk(name, current_args)
+        policy = _agent_policy(name, args)
+        risk   = _RISK_LEVEL_MAP.get(policy["risk"], "medium")
 
-        # Block system-path local_write even if the LLM tries it
-        if name == "local_write":
-            path = str(current_args.get("path", ""))
-            if any(path.startswith(p) for p in _LOCAL_WRITE_BLOCKED_PREFIXES):
-                transcript.append({
-                    "step": step + 1, "action": name, "args": current_args,
-                    "risk": "high", "error": f"BLOCKED: writing to system path is not allowed: {path}",
-                })
-                append_audit_event(
-                    "agent_blocked", user_email=current_user, source=req.source or "agent",
-                    action=name, path=path, reason="system_path",
-                )
-                continue
+        if policy["risk"] == "destructive":
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value, "action": name,
+                "thoughts": thoughts, "args": args, "risk": risk,
+                "governance": dict(policy),
+                "error": f"BLOCKED: destructive action '{name}' not permitted in agent mode.",
+            })
+            append_audit_event(
+                "agent_blocked", user_email=current_user, source=req.source or "agent",
+                action=name, reason="destructive", governance=dict(policy),
+            )
+            continue
 
-        # Audit medium/high actions before execution
-        if risk in ("medium", "high"):
+        if not policy["auto_approve"]:
             append_audit_event(
                 "agent_exec", user_email=current_user, source=req.source or "agent",
-                step=step + 1, action=name, risk=risk,
-                args={k: v for k, v in (current_args or {}).items() if k != "content"},
+                state=AgentState.EXECUTING.value, action=name, risk=risk,
+                shell=policy["shell"], network=policy["network"],
+                destructive=policy["destructive"], sandbox=policy["sandbox"],
+                rollback=policy["rollback"],
+                args={k: v for k, v in args.items() if k != "content"},
             )
 
         try:
-            result = execute_tool(name, current_args)
-            transcript.append({"step": step + 1, "action": name, "args": current_args, "risk": risk, "result": result})
+            _check_tool_role(name, current_user)
+            result = execute_tool(name, args)
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value, "action": name,
+                "thoughts": thoughts, "args": args,
+                "risk": risk, "governance": dict(policy), "result": result,
+            })
         except (ToolError, KeyError, TypeError) as exc:
-            transcript.append({"step": step + 1, "action": name, "args": current_args, "risk": risk, "error": str(exc)})
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value, "action": name,
+                "thoughts": thoughts, "args": args,
+                "risk": risk, "governance": dict(policy), "error": str(exc),
+            })
 
-    summary_context = (
-        f"{AGENT_SYSTEM_PROMPT}\n\n"
-        f"Recent conversation:\n{build_recent_chat_context(conversation_id=req.conversation_id) or '(none)'}\n\n"
-        f"User request:\n{req.message}\n\n"
-        f"Tool transcript:\n{json.dumps(transcript, ensure_ascii=False, indent=2)}"
+    ctx.state = AgentState.VERIFYING
+
+
+async def _phase_verify(
+    ctx: AgentRunContext, req: AgentRequest, router, lang_hint: str, current_user: str,
+    max_retry: int = 3,
+) -> None:
+    """VERIFYING: Critic role evaluates transcript → DONE / EXECUTING (retry) / ROLLBACK / FAILED."""
+    context = (
+        f"{CRITIC_PROMPT}\n\n"
+        f"[LANGUAGE HINT: {lang_hint}]\n\n"
+        f"Original request: {req.message}\n"
+        f"Plan goal: {ctx.plan.get('goal', req.message)}\n\n"
+        f"Full transcript:\n{json.dumps(ctx.transcript, ensure_ascii=False, indent=2)}"
     )
-    summary = await router.generate(
-        message='Return only {"action":"final","message":"..."} summarizing the current result in Korean.',
-        context=summary_context,
-        max_tokens=1024,
-        temperature=0.1,
+    raw = await router.generate(
+        message="Review the execution transcript and return your verdict JSON.",
+        context=context, max_tokens=512, temperature=0.1,
     )
     try:
-        final_action = _extract_agent_action(str(summary))
-        message = final_action.get("message", str(summary))
+        verdict = _extract_agent_action(str(raw))
     except ValueError:
-        message = str(summary)
+        verdict = {"action": "verdict", "verdict": "PASS", "next_state": "DONE",
+                   "reason": "Critic parse failed — assuming pass.", "corrections": [], "confidence": 0.7}
+
+    ctx.corrections = verdict.get("corrections", [])
+    # Normalize legacy verdict next_state strings to current AgentState names
+    raw_next = verdict.get("next_state", "DONE")
+    next_s = {"COMPLETE": "DONE", "RETRY": "EXECUTING"}.get(raw_next, raw_next)
+
+    ctx.transcript.append({
+        "state": AgentState.VERIFYING.value,
+        "verdict":     verdict.get("verdict", "PASS"),
+        "reason":      verdict.get("reason", ""),
+        "corrections": ctx.corrections,
+        "confidence":  verdict.get("confidence", 0.9),
+        "next_state":  next_s,
+    })
 
+    if verdict.get("verdict") == "PASS" or next_s == "DONE":
+        if not ctx.final_message:
+            ctx.final_message = verdict.get("reason", "작업이 완료되었습니다.")
+        ctx.state = AgentState.DONE
+    elif next_s == "ROLLBACK":
+        ctx.state = AgentState.ROLLBACK
+    elif next_s == "EXECUTING":
+        if ctx.retry_count >= max_retry:
+            ctx.final_message = (
+                f"최대 재시도({max_retry}회) 초과로 작업을 종료했습니다. "
+                f"마지막 비판: {verdict.get('reason', '(없음)')}"
+            )
+            ctx.state = AgentState.FAILED
+        else:
+            ctx.retry_count += 1
+            ctx.transcript.append({
+                "state": AgentState.EXECUTING.value,
+                "retry_attempt": ctx.retry_count,
+                "corrections": ctx.corrections,
+            })
+            ctx.state = AgentState.EXECUTING
+    else:
+        ctx.final_message = verdict.get("reason", "검증자가 인식되지 않은 다음 상태를 반환했습니다.")
+        ctx.state = AgentState.FAILED
+
+
+def _phase_rollback(ctx: AgentRunContext, current_user: str) -> None:
+    """ROLLBACK: attempt git checkout for each edited file, then COMPLETE."""
+    import subprocess as _sp
+    rolled: list = []
+    for step in ctx.transcript:
+        if step.get("state") != AgentState.EXECUTING.value:
+            continue
+        gov = step.get("governance", {})
+        if gov.get("rollback") != "git":
+            continue
+        result = step.get("result", {})
+        if not (isinstance(result, dict) and result.get("success")):
+            continue
+        path = result.get("path") or (step.get("args") or {}).get("path", "")
+        if not path:
+            continue
+        try:
+            r = _sp.run(
+                ["git", "checkout", "--", path], cwd=str(AGENT_ROOT),
+                capture_output=True, text=True, timeout=10,
+            )
+            rolled.append({"path": path, "ok": r.returncode == 0, "stderr": r.stderr[:200]})
+        except Exception as exc:
+            rolled.append({"path": path, "ok": False, "error": str(exc)})
+
+    ctx.transcript.append({"state": AgentState.ROLLBACK.value, "rolled_back": rolled})
+    recovered = [r["path"] for r in rolled if r.get("ok")]
+    ctx.final_message = (
+        f"실행 실패로 롤백했습니다. 복구 파일: {recovered}"
+        if recovered
+        else "롤백을 시도했으나 복구할 파일이 없거나 git이 초기화되지 않았습니다."
+    )
+    append_audit_event("agent_rollback", user_email=current_user, rolled_back=rolled)
+    # Rollback is a recovery from a failed verification — terminal state is FAILED
+    ctx.state = AgentState.FAILED
+
+
+async def _phase_memory_update(
+    ctx: AgentRunContext, req: AgentRequest, router, current_user: str,
+) -> None:
+    """Background: Memory Updater role extracts learnings after COMPLETE."""
+    context = (
+        f"{MEMORY_UPDATER_PROMPT}\n\n"
+        f"Completed task: {req.message}\n\n"
+        f"Last 5 transcript steps:\n{json.dumps(ctx.transcript[-5:], ensure_ascii=False)}"
+    )
+    try:
+        raw = await router.generate(
+            message="Extract learnings from this completed task.",
+            context=context, max_tokens=256, temperature=0.1,
+        )
+        mem = _extract_agent_action(str(raw))
+        if mem.get("save_to_knowledge") and mem.get("learnings"):
+            from tools import knowledge_save
+            knowledge_save(
+                "\n".join(mem["learnings"]),
+                folder="30_Projects",
+                title=f"Agent: {req.message[:60]}",
+            )
+    except Exception:
+        pass
+
+
+# ── Eval harness ──────────────────────────────────────────────────────────────
+
+@app.post("/agent/eval")
+async def agent_eval(req: AgentEvalRequest, request: Request):
+    """Run a skill's eval cases from schema.json and return pass/fail per case."""
+    require_user(request)
+    skill_dir = Path(__file__).resolve().parent / "skills" / req.skill
+    schema_path = skill_dir / "schema.json"
+    if not schema_path.exists():
+        raise HTTPException(404, detail=f"Skill '{req.skill}' not found or missing schema.json")
+
+    schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    eval_cases = schema.get("evals", [])
+    if req.case_id:
+        eval_cases = [c for c in eval_cases if c.get("id") == req.case_id]
+    if not eval_cases:
+        return {"skill": req.skill, "total": 0, "passed": 0, "failed": 0, "results": [],
+                "message": "No eval cases defined in schema.json"}
+
+    action_name = schema.get("action", req.skill)
+    results = []
+    for case in eval_cases:
+        case_id = case.get("id", "?")
+        try:
+            result   = execute_tool(action_name, case.get("input", {}))
+            criteria = case.get("pass_criteria", "")
+            if "success == true" in criteria:
+                passed = result.get("success") is True
+            elif "success == false" in criteria:
+                passed = result.get("success") is False
+            else:
+                passed = True  # manual review required
+            results.append({"id": case_id, "description": case.get("description", ""),
+                            "passed": passed, "result": result, "pass_criteria": criteria})
+        except Exception as exc:
+            results.append({"id": case_id, "description": case.get("description", ""),
+                            "passed": False, "error": str(exc),
+                            "pass_criteria": case.get("pass_criteria", "")})
+
+    n_passed = sum(1 for r in results if r.get("passed") is True)
+    return {
+        "skill": req.skill, "action": action_name,
+        "total": len(results), "passed": n_passed, "failed": len(results) - n_passed,
+        "results": results,
+    }
+
+
+@app.post("/agent")
+async def agent(req: AgentRequest, request: Request):
+    """Natural-language local agent.
+
+    State machine:
+        IDLE → PLANNING → WAITING_APPROVAL → EXECUTING → VERIFYING
+                                       ↓                     ↓
+                                     FAILED       DONE | EXECUTING(retry) | ROLLBACK
+                                                                                  ↓
+                                                                               FAILED
+    """
+    current_user = require_user(request)
+    enforce_rate_limit(current_user, "agent")
+    if not router.current_model_id:
+        raise HTTPException(status_code=400, detail="No model loaded. Call /models/load first.")
+
+    ensure_agent_root()
+    lang = detect_language(req.message)
+    lang_hint = _LANG_HINT[lang]
+    max_steps = max(1, min(req.max_steps, 50))
+    max_retry = 3
+
+    ctx = AgentRunContext()
+
+    while ctx.state not in AGENT_TERMINAL_STATES:
+        ctx.state_history.append(ctx.state.value)
+        # Hard guard against infinite state loops
+        if len(ctx.state_history) > 200:
+            ctx.final_message = "에이전트 상태 머신이 최대 반복(200)에 도달해 중단했습니다."
+            ctx.state = AgentState.FAILED
+            break
+
+        if ctx.state == AgentState.IDLE:
+            ctx.state = AgentState.PLANNING
+
+        elif ctx.state == AgentState.PLANNING:
+            await _phase_plan(ctx, req, router, lang_hint, current_user)
+
+        elif ctx.state == AgentState.WAITING_APPROVAL:
+            _phase_approval(ctx, current_user)
+
+        elif ctx.state == AgentState.EXECUTING:
+            await _phase_execute(ctx, req, router, lang_hint, current_user, max_steps)
+
+        elif ctx.state == AgentState.VERIFYING:
+            await _phase_verify(ctx, req, router, lang_hint, current_user, max_retry)
+
+        elif ctx.state == AgentState.ROLLBACK:
+            _phase_rollback(ctx, current_user)
+
+        else:
+            ctx.state = AgentState.FAILED
+
+    # Record terminal state in history for clients
+    ctx.state_history.append(ctx.state.value)
+
+    # Fire-and-forget memory update — does not block the response
+    asyncio.create_task(_phase_memory_update(ctx, req, router, current_user))
+
+    message = ctx.final_message or "작업을 완료했습니다."
     save_to_history("user", req.message, source=req.source or "web", conversation_id=req.conversation_id)
     save_to_history("assistant", message, source=req.source or "web", conversation_id=req.conversation_id)
-    created_files = _collect_created_files(transcript)
-    return {"status": "ok", "response": message, "workspace": str(AGENT_ROOT), "steps": transcript, "created_files": created_files}
+    created_files = _collect_created_files(ctx.transcript)
+    return {
+        "status": "ok" if ctx.state == AgentState.DONE else "failed",
+        "response": message,
+        "workspace": str(AGENT_ROOT),
+        "steps": ctx.transcript,
+        "state_history": ctx.state_history,
+        "final_state": ctx.state.value,
+        "created_files": created_files,
+    }
 
 
 # ── Direct Tool API ───────────────────────────────────────────────────────────
@@ -3410,9 +4758,13 @@ async def tools_workspace_tree(req: ToolWorkspaceTreeRequest, request: Request):
 
 
 @app.post("/tools/read_file")
-async def tools_read_file(req: ToolPathRequest, request: Request):
+async def tools_read_file(req: ToolReadFileRequest, request: Request):
     require_user(request)
-    return _tool_response(read_file, req.path)
+    try:
+        return {"status": "ok", "workspace": str(AGENT_ROOT),
+                "result": read_file(req.path, offset=req.offset, limit=req.limit, line_numbers=req.line_numbers)}
+    except ToolError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
 
 
 @app.post("/tools/write_file")
@@ -3421,12 +4773,51 @@ async def tools_write_file(req: ToolWriteFileRequest, request: Request):
     return _tool_response(write_file, req.path, req.content)
 
 
+@app.post("/tools/edit_file")
+async def tools_edit_file(req: ToolEditFileRequest, request: Request):
+    require_user(request)
+    try:
+        return {"status": "ok", "workspace": str(AGENT_ROOT),
+                "result": edit_file(req.path, req.old_string, req.new_string, replace_all=req.replace_all)}
+    except ToolError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
 @app.post("/tools/search_files")
 async def tools_search_files(req: ToolSearchFilesRequest, request: Request):
     require_user(request)
     return _tool_response(search_files, req.query, req.path, req.max_results)
 
 
+@app.post("/tools/grep")
+async def tools_grep(req: ToolGrepRequest, request: Request):
+    require_user(request)
+    try:
+        return {"status": "ok", "workspace": str(AGENT_ROOT),
+                "result": grep(
+                    req.pattern,
+                    path=req.path,
+                    glob=req.glob,
+                    max_results=req.max_results,
+                    case_insensitive=req.case_insensitive,
+                    context_lines=req.context_lines,
+                )}
+    except ToolError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@app.post("/tools/todo_read")
+async def tools_todo_read(request: Request):
+    require_user(request)
+    return _tool_response(todo_read)
+
+
+@app.post("/tools/todo_write")
+async def tools_todo_write(req: ToolTodoWriteRequest, request: Request):
+    require_user(request)
+    return _tool_response(todo_write, req.todos)
+
+
 @app.post("/tools/clear_history")
 async def tools_clear_history(req: ToolClearHistoryRequest, request: Request):
     current_user = require_user(request)
@@ -3806,7 +5197,7 @@ async def cu_drag(req: CuDragRequest, request: Request):
 @app.post("/cu/agent")
 async def cu_agent(req: CuAgentRequest, request: Request):
     """SSE streaming Computer Use agent loop."""
-    require_user(request)
+    require_admin(request)
     async def _stream():
         task_lower = (req.task or "").lower()
         url_match = re.search(r"(https?://[^\s]+|localhost:\d+[^\s]*|127\.0\.0\.1:\d+[^\s]*)", req.task or "")
@@ -3981,7 +5372,7 @@ async def tools_git_show(req: ToolGitShowRequest, request: Request):
 
 @app.post("/tools/run_command")
 async def tools_run_command(req: ToolRunCommandRequest, request: Request):
-    require_user(request)
+    require_admin(request)
     return _tool_response(run_command, req.command, req.cwd)
 
 
@@ -3993,71 +5384,106 @@ async def tools_network_status(request: Request):
 
 @app.post("/tools/build_project")
 async def tools_build_project(req: ToolScriptRequest, request: Request):
-    require_user(request)
+    require_admin(request)
     return _tool_response(build_project, req.cwd, req.script)
 
 
 @app.post("/tools/deploy_project")
 async def tools_deploy_project(req: ToolScriptRequest, request: Request):
-    require_user(request)
+    require_admin(request)
     return _tool_response(deploy_project, req.cwd, req.script)
 
 
+_MCP_TOOL_DESCRIPTIONS: Dict[str, str] = {
+    "list_dir":              "List files in the agent workspace.",
+    "workspace_tree":        "Return a recursive workspace tree.",
+    "read_file":             "Read a UTF-8 file from the workspace with optional line numbers and offset/limit slicing.",
+    "write_file":            "Write a UTF-8 file inside the workspace (new files / full rewrites).",
+    "edit_file":             "Precise diff-style edit: replace exact old_string with new_string. Requires unique match unless replace_all=true.",
+    "search_files":          "Substring search in text files (legacy).",
+    "grep":                  "Regex search across the workspace with line numbers and optional context.",
+    "todo_read":             "Read the agent's persistent TODO list for the current workspace.",
+    "todo_write":            "Replace the agent's TODO list (id, content, status: pending/in_progress/completed).",
+    "clear_history":         "Clear chat history to reduce context and speed up responses.",
+    "inspect_html":          "Inspect local HTML structure and assets.",
+    "preview_url":           "Return a server URL for a workspace file.",
+    "create_docx":           "Create a Word DOCX document in the agent workspace.",
+    "create_xlsx":           "Create an XLSX spreadsheet in the agent workspace.",
+    "create_pptx":           "Create a PPTX presentation deck in the agent workspace.",
+    "create_pdf":            "Create a PDF document in the agent workspace.",
+    "local_list":            "List any local folder (requires user permission via UI).",
+    "local_read":            "Read any local file (requires user permission via UI).",
+    "local_write":           "Write any local file (requires user permission via UI).",
+    "read_document":         "Extract text from PDF, DOCX, XLSX, PPTX, TXT, MD, CSV files.",
+    "computer_screenshot":   "Capture the current Mac screen as base64 PNG.",
+    "computer_open_app":     "Open or focus a Mac app, e.g. Google Chrome.",
+    "computer_open_url":     "Open a URL in a Mac app, e.g. Google Chrome.",
+    "computer_click":        "Click at screen coordinates (x, y).",
+    "computer_type":         "Type text at the current focus position.",
+    "computer_key":          "Press a keyboard key or shortcut (e.g. 'command+c').",
+    "computer_scroll":       "Scroll at screen coordinates.",
+    "computer_move":         "Move the mouse to screen coordinates.",
+    "computer_drag":         "Drag from (x1,y1) to (x2,y2).",
+    "computer_status":       "Check if Mac Computer Use (pyautogui) is available.",
+    "chrome_status":         "Report Chrome desktop bridge availability.",
+    "computer_use_status":   "Report Mac Computer Use bridge availability.",
+    "knowledge_save":        "Save a note into the local knowledge garden.",
+    "knowledge_search":      "Search the local knowledge garden.",
+    "knowledge_tree":        "List local knowledge garden markdown files.",
+    "knowledge_graph_ingest":"Ingest a message, AI answer, or connector event into the SQLite knowledge graph.",
+    "knowledge_graph_search":"Search graph nodes, summaries, and JSON metadata.",
+    "knowledge_graph_graph": "Return Obsidian-style graph nodes and edges.",
+    "knowledge_graph_context":"Return compact graph-backed RAG context for a prompt.",
+    "obsidian_save":         "Save a note into the Obsidian-compatible memory vault.",
+    "obsidian_search":       "Search the Obsidian-compatible memory vault.",
+    "obsidian_tree":         "List Obsidian memory vault markdown files.",
+    "git_status":            "Read-only local git status inside the workspace.",
+    "git_diff":              "Read-only local git diff inside the workspace.",
+    "git_log":               "Read-only local git log inside the workspace.",
+    "git_show":              "Read-only local git show --stat inside the workspace.",
+    "network_status":        "Get current local/private IP, public IP, hostname, and Wi-Fi info.",
+    "run_command":           "Run an allowlisted local command inside the workspace.",
+    "build_project":         "Run an allowlisted package.json build/compile/typecheck/test script to verify changes actually work.",
+    "deploy_project":        "Run an allowlisted package.json deploy/preview/release/package installer script (pkg/exe).",
+}
+
+
+@app.get("/tools/permissions")
+async def tools_permissions(request: Request):
+    """Compact tool permission view (tool / risk / requires_approval / network).
+
+    A simpler authorization-layer summary derived from TOOL_GOVERNANCE.
+    Use /mcp/tools for the full 7-dimensional governance object.
+    """
+    require_user(request)
+    return {"status": "ok", "permissions": list_tool_permissions()}
+
+
 @app.get("/mcp/tools")
 async def mcp_tools():
     installed = load_mcp_installs().get("installed", {})
+    tools = []
+    for name, description in _MCP_TOOL_DESCRIPTIONS.items():
+        policy = TOOL_GOVERNANCE.get(name, _TOOL_GOVERNANCE_DEFAULT)
+        tools.append({
+            "name": name,
+            "description": description,
+            "permission": get_tool_permission(name),
+            "governance": {
+                "risk":         policy["risk"],
+                "destructive":  policy["destructive"],
+                "shell":        policy["shell"],
+                "network":      policy["network"],
+                "auto_approve": policy["auto_approve"],
+                "sandbox":      policy["sandbox"],
+                "rollback":     policy["rollback"],
+            },
+        })
     return {
         "status": "ok",
         "workspace": str(AGENT_ROOT),
         "installed_mcps": [mcp_public_item(item, installed) for item in MCP_REGISTRY],
-        "tools": [
-            {"name": "list_dir", "description": "List files in the agent workspace."},
-            {"name": "workspace_tree", "description": "Return a recursive workspace tree."},
-            {"name": "read_file", "description": "Read a UTF-8 file from the workspace."},
-            {"name": "write_file", "description": "Write a UTF-8 file inside the workspace."},
-            {"name": "search_files", "description": "Search text files inside the workspace."},
-            {"name": "clear_history", "description": "Clear chat history to reduce context and speed up responses."},
-            {"name": "inspect_html", "description": "Inspect local HTML structure and assets."},
-            {"name": "preview_url", "description": "Return a server URL for a workspace file."},
-            {"name": "create_docx", "description": "Create a Word DOCX document in the agent workspace."},
-            {"name": "create_xlsx", "description": "Create an XLSX spreadsheet in the agent workspace."},
-            {"name": "create_pptx", "description": "Create a PPTX presentation deck in the agent workspace."},
-            {"name": "create_pdf", "description": "Create a PDF document in the agent workspace."},
-            {"name": "local_list", "description": "List any local folder (requires user permission via UI)."},
-            {"name": "local_read", "description": "Read any local file (requires user permission via UI)."},
-            {"name": "local_write", "description": "Write any local file (requires user permission via UI)."},
-            {"name": "read_document", "description": "Extract text from PDF, DOCX, XLSX, PPTX, TXT, MD, CSV files."},
-            {"name": "computer_screenshot", "description": "Capture the current Mac screen as base64 PNG."},
-            {"name": "computer_open_app", "description": "Open or focus a Mac app, e.g. Google Chrome."},
-            {"name": "computer_open_url", "description": "Open a URL in a Mac app, e.g. Google Chrome."},
-            {"name": "computer_click", "description": "Click at screen coordinates (x, y)."},
-            {"name": "computer_type", "description": "Type text at the current focus position."},
-            {"name": "computer_key", "description": "Press a keyboard key or shortcut (e.g. 'command+c')."},
-            {"name": "computer_scroll", "description": "Scroll at screen coordinates."},
-            {"name": "computer_move", "description": "Move the mouse to screen coordinates."},
-            {"name": "computer_drag", "description": "Drag from (x1,y1) to (x2,y2)."},
-            {"name": "computer_status", "description": "Check if Mac Computer Use (pyautogui) is available."},
-            {"name": "chrome_status", "description": "Report Chrome desktop bridge availability."},
-            {"name": "computer_use_status", "description": "Report Mac Computer Use bridge availability."},
-            {"name": "knowledge_save", "description": "Save a note into the local knowledge garden."},
-            {"name": "knowledge_search", "description": "Search the local knowledge garden."},
-            {"name": "knowledge_tree", "description": "List local knowledge garden markdown files."},
-            {"name": "knowledge_graph_ingest", "description": "Ingest a message, AI answer, or connector event into the SQLite knowledge graph."},
-            {"name": "knowledge_graph_search", "description": "Search graph nodes, summaries, and JSON metadata."},
-            {"name": "knowledge_graph_graph", "description": "Return Obsidian-style graph nodes and edges."},
-            {"name": "knowledge_graph_context", "description": "Return compact graph-backed RAG context for a prompt."},
-            {"name": "obsidian_save", "description": "Save a note into the Obsidian-compatible memory vault."},
-            {"name": "obsidian_search", "description": "Search the Obsidian-compatible memory vault."},
-            {"name": "obsidian_tree", "description": "List Obsidian memory vault markdown files."},
-            {"name": "git_status", "description": "Read-only local git status inside the workspace."},
-            {"name": "git_diff", "description": "Read-only local git diff inside the workspace."},
-            {"name": "git_log", "description": "Read-only local git log inside the workspace."},
-            {"name": "git_show", "description": "Read-only local git show --stat inside the workspace."},
-            {"name": "network_status", "description": "Get current local/private IP, public IP, hostname, and Wi-Fi info."},
-            {"name": "run_command", "description": "Run an allowlisted local command inside the workspace."},
-            {"name": "build_project", "description": "Run an allowlisted package.json build/compile/typecheck/test script."},
-            {"name": "deploy_project", "description": "Run an allowlisted package.json deploy/preview/release/package installer script (pkg/exe)."},
-        ],
+        "tools": tools,
     }
 
 
@@ -4115,6 +5541,7 @@ async def mcp_call(req: McpCallRequest, request: Request):
                 args.get("limit", 6),
             )
         }
+    _check_tool_role(req.action, current_user)
     return _tool_response(execute_tool, req.action, req.args or {})