local-coding-agent 1.1.0__py3-none-any.whl

local_coding_agent/desktop/server/_handlers.py

@@ -0,0 +1,2178 @@
+"""HTTP request handler serving the Desktop UI and REST endpoints."""
+
+from __future__ import annotations
+
+import http.client
+import hmac
+import json
+import os
+import re
+import shutil
+import subprocess
+import time
+import urllib.request
+import uuid
+from dataclasses import replace
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+from ...controller import mediated_apply
+from ...doctor import remediate_environment
+from ...memory import ModelMemoryManager
+from ...model_scanner import discover_llama_server_binary, get_live_system_path
+from ...ollama_adapter import OllamaError, build_client
+from ...profiles import ModelProfile, get_profile, list_profiles
+from ...task import TaskEnvelope
+from ...validators import apply_patch, parse_unified_diff
+from ...vram_fit import ContextFit, fit_context, kv_bytes_per_token, read_gguf_ctx_params
+from ..ui import render_desktop_html
+from ._models import (
+    _classify_backend_error,
+    discover_local_ollama_models,
+    find_discovered_gguf,
+    resolve_model_profile,
+    select_available_profile,
+)
+from ._telemetry import get_nvidia_gpu_telemetry
+
+# Bounded recent-prompt history feeding the hybrid mode router's isolated
+# context. Kept module-level (not on server state) so DesktopServer.__init__
+# needs no change. Mutations are guarded by server_inst.apply_lock; a deque
+# could replace the list if it ever needs to grow past a small bound.
+_MAX_RECENT_PROMPTS = 6
+_recent_prompts: list[str] = []
+_ASSET_DIR = Path(__file__).resolve().parent.parent / "assets"
+
+# Hard resource ceiling for a client-supplied context override. The per-model
+# VRAM preflight in _launch_llama_model clamps below this, but the cap keeps a
+# hostile/mistyped request from ever reaching llama-server.
+_MAX_CTX_OVERRIDE = 262144
+_DEFAULT_LLAMA_CTX = 8192
+_MAX_REQUEST_BODY_BYTES = 8 * 1024 * 1024
+_MAX_BODY_READ_CHUNK = 64 * 1024
+_MAX_REJECTED_BODY_DRAIN = 64 * 1024
+_REQUEST_BODY_IDLE_TIMEOUT = 2.0
+
+
+class _RequestBodyError(ValueError):
+    """A request body cannot be safely framed or read."""
+
+    def __init__(self, status: HTTPStatus, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+def build_queue_controller(profile_name: str, workspace_str: str, cancel_event: Any = None) -> Any:
+    """Build the real Controller for a queued desktop task.
+
+    Mirrors _handle_delegate's construction exactly (resolve_model_profile ->
+    build_client -> Controller) and resolves symbols through this module's
+    namespace, so tests can monkeypatch ``build_client`` / the Controller
+    class with the existing idioms. The background worker passes a
+    cooperative cancel Event through to the controller.
+    """
+    profile = resolve_model_profile(profile_name)
+    client = build_client(profile)
+    from ...controller import Controller
+
+    return Controller(client, workspace_str, cancel_event=cancel_event)
+
+
+class DesktopRequestHandler(BaseHTTPRequestHandler):
+    """HTTP request handler serving the Desktop UI and REST endpoints."""
+
+    @property
+    def server_inst(self) -> Any:
+        return getattr(self.server, "desktop_server", self.server)
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        path = parsed.path.rstrip("/")
+
+        if path in {"", "/app", "/index.html"}:
+            self._send_response(
+                HTTPStatus.OK,
+                "text/html; charset=utf-8",
+                render_desktop_html(self.server_inst.mutation_token).encode("utf-8"),
+            )
+        elif path == "/assets/tailwind.css":
+            self._send_asset("tailwind.css", "text/css; charset=utf-8")
+        elif path == "/assets/lucide.min.js":
+            self._send_asset("lucide.min.js", "text/javascript; charset=utf-8")
+        elif path in {"/api/status", "/status"}:
+            self._handle_status()
+        elif path in {"/api/gpu", "/gpu", "/api/gpu/telemetry"}:
+            self._handle_gpu_telemetry()
+        elif path in {"/api/models", "/models", "/api/profiles"}:
+            self._handle_models()
+        elif path in {"/api/sessions", "/sessions"}:
+            self._handle_sessions()
+        elif path in {"/api/tasks", "/tasks"}:
+            self._handle_tasks_list()
+        elif path in {"/api/workspace/files", "/workspace/files"}:
+            self._handle_workspace_files()
+        elif path in {"/api/health", "/health"}:
+            self._send_json({"status": "ok", "uptime": round(time.monotonic() - self.server_inst.started_at, 2)})
+        elif path == "/v1/models":
+            self._handle_v1_models()
+        else:
+            self._send_response(HTTPStatus.NOT_FOUND, "text/plain; charset=utf-8", b"404 Not Found\n")
+
+    def do_POST(self) -> None:
+        parsed = urlparse(self.path)
+        path = parsed.path.rstrip("/")
+
+        self._request_body = None
+        try:
+            content_length = self._parse_content_length()
+        except _RequestBodyError as error:
+            self._send_request_body_error(error)
+            return
+
+        rejection = self._unsafe_mutation_reason(content_length)
+        if rejection:
+            # Windows may reset a connection when the handler closes it while
+            # the client request body is still buffered.  Drain the declared
+            # body before returning the intentional 403 so callers receive
+            # the rejection instead of a transport-level connection abort.
+            # The drain is capped; a connection with unread bytes is closed
+            # rather than being reused with an unknown request boundary.
+            try:
+                self._discard_request_body(content_length)
+            except _RequestBodyError as error:
+                self._send_request_body_error(error)
+                return
+            self._send_json(
+                {"status": "rejected", "error": rejection},
+                HTTPStatus.FORBIDDEN,
+            )
+            return
+
+        try:
+            self._request_body = self._read_request_body(content_length)
+        except _RequestBodyError as error:
+            self._send_request_body_error(error)
+            return
+
+        if path in {"/api/chat", "/chat"}:
+            self._handle_chat()
+        elif path in {"/api/delegate", "/delegate"}:
+            self._handle_delegate()
+        elif path in {"/api/tasks", "/tasks"}:
+            self._handle_tasks_submit()
+        elif path in {"/api/tasks/cancel", "/tasks/cancel"}:
+            self._handle_tasks_cancel()
+        elif path in {"/api/apply", "/apply"}:
+            self._handle_apply()
+        elif path in {"/api/rollback", "/rollback"}:
+            self._handle_rollback()
+        elif path in {"/api/server/start", "/server/start"}:
+            self._handle_server_start()
+        elif path in {"/api/server/stop", "/server/stop"}:
+            self._handle_server_stop()
+        elif path in {"/api/model/load", "/model/load"}:
+            self._handle_model_load()
+        elif path in {"/api/model/unload", "/model/unload"}:
+            self._handle_model_unload()
+        elif path in {"/api/model/unload_all", "/model/unload_all"}:
+            self._handle_model_unload_all()
+        elif path in {"/api/doctor/fix", "/doctor/fix"}:
+            self._handle_doctor_fix()
+        elif path in {"/api/sessions", "/sessions"}:
+            self._handle_create_session()
+        elif path in {"/api/models/scan", "/models/scan"}:
+            self._handle_model_scan()
+        elif path == "/v1/chat/completions":
+            self._handle_v1_chat_completions()
+        elif path in {"/api/models/add_dir", "/models/add_dir"}:
+            self._handle_model_add_dir()
+        elif path in {"/api/models/remove_dir", "/models/remove_dir"}:
+            self._handle_model_remove_dir()
+        else:
+            self._send_response(HTTPStatus.NOT_FOUND, "text/plain; charset=utf-8", b"404 Not Found\n")
+
+    def _unsafe_mutation_reason(self, content_length: int | None = None) -> str:
+        """Reject browser-driven loopback CSRF while preserving local CLI use."""
+        expected_port = self.server_inst.actual_port
+        allowed_hosts = {
+            f"127.0.0.1:{expected_port}",
+            f"localhost:{expected_port}",
+            f"[::1]:{expected_port}",
+        }
+        host = self.headers.get("Host", "").lower()
+        if host not in allowed_hosts:
+            return "Host must target this loopback desktop server"
+
+        supplied_token = self.headers.get("X-Desktop-Token", "")
+        if not hmac.compare_digest(supplied_token, self.server_inst.mutation_token):
+            return "Missing or invalid desktop mutation token"
+
+        origin = self.headers.get("Origin")
+        if origin:
+            parsed = urlparse(origin)
+            origin_host = (parsed.netloc or "").lower()
+            if parsed.scheme not in {"http", "https"} or origin_host not in allowed_hosts:
+                return "Cross-origin desktop API mutations are not allowed"
+
+        if content_length is None:
+            content_length = self._parse_content_length()
+        content_type = self.headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
+        if content_length > 0 and content_type != "application/json":
+            return "State-changing request bodies must use application/json"
+        return ""
+
+    def _parse_content_length(self) -> int:
+        """Parse one bounded Content-Length or reject ambiguous framing."""
+        values = None
+        get_all = getattr(self.headers, "get_all", None)
+        if get_all is not None:
+            values = get_all("Content-Length")
+        if values is None:
+            raw = self.headers.get("Content-Length")
+            values = [] if raw is None else [raw]
+        if len(values) > 1:
+            raise _RequestBodyError(HTTPStatus.BAD_REQUEST, "Exactly one Content-Length header is required")
+
+        transfer_encoding = self.headers.get("Transfer-Encoding", "")
+        if transfer_encoding.strip():
+            raise _RequestBodyError(
+                HTTPStatus.BAD_REQUEST,
+                "Transfer-Encoding is unsupported; use a single Content-Length header",
+            )
+        if not values:
+            return 0
+
+        raw = str(values[0]).strip()
+        if not raw or not re.fullmatch(r"[0-9]+", raw):
+            raise _RequestBodyError(
+                HTTPStatus.BAD_REQUEST,
+                "Content-Length must be a non-negative decimal integer",
+            )
+        digits = raw.lstrip("0") or "0"
+        maximum = str(_MAX_REQUEST_BODY_BYTES)
+        if len(digits) > len(maximum) or (len(digits) == len(maximum) and digits > maximum):
+            raise _RequestBodyError(
+                HTTPStatus.REQUEST_ENTITY_TOO_LARGE,
+                f"Request body exceeds the {_MAX_REQUEST_BODY_BYTES}-byte limit",
+            )
+        return int(digits)
+
+    def _read_request_body(self, length: int, *, retain: bool = True) -> bytes:
+        """Read exactly ``length`` bytes with a bounded per-read idle timeout."""
+        if length <= 0:
+            return b""
+
+        connection = getattr(self, "connection", None)
+        original_timeout = None
+        if connection is not None:
+            original_timeout = connection.gettimeout()
+            connection.settimeout(_REQUEST_BODY_IDLE_TIMEOUT)
+        chunks: list[bytes] = []
+        remaining = length
+        try:
+            while remaining:
+                try:
+                    chunk = self.rfile.read(min(remaining, _MAX_BODY_READ_CHUNK))
+                except (TimeoutError, OSError) as error:
+                    raise _RequestBodyError(
+                        HTTPStatus.BAD_REQUEST,
+                        "Request body was incomplete or idle before its Content-Length was satisfied",
+                    ) from error
+                if not chunk:
+                    raise _RequestBodyError(
+                        HTTPStatus.BAD_REQUEST,
+                        "Request body was shorter than its Content-Length",
+                    )
+                remaining -= len(chunk)
+                if retain:
+                    chunks.append(chunk)
+        finally:
+            if connection is not None:
+                connection.settimeout(original_timeout)
+        return b"".join(chunks) if retain else b""
+
+    def _discard_request_body(self, length: int | None = None) -> None:
+        """Drain a bounded rejected body and close if bytes remain unsynchronized."""
+        if length is None:
+            try:
+                length = self._parse_content_length()
+            except _RequestBodyError:
+                return
+        if length <= 0:
+            return
+        drain_length = min(length, _MAX_REJECTED_BODY_DRAIN)
+        if drain_length < length:
+            self.close_connection = True
+        self._read_request_body(drain_length, retain=False)
+
+    def _read_json_body(self) -> dict[str, Any]:
+        body = getattr(self, "_request_body", None)
+        if body is None:
+            body = self._read_request_body(self._parse_content_length())
+        if not body:
+            return {}
+        try:
+            val = json.loads(body.decode("utf-8"))
+            return val if isinstance(val, dict) else {}
+        except Exception:
+            return {}
+
+    def _send_asset(self, filename: str, content_type: str) -> None:
+        try:
+            body = (_ASSET_DIR / filename).read_bytes()
+        except OSError:
+            self._send_response(HTTPStatus.NOT_FOUND, "text/plain; charset=utf-8", b"Asset not found\n")
+            return
+        self._send_response(HTTPStatus.OK, content_type, body)
+
+    def _handle_status(self) -> None:
+        workspace = self.server_inst.workspace
+        branch = "main"
+        try:
+            res = subprocess.run(
+                ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                cwd=workspace,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if res.returncode == 0 and res.stdout.strip():
+                branch = res.stdout.strip()
+        except Exception:
+            pass
+
+        # Check server endpoints with loading / ready distinction
+        ollama_online, ollama_status = self._probe_server_status("http://127.0.0.1:11434/api/tags")
+        llama_online, llama_status = self._probe_server_status("http://127.0.0.1:8080/v1/models")
+
+        # 1. First priority: real hardware readings from nvidia-smi.  Missing
+        # telemetry is an unknown, never a synthetic 16 GiB "System GPU".
+        gpu_telemetry = get_nvidia_gpu_telemetry()
+        vram_info = gpu_telemetry or {
+            "status": "unavailable",
+            "source": "nvidia-smi",
+            "error": "GPU telemetry is unavailable on this host",
+            "gpu_name": None,
+            "used_mb": None,
+            "total_mb": None,
+            "used_gb": None,
+            "total_gb": None,
+            "percent": None,
+            "utilization_pct": None,
+            "temp_c": None,
+        }
+
+        # Ollama can confirm loaded-model bytes, but /api/ps is not a GPU
+        # capacity source. Keep this partial observation separate from VRAM
+        # capacity and percentage fields.
+        if not gpu_telemetry and ollama_online:
+            try:
+                client = build_client(get_profile(self.server_inst.default_profile))
+                snap = ModelMemoryManager(client).snapshot()
+                if snap.is_supported:
+                    vram_info["loaded_models"] = [
+                        {
+                            "name": model.name,
+                            "size_vram": model.size_vram,
+                            "size": model.size,
+                            "expires_at": model.expires_at,
+                        }
+                        for model in snap.models
+                    ]
+                    vram_info["loaded_vram_bytes"] = snap.total_vram_bytes
+                    vram_info["loaded_vram_source"] = "ollama:/api/ps"
+            except Exception:
+                pass
+
+        task_counts = {"queued": 0, "running": 0}
+        for record in self.server_inst.load_tasks():
+            status = record.get("status")
+            if status in task_counts:
+                task_counts[status] += 1
+
+        payload = {
+            "status": "healthy",
+            "uptime_seconds": round(time.monotonic() - self.server_inst.started_at, 2),
+            "workspace": str(Path(workspace).resolve()),
+            "workspace_name": Path(workspace).resolve().name,
+            "git_branch": branch,
+            "profile": self.server_inst.default_profile,
+            "servers": {
+                "ollama": {"online": ollama_online, "status": ollama_status, "endpoint": "http://127.0.0.1:11434"},
+                "llama_server": {
+                    "online": llama_online,
+                    "status": llama_status,
+                    "endpoint": "http://127.0.0.1:8080",
+                    "requested_ctx": self.server_inst.llama_num_ctx,
+                    "effective_ctx": self.server_inst.llama_effective_ctx,
+                },
+            },
+            "vram": vram_info,
+            "stats": self.server_inst.stats.snapshot() if self.server_inst.stats else {},
+            "tasks": task_counts,
+        }
+        self._send_json(payload)
+
+    def _handle_gpu_telemetry(self) -> None:
+        gpu = get_nvidia_gpu_telemetry()
+        if gpu and gpu.get("status") == "ok":
+            self._send_json({"status": "ok", "gpu": gpu})
+        else:
+            self._send_json({
+                "status": gpu.get("status", "unavailable") if gpu else "unavailable",
+                "message": gpu.get("error", "nvidia-smi telemetry not available on this host") if gpu else "nvidia-smi telemetry not available on this host",
+            })
+
+    def _handle_models(self) -> None:
+        profiles_data = []
+        for name in list_profiles():
+            prof = get_profile(name)
+            profiles_data.append({
+                "name": name,
+                "model": prof.model,
+                "provider": prof.provider,
+                "endpoint": prof.endpoint,
+                "num_ctx": prof.num_ctx,
+                "policy_context_cap": prof.max_context_length,
+                "model_context_limit": prof.model_context_limit,
+            })
+
+        ollama_online, _ = self._probe_server_status("http://127.0.0.1:11434/api/tags")
+        ollama_models = discover_local_ollama_models()
+
+        llama_online, _ = self._probe_server_status("http://127.0.0.1:8080/v1/models")
+        llama_models = self._list_llama_model_ids() if llama_online else []
+
+        from ...model_scanner import get_model_registry
+        discovered_ggufs = [m.to_dict() for m in get_model_registry().get_models(auto_scan=True)]
+
+        self._send_json({
+            "profiles": profiles_data,
+            "active_profile": self.server_inst.default_profile,
+            "backends": {
+                "ollama": {"online": ollama_online, "endpoint": "http://127.0.0.1:11434", "models": ollama_models},
+                "llama_server": {"online": llama_online, "endpoint": "http://127.0.0.1:8080", "models": llama_models},
+                "local_gguf": {"models": discovered_ggufs},
+            },
+        })
+
+    def _handle_model_scan(self) -> None:
+        from ...model_scanner import get_model_registry
+        data = self._read_json_body()
+        deep = bool(data.get("deep", False))
+        registry = get_model_registry()
+        models = registry.scan(deep=deep)
+        self._send_json({"status": "ok", "total_models": len(models), "models": [m.to_dict() for m in models]})
+
+    def _handle_model_add_dir(self) -> None:
+        from ...model_scanner import get_model_registry
+        data = self._read_json_body()
+        path_val = data.get("path", "").strip()
+        if not path_val or not Path(path_val).is_dir():
+            self._send_json({"status": "failed", "error": f"Directory does not exist: {path_val}"})
+            return
+        added = get_model_registry().add_custom_directory(path_val)
+        self._send_json({"status": "added" if added else "already_present", "path": path_val})
+
+    def _handle_model_remove_dir(self) -> None:
+        from ...model_scanner import get_model_registry
+        data = self._read_json_body()
+        path_val = data.get("path", "").strip()
+        removed = get_model_registry().remove_custom_directory(path_val)
+        self._send_json({"status": "removed" if removed else "not_found", "path": path_val})
+
+    def _handle_workspace_files(self) -> None:
+        workspace = Path(self.server_inst.workspace)
+        files = []
+        for p in workspace.rglob("*"):
+            if p.is_file() and not any(part.startswith(".") or part in ("__pycache__", "venv", ".git", "build", "dist", "node_modules") for part in p.parts):
+                rel = str(p.relative_to(workspace).as_posix())
+                files.append({
+                    "path": rel,
+                    "name": p.name,
+                    "size_bytes": p.stat().st_size,
+                    "is_code": p.suffix in (".py", ".ts", ".js", ".go", ".rs", ".json", ".md"),
+                })
+        files.sort(key=lambda x: (not x["is_code"], x["path"]))
+        self._send_json({"workspace": str(workspace), "files": files[:80]})
+
+    def _handle_sessions(self) -> None:
+        try:
+            self._send_json({"sessions": self.server_inst.load_sessions()})
+        except Exception as error:
+            self._send_json({"status": "failed", "sessions": [], "error": str(error)})
+
+    def _handle_create_session(self) -> None:
+        data = self._read_json_body()
+        session_id = data.get("id") or f"sess-{uuid.uuid4().hex[:12]}"
+        session_type = data.get("type", "user")
+        title = data.get("title", "New Task Session")
+        file_path = data.get("file", "src/main.py")
+        patch = data.get("patch", "")
+        checks = data.get("checks", [])
+
+        session = {
+            "id": session_id,
+            "type": session_type,
+            "title": title,
+            "file": file_path,
+            "patch": patch,
+            "checks": checks,
+            "status": data.get("status", "Active"),
+            "evidence_verified": False,
+            "time": "Just now",
+        }
+        for key in (
+            "prompt",
+            "profile",
+            "message",
+            "thinking",
+            "testResult",
+            "plan",
+            "test_evidence",
+            "files",
+        ):
+            if key in data:
+                session[key] = data[key]
+        try:
+            self.server_inst.save_session(session)
+        except Exception as error:
+            self._send_json({"status": "failed", "persisted": False, "error": str(error)})
+            return
+        self._send_json({"status": "created", "persisted": True, "session": session})
+
+    def _save_chat_session(
+        self,
+        response: dict[str, Any],
+        task_checks: list[str],
+        *,
+        status: str,
+        evidence_verified: bool = False,
+    ) -> None:
+        prompt = str(response.get("prompt") or "")
+        session = {
+            "id": response.get("task_id") or f"sess-{uuid.uuid4().hex[:12]}",
+            "type": "user",
+            "mode": response.get("mode", "chat"),
+            "title": prompt[:50] + ("..." if len(prompt) > 50 else ""),
+            "prompt": prompt,
+            "profile": response.get("profile", self.server_inst.default_profile),
+            "file": response.get("file", "workspace"),
+            "files": response.get("files") or [],
+            "patch": response.get("patch", ""),
+            "checks": task_checks,
+            "test_evidence": response.get("checks") or [],
+            "status": status,
+            "evidence_verified": evidence_verified,
+            "time": "Just now",
+            "message": response.get("message", ""),
+            "thinking": response.get("thinking", ""),
+            "testResult": response.get("testResult", "NOT RUN"),
+        }
+        if response.get("plan") is not None:
+            session["plan"] = response["plan"]
+        try:
+            self.server_inst.save_session(session)
+            response["persisted"] = True
+        except Exception as error:
+            response["persisted"] = False
+            response["persistence_error"] = str(error)
+
+    def _server_log_file(self, backend: str) -> Path:
+        log_dir = Path(self.server_inst.workspace) / ".local_agent" / "logs"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        return log_dir / f"{backend}.log"
+
+    def _read_log_tail(self, backend: str, n: int = 40) -> str:
+        log_file = self._server_log_file(backend)
+        if not log_file.exists():
+            return ""
+        try:
+            with open(log_file, "r", encoding="utf-8", errors="replace") as fh:
+                lines = fh.readlines()
+            return "".join(lines[-n:])
+        except Exception:
+            return ""
+
+    def _wait_for_ready(self, url: str, proc: subprocess.Popen, backend: str, timeout: float = 30.0) -> dict:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            online, status = self._probe_server_status(url)
+            if online and status == "ready":
+                return {"ok": True, "status": "started"}
+            if proc.poll() is not None:
+                return {
+                    "ok": False,
+                    "status": "failed",
+                    "error": f"Server exited during startup (code {proc.returncode}). Log tail:\n{self._read_log_tail(backend)}",
+                }
+            time.sleep(0.5)
+
+        if proc.poll() is not None:
+            return {
+                "ok": False,
+                "status": "failed",
+                "error": f"Server exited during startup (code {proc.returncode}). Log tail:\n{self._read_log_tail(backend)}",
+            }
+        return {
+            "ok": False,
+            "status": "loading",
+            "message": "server started but not ready yet",
+        }
+
+    def _handle_server_start(self) -> None:
+        data = self._read_json_body()
+        backend = data.get("backend", "ollama")
+        custom_path = data.get("custom_path")
+        model_path = data.get("model_path")
+
+        if backend == "ollama":
+            ollama_bin = self._find_ollama_bin()
+            if not ollama_bin:
+                self._send_json({"status": "failed", "error": "Ollama executable not found. Please install Ollama from ollama.com"})
+                return
+            try:
+                log_handle = open(self._server_log_file("ollama"), "ab")
+                proc = subprocess.Popen(
+                    [ollama_bin, "serve"],
+                    stdout=log_handle,
+                    stderr=log_handle,
+                    creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+                )
+                log_handle.close()
+                self.server_inst.spawned_processes["ollama"] = proc
+                result = self._wait_for_ready("http://127.0.0.1:11434/api/tags", proc, "ollama")
+                if result.get("status") == "started":
+                    self._send_json({"status": "started", "backend": "ollama", "pid": proc.pid})
+                else:
+                    self._send_json(result)
+            except Exception as error:
+                self._send_json({"status": "failed", "error": f"{error}\nLog tail:\n{self._read_log_tail('ollama')}"})
+
+        elif backend in ("llama_server", "llama.cpp"):
+            if self._probe_models_loaded("http://127.0.0.1:8080/v1/models"):
+                self._send_json({
+                    "status": "already_running",
+                    "backend": "llama_server",
+                    "endpoint": "http://127.0.0.1:8080",
+                })
+                return
+
+            llama_bin = self._find_llama_server_bin(custom_path)
+            if not llama_bin:
+                self._send_json({
+                    "status": "failed",
+                    "error": (
+                        "llama-server executable not found in system PATH. "
+                        "Add your llama-server directory to PATH or set LLAMA_SERVER_PATH."
+                    ),
+                })
+                return
+
+            self._kill_llama_on_port(8080)
+            gguf_path = self._find_gguf_model(model_path)
+            cmd = [llama_bin, "--port", "8080"]
+            if gguf_path:
+                alias = Path(gguf_path).stem
+                cmd.extend(["-m", gguf_path, "-c", str(self.server_inst.llama_num_ctx), "--alias", alias])
+                self.server_inst.llama_gguf_path = gguf_path
+                self.server_inst.llama_gguf_label = alias
+
+            try:
+                log_handle = open(self._server_log_file("llama_server"), "ab")
+                proc = subprocess.Popen(
+                    cmd,
+                    stdout=log_handle,
+                    stderr=log_handle,
+                    creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+                )
+                log_handle.close()
+                self.server_inst.spawned_processes["llama_server"] = proc
+                if gguf_path:
+                    result = self._wait_for_model_loaded(proc, "llama_server")
+                else:
+                    result = self._wait_for_ready("http://127.0.0.1:8080/v1/models", proc, "llama_server")
+                if result.get("status") == "started":
+                    self._send_json({
+                        "status": "started",
+                        "backend": "llama_server",
+                        "pid": proc.pid,
+                        "bin": llama_bin,
+                        "model": gguf_path or "unspecified",
+                    })
+                else:
+                    self._send_json(result)
+            except Exception as error:
+                self._send_json({"status": "failed", "error": f"{error}\nLog tail:\n{self._read_log_tail('llama_server')}"})
+        else:
+            self._send_json({"status": "failed", "error": f"Unknown backend: {backend}"})
+
+    def _find_llama_server_bin(self, custom: str | None = None) -> str | None:
+        return discover_llama_server_binary(custom)
+
+    def _find_ollama_bin(self) -> str | None:
+        live_path = get_live_system_path()
+        ollama_bin = shutil.which("ollama", path=live_path) or shutil.which("ollama.exe", path=live_path)
+        if not ollama_bin:
+            appdata_ollama = Path(os.path.expandvars(r"%LOCALAPPDATA%\Programs\Ollama\ollama.exe"))
+            if appdata_ollama.exists():
+                ollama_bin = str(appdata_ollama)
+        return ollama_bin
+
+    def _ensure_ollama_running(self) -> bool:
+        """Start ollama serve if offline; return True when the API is reachable."""
+        online, _ = self._probe_server_status("http://127.0.0.1:11434/api/tags")
+        if online:
+            return True
+        ollama_bin = self._find_ollama_bin()
+        if not ollama_bin:
+            return False
+        try:
+            log_handle = open(self._server_log_file("ollama"), "ab")
+            proc = subprocess.Popen(
+                [ollama_bin, "serve"],
+                stdout=log_handle,
+                stderr=log_handle,
+                creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+            )
+            log_handle.close()
+            self.server_inst.spawned_processes["ollama"] = proc
+        except Exception:
+            return False
+        result = self._wait_for_ready("http://127.0.0.1:11434/api/tags", proc, "ollama")
+        return result.get("status") == "started"
+
+    def _find_gguf_model(self, custom: str | None = None) -> str | None:
+        if custom and custom.strip() and Path(custom.strip()).is_file():
+            return str(Path(custom.strip()).resolve())
+
+        env_model = os.environ.get("LLAMA_MODEL_PATH") or os.environ.get("GGUF_MODEL_PATH")
+        if env_model and Path(env_model.strip()).is_file():
+            return str(Path(env_model.strip()).resolve())
+
+        return None
+
+    def _handle_server_stop(self) -> None:
+        data = self._read_json_body()
+        backend = data.get("backend", "all")
+        stopped = []
+
+        for name in list(self.server_inst.spawned_processes):
+            if backend in (name, "all"):
+                self._stop_backend(name)
+                stopped.append(name)
+
+        self._send_json({"status": "stopped", "backends": stopped})
+
+    def _auto_fit_llama_ctx(self, gguf: dict) -> int | None:
+        """Fit llama-server ctx from GGUF metadata + free VRAM for num_ctx=auto.
+
+        Best-effort: never raises; leaves ``llama_num_ctx`` untouched when the
+        metadata, exact model size, or VRAM telemetry is unavailable.  A
+        numeric context is applied only for an explicit ``fits`` result.
+        """
+        params = read_gguf_ctx_params(gguf["path"])
+        gpu = get_nvidia_gpu_telemetry()
+        if not gpu or not isinstance(gpu.get("total_mb"), (int, float)) or not isinstance(gpu.get("used_mb"), (int, float)):
+            return None
+        total_mb = float(gpu["total_mb"])
+        used_mb = float(gpu["used_mb"])
+        if total_mb <= 0 or used_mb < 0 or used_mb > total_mb:
+            return None
+        try:
+            weights_bytes = Path(gguf["path"]).stat().st_size
+        except (KeyError, OSError, TypeError):
+            return None
+        kv = (
+            kv_bytes_per_token(
+                params["n_layers"], params["n_head_kv"], params["head_dim"]
+            )
+            if params.get("n_layers") and params.get("n_head_kv") and params.get("head_dim")
+            else 0
+        )
+        native = params.get("native_context_length")
+        if not native:
+            return None
+        result = fit_context(
+            int((total_mb - used_mb) * 1024 * 1024),
+            weights_bytes,
+            kv,
+            max_ctx=native,
+        )
+        if result.status == "fits" and result.context is not None:
+            return result.context
+        return None
+
+    def _handle_model_load(self) -> None:
+        data = self._read_json_body()
+        model_name = data.get("model") or self.server_inst.default_profile
+        requested_ctx = data.get("num_ctx")
+        requested_llama_ctx = None
+        if requested_ctx is not None and requested_ctx != "auto":
+            ctx, ctx_error = self._parse_ctx_override(requested_ctx)
+            if ctx_error:
+                self._send_json({"status": "failed", "error": ctx_error}, HTTPStatus.BAD_REQUEST)
+                return
+            requested_llama_ctx = ctx
+        try:
+            gguf = find_discovered_gguf(model_name)
+            if gguf and gguf.get("path"):
+                launch_ctx = requested_llama_ctx
+                if requested_ctx == "auto":
+                    auto_ctx = self._auto_fit_llama_ctx(gguf)
+                    # Evaluate auto for the new model.  If fit evidence is
+                    # unavailable, use the documented launch default rather
+                    # than inheriting a previous model's context.
+                    launch_ctx = auto_ctx or _DEFAULT_LLAMA_CTX
+                result = self._launch_llama_model(
+                    gguf["path"],
+                    gguf.get("display_name") or gguf.get("name") or model_name,
+                    num_ctx=launch_ctx,
+                )
+                if result.get("status") == "started":
+                    try:
+                        warmup = ModelProfile(
+                            name=gguf.get("display_name") or model_name,
+                            model=gguf.get("display_name") or model_name,
+                            provider="openai",
+                            endpoint="http://127.0.0.1:8080",
+                            num_ctx=self.server_inst.llama_num_ctx,
+                        )
+                        build_client(warmup).complete("warmup", system="warmup", max_tokens=1)
+                    except Exception:
+                        pass
+                    self._send_json({
+                        "status": "loaded",
+                        "model": model_name,
+                        "backend": "llama_server",
+                        "path": gguf["path"],
+                        "effective_ctx": self.server_inst.llama_effective_ctx,
+                        **({"ctx_warning": result["ctx_warning"]} if result.get("ctx_warning") else {}),
+                    })
+                else:
+                    self._send_json(result)
+                return
+
+            prof = resolve_model_profile(model_name)
+            client = build_client(prof)
+            if prof.provider == "ollama":
+                if not self._ensure_ollama_running():
+                    self._send_json({"status": "failed", "error": "Ollama (port 11434) could not be started. Start it manually or check PATH."})
+                    return
+                if hasattr(client, "_request_json"):
+                    try:
+                        client._request_json("POST", "/api/generate", {"model": prof.model, "prompt": "", "keep_alive": "10m"})
+                    except OllamaError as oe:
+                        if "not found" in str(oe).lower():
+                            base = prof.model.split(":", 1)[0]
+                            candidates = [prof.model, f"{base}:latest", base]
+                            avail = set()
+                            try:
+                                for m in client.available_models().get("models", []):
+                                    if isinstance(m, dict) and "name" in m:
+                                        avail.add(m["name"])
+                            except Exception:
+                                avail = set(discover_local_ollama_models())
+                            alt = next((c for c in candidates if c in avail), None)
+                            if alt is None:
+                                raise
+                            client._request_json("POST", "/api/generate", {"model": alt, "prompt": "", "keep_alive": "10m"})
+                        else:
+                            raise
+                else:
+                    client.complete("warmup", system="warmup", max_tokens=1)
+            elif prof.provider == "openai":
+                if hasattr(client, "complete"):
+                    client.complete("warmup", system="warmup", max_tokens=1)
+                elif hasattr(client, "chat"):
+                    client.chat([{"role": "user", "content": "warmup"}])
+            else:
+                if hasattr(client, "complete"):
+                    client.complete("warmup", system="warmup", max_tokens=1)
+            self._send_json({"status": "loaded", "model": model_name, "backend": prof.provider})
+        except Exception as error:
+            kind = _classify_backend_error(error)
+            if kind == "offline":
+                is_llama = prof.provider == "openai"
+                backend_name = "llama-server (port 8080)" if is_llama else "Ollama (port 11434)"
+                self._send_json({"status": "failed", "error": f"{backend_name} is OFFLINE. Start it in Local Inference Servers."})
+            else:
+                self._send_json({"status": "failed", "error": str(error)})
+
+    def _launch_llama_model(self, gguf_path: str, model_label: str, num_ctx: int | None = None) -> dict:
+        """Launch llama-server with a specific GGUF file (single-model server).
+
+        Uses ``--alias`` so the model id exposed by ``/v1/models`` is the clean
+        stem (e.g. ``Ling-3.0-tiny-Q6_K``) rather than the on-disk filename.
+        ``-ngl`` is intentionally omitted: forcing ``-ngl 99`` aborts the load
+        when free VRAM cannot fit every layer, whereas the default auto-fit
+        spills only the overflow to CPU.
+
+        Resource preflight (P1): before stopping the running server, the
+        requested context is clamped to what the GGUF geometry + free VRAM
+        actually fit, so a typo'd 200k window cannot wedge the machine.
+        On a failed relaunch the previous configuration is relaunched once so
+        the user keeps a working server.
+        """
+        previous_ctx = self.server_inst.llama_num_ctx
+        previous_path = self.server_inst.llama_gguf_path
+        previous_label = self.server_inst.llama_gguf_label
+        effective_ctx = num_ctx
+        ctx_warning = ""
+        if num_ctx is not None:
+            requested = max(512, int(num_ctx))
+            fit = self._preflight_context_fit(gguf_path)
+            if fit.status == "does_not_fit":
+                return {
+                    "status": "failed",
+                    "error": fit.reason or "Requested context cannot fit the verified model and VRAM resources.",
+                }
+            if fit.status == "fits" and fit.context is not None and fit.context != requested:
+                ctx_warning = (
+                    f"Requested context {requested} exceeds what free VRAM fits next to "
+                    f"the model weights; clamped to {fit.context} tokens."
+                )
+                effective_ctx = fit.context
+        llama_bin = self._find_llama_server_bin(None)
+        if not llama_bin:
+            return {
+                "status": "failed",
+                "error": (
+                    "llama-server executable not found in PATH. "
+                    "Add your llama-server directory to PATH or set LLAMA_SERVER_PATH."
+                ),
+            }
+        if effective_ctx is not None:
+            self.server_inst.llama_num_ctx = max(512, int(effective_ctx))
+        self._stop_backend("llama_server")
+        self._kill_llama_on_port(8080)
+        cmd = [
+            llama_bin, "--port", "8080", "-m", gguf_path,
+            "-c", str(self.server_inst.llama_num_ctx), "--alias", model_label,
+        ]
+        try:
+            log_handle = open(self._server_log_file("llama_server"), "ab")
+            proc = subprocess.Popen(
+                cmd,
+                stdout=log_handle,
+                stderr=log_handle,
+                creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+            )
+            log_handle.close()
+            self.server_inst.spawned_processes["llama_server"] = proc
+            self.server_inst.llama_gguf_path = gguf_path
+            self.server_inst.llama_gguf_label = model_label
+            result = self._wait_for_model_loaded(proc, "llama_server")
+            if result.get("status") == "started":
+                effective = self._read_effective_ctx()
+                self.server_inst.llama_effective_ctx = effective
+                if effective is not None and effective != self.server_inst.llama_num_ctx:
+                    readback = (
+                        f"Requested context {self.server_inst.llama_num_ctx} via -c "
+                        f"but llama-server reports n_ctx={effective}; the window was "
+                        "likely clamped to the model's native context length."
+                    )
+                    ctx_warning = f"{ctx_warning} {readback}".strip() if ctx_warning else readback
+                result.update({"backend": "llama_server", "pid": proc.pid, "model": model_label})
+                if ctx_warning:
+                    result["ctx_warning"] = ctx_warning
+                return result
+            failure = result
+        except Exception as error:
+            failure = {"status": "failed", "error": f"{error}\nLog tail:\n{self._read_log_tail('llama_server')}"}
+
+        # Relaunch failed: restore the previous working configuration once so
+        # the risky reload never leaves the machine without a server.
+        self.server_inst.llama_num_ctx = previous_ctx
+        self.server_inst.llama_gguf_path = previous_path
+        self.server_inst.llama_gguf_label = previous_label
+        if previous_path:
+            restore = self._launch_llama_model(previous_path, previous_label or Path(previous_path).stem, num_ctx=previous_ctx)
+            if restore.get("status") == "started":
+                failure["restored"] = f"Previous configuration restored ({Path(previous_path).name}, -c {previous_ctx})."
+            else:
+                failure["restore_error"] = restore.get("error", "unknown error")
+        return failure
+
+    def _preflight_context_fit(self, gguf_path: str) -> ContextFit:
+        """Return an explicit fit state before stopping a running backend."""
+        try:
+            params = read_gguf_ctx_params(gguf_path)
+            n_layers = params.get("n_layers")
+            n_head_kv = params.get("n_head_kv")
+            head_dim = params.get("head_dim")
+            if not (n_layers and n_head_kv and head_dim):
+                return ContextFit("unknown", reason="GGUF KV-cache geometry is unavailable")
+            native = params.get("native_context_length")
+            if not native:
+                return ContextFit("unknown", reason="GGUF native context length is unavailable")
+            gpu = get_nvidia_gpu_telemetry()
+            if not gpu or not isinstance(gpu.get("total_mb"), (int, float)) or not isinstance(gpu.get("used_mb"), (int, float)):
+                return ContextFit("unknown", reason="GPU VRAM telemetry is unavailable")
+            total_mb = float(gpu["total_mb"])
+            used_mb = float(gpu["used_mb"])
+            if total_mb <= 0 or used_mb < 0 or used_mb > total_mb:
+                return ContextFit("unknown", reason="GPU VRAM telemetry is invalid")
+            try:
+                weights_bytes = Path(gguf_path).stat().st_size
+            except OSError:
+                return ContextFit("unknown", reason="GGUF weight size is unavailable")
+            kv = kv_bytes_per_token(n_layers, n_head_kv, head_dim)
+            return fit_context(
+                int((total_mb - used_mb) * 1024 * 1024),
+                weights_bytes,
+                kv,
+                max_ctx=native,
+            )
+        except Exception:
+            return ContextFit("unknown", reason="Context fit could not be verified")
+
+    def _preflight_ctx_fit(self, gguf_path: str, requested: int) -> int | None:
+        """Backward-compatible numeric view of the explicit fit result."""
+        result = self._preflight_context_fit(gguf_path)
+        if result.status == "fits" and result.context is not None and requested > result.context:
+            return result.context
+        return None
+
+    def _wait_for_model_loaded(self, proc: subprocess.Popen, backend: str, timeout: float = 90.0) -> dict:
+        """Wait until llama-server actually exposes a loaded model in /v1/models."""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if self._probe_models_loaded("http://127.0.0.1:8080/v1/models"):
+                return {"ok": True, "status": "started"}
+            if proc.poll() is not None:
+                return {
+                    "ok": False,
+                    "status": "failed",
+                    "error": f"Server exited during startup (code {proc.returncode}). Log tail:\n{self._read_log_tail(backend)}",
+                }
+            time.sleep(1.0)
+        if proc.poll() is not None:
+            return {
+                "ok": False,
+                "status": "failed",
+                "error": f"Server exited during startup (code {proc.returncode}). Log tail:\n{self._read_log_tail(backend)}",
+            }
+        return {"ok": False, "status": "loading", "message": "server started but model not loaded yet"}
+
+    def _probe_models_loaded(self, url: str) -> bool:
+        """Return True only when the backend lists at least one loaded model."""
+        try:
+            req = urllib.request.Request(url)
+            with urllib.request.urlopen(req, timeout=0.5) as resp:
+                if resp.status != 200:
+                    return False
+                data = json.loads(resp.read().decode("utf-8"))
+        except Exception:
+            return False
+        models = data.get("data") or data.get("models") or []
+        return isinstance(models, list) and len(models) > 0
+
+    def _read_effective_ctx(self, port: int = 8080) -> int | None:
+        """Read back the context window llama-server actually serves (/props).
+
+        llama-server may silently clamp ``-c`` to the model's native context
+        length, so verify reality instead of trusting the launch flag. Returns
+        None when /props is unavailable (older builds, external servers).
+        """
+        try:
+            req = urllib.request.Request(f"http://127.0.0.1:{port}/props")
+            with urllib.request.urlopen(req, timeout=2.0) as resp:
+                if resp.status != 200:
+                    return None
+                props = json.loads(resp.read().decode("utf-8"))
+            n_ctx = (props.get("default_generation_settings") or {}).get("n_ctx")
+            return int(n_ctx) if n_ctx else None
+        except Exception:
+            return None
+
+    def _list_llama_model_ids(self) -> list[str]:
+        """Model ids currently served by llama-server /v1/models ([] if offline)."""
+        try:
+            req = urllib.request.Request("http://127.0.0.1:8080/v1/models")
+            with urllib.request.urlopen(req, timeout=0.5) as resp:
+                if resp.status != 200:
+                    return []
+                data = json.loads(resp.read().decode("utf-8"))
+            raw_list = data.get("data") or data.get("models") or []
+            ids = []
+            for m in raw_list:
+                if isinstance(m, dict) and "id" in m:
+                    ids.append(m["id"])
+                elif isinstance(m, dict) and "name" in m:
+                    ids.append(m["name"])
+            return ids
+        except Exception:
+            return []
+
+    def _list_ollama_model_tags(self) -> list[str]:
+        return discover_local_ollama_models()
+
+    def _resolve_v1_target(self, model_id: str) -> tuple[str, int] | None:
+        """Map a requested model id to the local backend that serves it.
+
+        Resident llama-server wins when the id matches (or is unspecified);
+        exact Ollama tag match otherwise; None means no local backend serves it.
+        """
+        if self._probe_server_status("http://127.0.0.1:8080/v1/models")[0]:
+            llama_ids = self._list_llama_model_ids()
+            if not model_id or model_id in llama_ids:
+                return ("127.0.0.1", 8080)
+        if model_id and model_id in self._list_ollama_model_tags():
+            return ("127.0.0.1", 11434)
+        return None
+
+    def _handle_v1_models(self) -> None:
+        """OpenAI-compatible catalog: union of both local backends."""
+        data = [{"id": mid, "object": "model", "owned_by": "llama-server"} for mid in self._list_llama_model_ids()]
+        data.extend({"id": tag, "object": "model", "owned_by": "ollama"} for tag in self._list_ollama_model_tags())
+        self._send_json({"object": "list", "data": data})
+
+    def _handle_v1_chat_completions(self) -> None:
+        """OpenAI-compatible chat proxy to the active local backend.
+
+        Both Ollama and llama-server already speak OpenAI wire format natively,
+        so this is a byte-level router: resolve the model id to a backend and
+        stream the upstream response straight back without translation.
+        """
+        body = getattr(self, "_request_body", None)
+        if body is None:
+            body = self._read_request_body(self._parse_content_length()) or b"{}"
+        try:
+            payload = json.loads(body.decode("utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            payload = {}
+        model_id = str(payload.get("model") or "")
+        target = self._resolve_v1_target(model_id)
+        if target is None:
+            available = sorted(set(self._list_llama_model_ids()) | set(self._list_ollama_model_tags()))
+            self._send_json({
+                "error": {
+                    "message": (
+                        f"Model '{model_id or '(unspecified)'}' is not served by any local backend. "
+                        f"Available models: {available}. Load one via the Desktop Harness "
+                        "(Local Inference Servers panel) and retry."
+                    ),
+                    "type": "model_not_found",
+                    "code": 404,
+                }
+            }, status=HTTPStatus.NOT_FOUND)
+            return
+        host, port = target
+        try:
+            conn = http.client.HTTPConnection(host, port, timeout=600)
+            conn.request(
+                "POST",
+                "/v1/chat/completions",
+                body=body,
+                headers={"Content-Type": "application/json", "Accept": self.headers.get("Accept", "*/*")},
+            )
+            upstream = conn.getresponse()
+            self.send_response(upstream.status)
+            self.send_header("Content-Type", upstream.getheader("Content-Type", "application/json"))
+            self.end_headers()
+            while True:
+                chunk = upstream.read(4096)
+                if not chunk:
+                    break
+                self.wfile.write(chunk)
+                self.wfile.flush()
+            conn.close()
+        except Exception as error:
+            # Headers may already be on the wire mid-stream; then the client
+            # just sees a truncated body — nothing sane left to send.
+            try:
+                self._send_json({
+                    "error": {
+                        "message": f"Upstream {host}:{port} failed: {error}",
+                        "type": "upstream_error",
+                        "code": 502,
+                    }
+                }, status=HTTPStatus.BAD_GATEWAY)
+            except Exception:
+                pass
+
+    def _find_pid_on_port(self, port: int) -> int | None:
+        if os.name == "nt":
+            try:
+                out = subprocess.run(
+                    ["netstat", "-ano", "-p", "tcp"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                    timeout=5,
+                ).stdout
+                for line in out.splitlines():
+                    parts = line.split()
+                    if len(parts) >= 5 and f":{port}" in parts[1] and parts[3].upper() == "LISTENING":
+                        try:
+                            return int(parts[4])
+                        except ValueError:
+                            continue
+            except Exception:
+                pass
+        else:
+            try:
+                out = subprocess.run(
+                    ["lsof", "-ti", f":{port}"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                    timeout=5,
+                ).stdout
+                pid = out.strip().splitlines()[0] if out.strip() else ""
+                if pid.isdigit():
+                    return int(pid)
+            except Exception:
+                pass
+        return None
+
+    def _looks_like_llama(self, pid: int) -> bool:
+        if os.name == "nt":
+            try:
+                out = subprocess.run(
+                    ["tasklist", "/FI", f"PID eq {pid}", "/FO", "CSV", "/NH"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                    timeout=5,
+                ).stdout
+                return "llama" in out.lower()
+            except Exception:
+                return False
+        return True
+
+    def _kill_llama_on_port(self, port: int) -> None:
+        """Stop only a backend owned by this server instance.
+
+        A port lookup cannot prove process ownership: another listener may
+        share a name, expose a similar port (for example ``:80801``), or be a
+        user's independently managed llama-server.  The registered Popen
+        handle is the only trustworthy ownership evidence, and normal launch
+        cleanup already removes that handle before this compatibility hook is
+        reached.  External listeners are therefore left untouched; the next
+        bind reports the real conflict to the caller.
+        """
+        del port  # retained for callers of the old compatibility seam
+        for name, proc in list(self.server_inst.spawned_processes.items()):
+            if name == "llama_server" and proc is not None:
+                self._stop_backend(name)
+
+    def _stop_backend(self, name: str) -> None:
+        proc = self.server_inst.spawned_processes.pop(name, None)
+        if proc is None:
+            return
+        try:
+            if os.name == "nt":
+                subprocess.run(
+                    ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                    capture_output=True,
+                    check=False,
+                )
+            else:
+                proc.terminate()
+                proc.wait(timeout=2.0)
+        except Exception:
+            try:
+                proc.kill()
+            except Exception:
+                pass
+
+    def _handle_model_unload(self) -> None:
+        data = self._read_json_body()
+        model_name = data.get("model")
+        if not model_name:
+            self._send_json({"status": "failed", "error": "model name required"})
+            return
+        try:
+            client = build_client(resolve_model_profile(self.server_inst.default_profile))
+            manager = ModelMemoryManager(client)
+            snap = manager.unload_model(model_name)
+            self._send_json({"status": "unloaded", "model": model_name, "remaining": [m.name for m in snap.models]})
+        except Exception as error:
+            self._send_json({"status": "failed", "error": str(error)})
+
+    def _handle_model_unload_all(self) -> None:
+        try:
+            client = build_client(resolve_model_profile(self.server_inst.default_profile))
+            manager = ModelMemoryManager(client)
+            snap = manager.unload_all()
+            stopped = []
+            for name in list(self.server_inst.spawned_processes):
+                if name == "llama_server":
+                    self._stop_backend(name)
+                    stopped.append(name)
+            self.server_inst.llama_effective_ctx = None
+            self.server_inst.llama_gguf_path = None
+            self.server_inst.llama_gguf_label = None
+            self._send_json({
+                "status": "unloaded_all",
+                "remaining_bytes": snap.total_vram_bytes,
+                "stopped": stopped,
+            })
+        except Exception as error:
+            self._send_json({"status": "failed", "error": str(error)})
+
+    @staticmethod
+    def _parse_ctx_override(requested_ctx: Any) -> tuple[int | None, str | None]:
+        if requested_ctx is None:
+            return None, None
+        if isinstance(requested_ctx, bool):
+            return None, "Context override must be an integer of at least 512 tokens"
+        try:
+            ctx = int(requested_ctx)
+        except (TypeError, ValueError):
+            return None, "Context override must be an integer of at least 512 tokens"
+        if isinstance(requested_ctx, float) and not requested_ctx.is_integer():
+            return None, "Context override must be an integer of at least 512 tokens"
+        if ctx < 512:
+            return None, "Context override must be at least 512 tokens"
+        if ctx > _MAX_CTX_OVERRIDE:
+            return None, (
+                f"Context override {ctx} is too large; the hard resource cap is "
+                f"{_MAX_CTX_OVERRIDE} tokens"
+            )
+        return ctx, None
+
+    def _apply_ctx_override(self, profile: ModelProfile, requested_ctx: Any) -> tuple[ModelProfile, str | None]:
+        """Clamp and apply a per-request context-window override.
+
+        Returns (profile, relaunch_error). For openai-provider (llama-server)
+        profiles the context window is fixed at server launch (``-c``), so a
+        changed value triggers a relaunch of the remembered GGUF; when the
+        server was started externally the caller gets a prescriptive error.
+        """
+        ctx, error = self._parse_ctx_override(requested_ctx)
+        if error:
+            return profile, error
+        if ctx is None:
+            return profile, None
+        # Static profile values are policy recommendations, not proof of the
+        # installed model's runtime limit.  Clamp only to a verified limit.
+        max_len = getattr(profile, "model_context_limit", None)
+        if max_len and ctx > max_len:
+            ctx = int(max_len)
+        profile = replace(profile, num_ctx=ctx)
+        if profile.provider != "openai":
+            return profile, None  # Ollama receives options.num_ctx per request
+        if self.server_inst.llama_num_ctx == ctx:
+            return profile, None
+        gguf_path = self.server_inst.llama_gguf_path
+        if not gguf_path:
+            return profile, (
+                f"llama-server is running with -c {self.server_inst.llama_num_ctx}. "
+                f"To use a {ctx}-token context window, reload the model from the "
+                "model panel (Load into VRAM) with the Context Override set."
+            )
+        label = self.server_inst.llama_gguf_label or Path(gguf_path).stem
+        result = self._launch_llama_model(gguf_path, label, num_ctx=ctx)
+        if result.get("status") != "started":
+            error = (
+                f"llama-server relaunch with -c {ctx} failed: {result.get('error', 'unknown error')}"
+            )
+            if result.get("restored"):
+                error += f" {result['restored']}"
+            elif result.get("restore_error"):
+                error += f" Automatic restore of the previous configuration also failed: {result['restore_error']}"
+            return profile, error
+        return profile, None
+
+    def _handle_chat(self) -> None:
+        data = self._read_json_body()
+        prompt = str(data.get("prompt", "")).strip()
+        profile_name = data.get("profile", self.server_inst.default_profile)
+        if profile_name == self.server_inst.default_profile:
+            profile_name = select_available_profile(profile_name)
+        files = data.get("files") or []
+        checks = data.get("checks") or []
+        requested_ctx = data.get("num_ctx")
+
+        if not prompt:
+            self._send_json({"status": "failed", "error": "Prompt cannot be empty"})
+            return
+        _, ctx_error = self._parse_ctx_override(requested_ctx)
+        if ctx_error:
+            self._send_json({"status": "failed", "error": ctx_error}, HTTPStatus.BAD_REQUEST)
+            return
+
+        from ...mode_router import MODES, classify_fast, classify_mode
+
+        # Resolve the user-selected interaction mode. Invalid / missing falls
+        # back to "hybrid" (auto-classify to chat/build/plan).
+        raw_mode = data.get("mode")
+        mode = raw_mode if raw_mode in MODES else "hybrid"
+        if mode == "hybrid":
+            # Keep a bounded recent-prompt history for the router's isolated context.
+            with self.server_inst.apply_lock:
+                _recent_prompts.append(prompt)
+                del _recent_prompts[:-_MAX_RECENT_PROMPTS]
+                recent_snapshot = list(_recent_prompts)
+            router = None
+            try:
+                from ...mode_router import build_mode_router
+
+                # Small default profile in the isolated context, never the main profile.
+                router = build_mode_router()
+            except Exception:
+                router = None  # ponytail: deterministic fallback, never break chat
+            mode = classify_mode(
+                prompt,
+                current_mode=None,
+                router=router,
+                n_every=3,
+                counter=self.server_inst.hybrid_counter,
+                recent_prompts=recent_snapshot,
+            )
+            with self.server_inst.apply_lock:
+                self.server_inst.hybrid_counter += 1
+
+        workspace = self.server_inst.workspace
+        # Scope discovery is for mutation/build work.  Chat and small-talk do
+        # not need a repository scan, and an informational request without an
+        # explicit file must ask for context rather than guess one.
+        if not files and mode == "plan":
+            files = detect_plan_candidates(workspace)
+        elif not files and (mode != "chat" or re.search(r"[\w./\\-]+\.\w{1,5}", prompt)):
+            files = detect_relevant_files(workspace, prompt)
+        if not checks and mode == "build":
+            checks = detect_test_checks(workspace)
+        if mode == "build" and not files:
+            self._send_json({
+                "status": "needs_context",
+                "mode": "build",
+                "message": "Name an existing file or provide an explicit scope before requesting a build change.",
+                "files": [],
+            })
+            return
+
+        # ponytail: uuid suffix — int(time.time()) collided when two chats
+        # landed in the same second and silently overwrote History.
+        task_id = f"task-{uuid.uuid4().hex[:12]}"
+
+        # Read-only planning for plan mode — never produces a patch, always
+        # returns a PlanArtifact. Failures degrade to an empty plan, never raise.
+        if mode == "plan":
+            try:
+                from ...plan_mode import PlanArtifact
+                from ...controller import Controller
+                profile = resolve_model_profile(profile_name)
+                profile, ctx_error = self._apply_ctx_override(profile, requested_ctx)
+                if ctx_error:
+                    self._send_json({"status": "failed", "error": ctx_error})
+                    return
+                client = build_client(profile)
+                task = TaskEnvelope(
+                    id=task_id,
+                    goal=prompt,
+                    files=tuple(files),
+                    checks=tuple(checks),
+                )
+                # Read-only enforcement at the tool-policy layer: block the two
+                # tools that mutate the workspace so plan mode cannot patch.
+                controller = Controller(
+                    client, workspace,
+                    blocked_tools={"propose_patch", "run_tests"},
+                )
+                result = controller.run(task, apply=False)
+
+                summary = result.get("summary") or ""
+                steps = [summary] if summary else []
+                risks = result.get("risks") or []
+                files_to_modify = list(files)
+                plan = PlanArtifact(
+                    goal=prompt,
+                    steps=[str(s) for s in steps],
+                    risks=[str(r) if isinstance(r, str) else str(r.get("message", "")) for r in risks],
+                    files_to_modify=[str(f) for f in files_to_modify],
+                )
+                plan_dict = plan.to_dict()
+                message = summary or f"Plan generated for '{prompt}'."
+            except Exception as error:
+                plan_dict = {
+                    "goal": prompt,
+                    "steps": [],
+                    "risks": [],
+                    "files_to_modify": list(files),
+                }
+                message = f"Could not generate a detailed plan: {error}"
+            response = {
+                "status": "completed",
+                "mode": "plan",
+                "task_id": task_id,
+                "prompt": prompt,
+                "profile": profile_name,
+                "plan": plan_dict,
+                "file": "workspace",
+                "patch": "",
+                "thinking": "Plan mode: read-only exploration produced a plan.",
+                "testResult": "READY",
+                "checks": [],
+                "message": message,
+            }
+            self._save_chat_session(response, [], status="Planned")
+            self._send_json(response)
+            return
+
+        # Friendly conversational / small-talk handling. The Controller tool-loop
+        # demands structured JSON that small models can't reliably emit for
+        # non-coding prompts, so route small talk to a plain completion.
+        greetings = {"hi", "hello", "hey", "привет", "здравствуйте", "yo", "sup", "help", "test", "ok", "thanks", "спасибо"}
+        greeting_phrases = ("how are you", "what's up", "whats up", "wassup", "how are u")
+        lowered = prompt.lower().strip("!.,? ")
+        tokens = lowered.split()
+        is_small_talk = (
+            lowered in greetings
+            or any(phrase in lowered for phrase in greeting_phrases)
+            or (len(tokens) <= 4 and any(tok.strip("!.,?") in greetings for tok in tokens))
+        )
+        if is_small_talk:
+            try:
+                profile = resolve_model_profile(profile_name)
+                profile, ctx_error = self._apply_ctx_override(profile, requested_ctx)
+                if ctx_error:
+                    self._send_json({"status": "failed", "error": ctx_error})
+                    return
+                client = build_client(profile)
+                resp = client.chat([
+                    {"role": "system", "content": "You are a concise local coding assistant."},
+                    {"role": "user", "content": prompt},
+                ])
+                reply = (resp.get("message") or {}).get("content")
+            except Exception as error:
+                self._send_offline_or_error(error, profile_name)
+                return
+            response = {
+                "status": "completed",
+                "mode": mode,
+                "task_id": task_id,
+                "prompt": prompt,
+                "profile": profile_name,
+                "file": "workspace",
+                "patch": "",
+                "thinking": "Conversational intent detected.",
+                "testResult": "READY",
+                "checks": [],
+                "message": reply or (
+                    f"Hello! Connected to `{profile_name}`. "
+                    "Please give me a specific coding task, bug fix, or refactoring goal "
+                    "(e.g. 'Fix off-by-one in sliding window' or 'Write unit tests for tax logic')."
+                ),
+            }
+            self._save_chat_session(response, [], status="Answered")
+            self._send_json(response)
+            return
+
+        # Informational / Code Inquiry Handling (e.g. "read main.py and tell me what it does",
+        # "explain foo", "can u tell me what main.py does?"). The shared classifier detects
+        # questions anywhere in the prompt, not just as prefixes; a question never needs a
+        # patch, so it bypasses the Controller AND the blind chat completion — the model
+        # must see the file it is asked about, whatever mode the user selected.
+        if classify_fast(prompt) == "chat" and files:
+            try:
+                profile = resolve_model_profile(profile_name)
+                profile, ctx_error = self._apply_ctx_override(profile, requested_ctx)
+                if ctx_error:
+                    self._send_json({"status": "failed", "error": ctx_error})
+                    return
+                if profile.num_predict < 2048:
+                    profile = replace(profile, num_predict=2048)
+                client = build_client(profile)
+                if not files:
+                    self._send_json({
+                        "status": "needs_context",
+                        "mode": "chat",
+                        "message": "Please name the file or provide its path so I can answer from repository evidence.",
+                        "file": None,
+                    })
+                    return
+                target_file = files[0]
+                # Strict Scope Boundary (server-enforced, mirrors apply): normalize
+                # and verify the resolved path stays inside the workspace before
+                # reading. An absolute path or `../` escapes the workspace -> skip.
+                # Up to 3 allowlisted files are injected: "what component does X"
+                # usually spans more than one file and a single-file context makes
+                # the model answer "I don't have access".
+                workspace_root = Path(workspace).resolve()
+                snippets: list[str] = []
+                for candidate_file in (files[:3] or ["src/main.py"]):
+                    try:
+                        resolved = (workspace_root / candidate_file).resolve()
+                        if resolved.is_relative_to(workspace_root) and resolved.is_file():
+                            body = resolved.read_text(encoding="utf-8", errors="replace")[:6000]
+                            snippets.append(f"--- {candidate_file} ---\n{body}")
+                    except Exception:
+                        continue
+                content_snippet = "\n\n".join(snippets)
+
+                messages = [
+                    {"role": "system", "content": f"You are a helpful coding assistant answering a question about this workspace. Relevant files: {', '.join(files[:3]) or target_file}\n\n{content_snippet}"},
+                    {"role": "user", "content": prompt},
+                ]
+                resp = client.chat(messages)
+                msg_content = (resp.get("message") or {}).get("content") or "No response received."
+
+                response = {
+                    "status": "completed",
+                    "mode": mode,
+                    "task_id": task_id,
+                    "prompt": prompt,
+                    "profile": profile_name,
+                    "file": target_file,
+                    "patch": "",
+                    "thinking": f"Read context from {target_file} and formulated code explanation.",
+                    "testResult": "READY",
+                    "checks": [],
+                    "message": msg_content,
+                }
+                self._save_chat_session(response, checks, status="Answered")
+                self._send_json(response)
+                return
+            except Exception as error:
+                self._send_offline_or_error(error, profile_name)
+                return
+
+        # Plain conversational completion for chat mode — never runs the
+        # Controller. Reached only for chat-mode prompts that are neither
+        # small talk nor questions (opinions, jokes, ...); questions above
+        # already got the file-aware answer.
+        if mode == "chat":
+            try:
+                profile = resolve_model_profile(profile_name)
+                profile, ctx_error = self._apply_ctx_override(profile, requested_ctx)
+                if ctx_error:
+                    self._send_json({"status": "failed", "error": ctx_error}, HTTPStatus.BAD_REQUEST)
+                    return
+                client = build_client(profile)
+                resp = client.chat([
+                    {"role": "system", "content": "You are a concise local coding assistant."},
+                    {"role": "user", "content": prompt},
+                ])
+                reply = (resp.get("message") or {}).get("content")
+            except Exception as error:
+                self._send_offline_or_error(error, profile_name)
+                return
+            response = {
+                "status": "completed",
+                "mode": "chat",
+                "task_id": task_id,
+                "prompt": prompt,
+                "profile": profile_name,
+                "file": "workspace",
+                "patch": "",
+                "thinking": "Conversational intent detected.",
+                "testResult": "READY",
+                "checks": [],
+                "message": reply or (
+                    f"Hello! Connected to `{profile_name}`. "
+                    "Please give me a specific coding task, bug fix, or refactoring goal "
+                    "(e.g. 'Fix off-by-one in sliding window' or 'Write unit tests for tax logic')."
+                ),
+            }
+            self._save_chat_session(response, [], status="Answered")
+            self._send_json(response)
+            return
+
+        task = TaskEnvelope(
+            id=task_id,
+            goal=prompt,
+            files=tuple(files),
+            checks=tuple(checks),
+        )
+
+        try:
+            from ...controller import Controller
+            profile = resolve_model_profile(profile_name)
+            profile, ctx_error = self._apply_ctx_override(profile, requested_ctx)
+            if ctx_error:
+                self._send_json({"status": "failed", "error": ctx_error})
+                return
+            client = build_client(profile)
+            controller = Controller(client, workspace)
+            result = controller.run(task, apply=False)
+
+            patch_content = result.get("patch", "")
+            target_file = files[0] if files else "src/main.py"
+            check_evidence = result.get("checks") if isinstance(result.get("checks"), list) else []
+            evidence_verified = bool(check_evidence) and all(
+                isinstance(item, dict) and item.get("passed") is True
+                for item in check_evidence
+            )
+
+            summary = result.get("summary") or ""
+            error = result.get("error")
+            err_kind = error.get("kind") if isinstance(error, dict) else None
+            if err_kind == "duplicate_tool_call":
+                friendly = "The model got stuck repeating the same step. Try a simpler single-step task, or a larger model."
+            elif err_kind == "context_overflow":
+                friendly = summary
+            elif err_kind == "retry_budget_exhausted":
+                friendly = "The model couldn't produce a valid result after several attempts. Simplify the request or switch to a larger model."
+            elif result.get("status") == "failed":
+                friendly = f"The task could not be completed: {summary}"
+            else:
+                friendly = summary
+
+            response = {
+                "status": result.get("status", "completed"),
+                "mode": mode,
+                "task_id": task_id,
+                "prompt": prompt,
+                "profile": profile_name,
+                "file": target_file,
+                "files": list(files),
+                "patch": patch_content,
+                "thinking": friendly or "AST context compacted, generated candidate patch, ran external tests.",
+                "testResult": "PASSED" if evidence_verified else ("NOT RUN" if result.get("status") == "accepted" else "FAILED"),
+                "checks": check_evidence,
+                "message": friendly or f"Task processed for '{prompt}'.",
+            }
+            self._save_chat_session(
+                response,
+                checks,
+                status="Verified" if evidence_verified else "Needs Review",
+                evidence_verified=evidence_verified,
+            )
+            self._send_json(response)
+        except Exception as error:
+            kind = _classify_backend_error(error)
+            if kind == "offline":
+                is_llama = profile.provider == "openai"
+                server_name = "llama-server on port 8080" if is_llama else "Ollama on port 11434"
+                prescript = f"Local backend server ({server_name}) is currently OFFLINE. Click 'Start {('llama-server' if is_llama else 'Ollama')}' or launch your local engine."
+                self._send_json({"status": "failed", "error": prescript, "offline_server": "llama_server" if is_llama else "ollama"})
+            else:
+                self._send_json({"status": "failed", "error": str(error)})
+
+    def _handle_delegate(self) -> None:
+        data = self._read_json_body()
+        raw_task = data.get("task", {})
+        profile_name = data.get("profile", self.server_inst.default_profile)
+        apply_flag = bool(data.get("apply", False))
+
+        try:
+            from ...controller import Controller
+            task = TaskEnvelope.from_mapping(raw_task)
+            profile = resolve_model_profile(profile_name)
+            client = build_client(profile)
+            controller = Controller(client, self.server_inst.workspace)
+            result = controller.run(task, apply=apply_flag)
+            self._send_json(result)
+        except Exception as error:
+            self._send_json({"status": "failed", "error": str(error)})
+
+    def _handle_tasks_submit(self) -> None:
+        data = self._read_json_body()
+        server = self.server_inst
+        goal = data.get("goal")
+        if not isinstance(goal, str) or not goal.strip():
+            self._send_json({"status": "failed", "error": "goal is required"})
+            return
+        files = data.get("files") or []
+        checks = data.get("checks") or []
+        if not isinstance(files, list) or not all(isinstance(f, str) and f for f in files):
+            self._send_json({"status": "failed", "error": "files must be a list of non-empty strings"})
+            return
+        if not isinstance(checks, list) or not all(isinstance(c, str) and c for c in checks):
+            self._send_json({"status": "failed", "error": "checks must be a list of non-empty strings"})
+            return
+        record = {
+            "id": f"task-{uuid.uuid4().hex[:12]}",
+            "goal": goal.strip(),
+            "files": [str(f) for f in files],
+            "checks": [str(c) for c in checks],
+            "profile": str(data.get("profile") or server.default_profile),
+            "status": "queued",
+            "created_at": time.time(),
+            "started_at": None,
+            "finished_at": None,
+            "summary": "",
+            "patch": "",
+            "checks_results": [],
+            "error": "",
+        }
+        with server.task_queue_lock:
+            server.save_task(record)
+        self._send_json({"status": "queued", "task": record})
+
+    def _handle_tasks_list(self) -> None:
+        self._send_json({"tasks": self.server_inst.load_tasks()})
+
+    def _handle_tasks_cancel(self) -> None:
+        data = self._read_json_body()
+        task_id = str(data.get("id") or "")
+        server = self.server_inst
+        with server.task_queue_lock:
+            record = server.get_task(task_id)
+            if record is None:
+                self._send_json({"status": "failed", "error": f"Unknown task id: {task_id}"})
+                return
+            status = record.get("status")
+            if status == "queued":
+                updated = server.update_task(task_id, status="cancelled", finished_at=time.time())
+                self._send_json({"status": "cancelled", "task": updated})
+                return
+            if status == "running":
+                event = server._task_events.get(task_id)
+                if event is not None:
+                    event.set()
+                self._send_json({"status": "cancelling", "task": record})
+                return
+            self._send_json({"status": "failed", "error": f"Task {task_id} is already {status}"})
+
+    def _handle_apply(self) -> None:
+        data = self._read_json_body()
+        patch_str = data.get("patch", "")
+        checks = data.get("checks", [])
+        files = data.get("files", [])
+        workspace = Path(self.server_inst.workspace)
+
+        if not isinstance(patch_str, str) or not patch_str.strip():
+            self._send_json({"status": "failed", "error": "No patch content provided to apply"})
+            return
+        if not isinstance(files, list) or not all(isinstance(f, str) for f in files):
+            self._send_json({"status": "rejected", "error": "files must be a list of strings"})
+            return
+        if not isinstance(checks, list) or not all(isinstance(c, str) for c in checks):
+            self._send_json({"status": "rejected", "error": "checks must be a list of strings"})
+            return
+
+        # Strict Scope Boundary (server-enforced, mirrors validate_candidate):
+        # the caller must declare the allowlist. The boundary lives on the
+        # server, not the client.
+        if not files:
+            self._send_json({
+                "status": "rejected",
+                "error": "No declared file scope; refusing to apply a patch with an empty allowlist",
+            })
+            return
+
+        try:
+            task = TaskEnvelope(
+                id="desktop-apply",
+                goal="apply reviewed patch",
+                files=tuple(files),
+                checks=tuple(checks),
+            )
+        except ValueError as error:
+            self._send_json({"status": "rejected", "error": f"Invalid apply request: {error}"})
+            return
+
+        # Mediated apply under the lock: the same verification gate as the CLI
+        # and service paths (declared scope, semantic lint, targeted checks,
+        # verified rollback). Holding the lock across apply->checks->rollback
+        # closes the race on last_applied_files.
+        with self.server_inst.apply_lock:
+            result = mediated_apply(workspace, patch_str, task)
+            payload: dict[str, Any] = {
+                "status": "applied" if result.get("applied") is True else "rejected",
+                "checks": result.get("checks", []),
+                "rolled_back": bool(result.get("rolled_back")),
+            }
+            if result.get("applied") is True:
+                changed, _ = parse_unified_diff(patch_str)
+                # Record only the files the patch actually changes (not the
+                # declared allowlist), so a later rollback never wipes unrelated
+                # work.
+                self.server_inst.last_applied_files = list(changed)
+                self.server_inst.last_applied_patch = patch_str
+            else:
+                error = result.get("error")
+                payload["error"] = error.get("message", "apply rejected") if isinstance(error, dict) else str(error)
+            self._send_json(payload)
+
+    def _handle_rollback(self) -> None:
+        workspace = Path(self.server_inst.workspace)
+        with self.server_inst.apply_lock:
+            targets = list(self.server_inst.last_applied_files)
+            patch = self.server_inst.last_applied_patch
+            if not targets or not patch:
+                self._send_json({"status": "rolled_back", "restored": []})
+                return
+            # Scoped rollback via reverse-apply of the stored patch: handles both
+            # modified (tracked) and newly-created (untracked) files uniformly,
+            # unlike `git restore` which cannot remove untracked files. Restores
+            # only the files this apply touched — never unrelated work.
+            reverted, detail = apply_patch(workspace, patch, reverse=True)
+            if not reverted:
+                self._send_json({
+                    "status": "failed",
+                    "error": f"Rollback failed: {detail}",
+                    "restored": [],
+                })
+                return
+            self.server_inst.last_applied_files = []
+            self.server_inst.last_applied_patch = ""
+            self._send_json({"status": "rolled_back", "restored": targets})
+
+    def _handle_doctor_fix(self) -> None:
+        try:
+            report = remediate_environment(write=True)
+            report_data = report.to_dict()
+            if report.success:
+                self._send_json({"status": "ok", "report": report_data})
+                return
+            errors = getattr(report, "errors", [])
+            actions = getattr(report, "actions", [])
+            if actions:
+                # Partial success: some targets applied, others were denied
+                # (e.g. permission-denied global .gemini/.codex/.claude). A
+                # bare 500 would hide the real progress from the user.
+                self._send_json({
+                    "status": "partial",
+                    "error": "; ".join(errors) or "Doctor remediation was incomplete",
+                    "report": report_data,
+                })
+                return
+            self._send_json(
+                {
+                    "status": "failed",
+                    "error": "; ".join(errors) or "Doctor remediation was incomplete",
+                    "report": report_data,
+                },
+                HTTPStatus.INTERNAL_SERVER_ERROR,
+            )
+        except Exception as error:
+            self._send_json(
+                {"status": "failed", "error": str(error)},
+                HTTPStatus.INTERNAL_SERVER_ERROR,
+            )
+
+    def _probe_port(self, url: str) -> bool:
+        online, _ = self._probe_server_status(url)
+        return online
+
+    def _probe_server_status(self, url: str) -> tuple[bool, str]:
+        try:
+            req = urllib.request.Request(url)
+            with urllib.request.urlopen(req, timeout=0.3) as resp:
+                if resp.status == 200:
+                    return True, "ready"
+                return True, "loading"
+        except urllib.error.HTTPError as e:
+            if e.code == 503:
+                return True, "loading"
+            return False, "offline"
+        except Exception:
+            return False, "offline"
+
+    def _send_json(self, data: Any, status: HTTPStatus = HTTPStatus.OK) -> None:
+        body = json.dumps(data, ensure_ascii=False).encode("utf-8")
+        self._send_response(status, "application/json; charset=utf-8", body)
+
+    def _send_request_body_error(self, error: _RequestBodyError) -> None:
+        """Return a framing error and prevent reuse of an unsynchronized socket."""
+        self.close_connection = True
+        self._send_json({"status": "rejected", "error": error.message}, error.status)
+
+    def _send_offline_or_error(self, error: Exception, profile_name: Any) -> None:
+        """Prescriptive failure for chat completions — never mask a dead
+        backend behind the canned 'Connected' greeting."""
+        try:
+            profile = resolve_model_profile(profile_name)
+        except Exception:
+            profile = None
+        if profile is not None and _classify_backend_error(error) == "offline":
+            is_llama = profile.provider == "openai"
+            server_name = "llama-server on port 8080" if is_llama else "Ollama on port 11434"
+            self._send_json({
+                "status": "failed",
+                "error": (
+                    f"Local backend server ({server_name}) is currently OFFLINE. "
+                    f"Click 'Start {('llama-server' if is_llama else 'Ollama')}' or launch your local engine."
+                ),
+                "offline_server": "llama_server" if is_llama else "ollama",
+            })
+        else:
+            self._send_json({"status": "failed", "error": str(error)})
+
+    def _send_response(self, status: HTTPStatus, content_type: str, body: bytes) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(body)))
+        if self.close_connection:
+            self.send_header("Connection", "close")
+        self.send_header("Cache-Control", "no-cache, no-store, must-revalidate")
+        self.send_header("Content-Security-Policy", "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'")
+        self.send_header("X-Content-Type-Options", "nosniff")
+        self.send_header("X-Frame-Options", "DENY")
+        self.send_header("Referrer-Policy", "no-referrer")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, format: str, *args: Any) -> None:
+        del format, args
+
+
+def detect_relevant_files(workspace: str, prompt: str) -> list[str]:
+    """Heuristic allowlist for a task with no explicit files.
+
+    Module-level (not a handler method) so the background task worker can
+    resolve a file scope without an HTTP request context.
+    """
+    ws_path = Path(workspace)
+
+    # 1. Files explicitly named in the prompt win over every heuristic:
+    # "what does main.py do?" must not answer about an unrelated dirty file.
+    lowered = prompt.lower()
+    # ponytail: dot-token candidates let "__main__.py" match a "main.py"
+    # mention via suffix; drop the stem tier if false positives appear.
+    candidates = {
+        tok.strip("./\\'\"(),:?!")
+        for tok in re.findall(r"[\w./\\-]+\.\w{1,5}", lowered)
+    } - {""}
+    # A bare basename is an explicit scope only when it identifies one real
+    # file.  Duplicate basenames require the caller to provide a path.
+    basename_counts: dict[str, int] = {}
+    # Keyword scoring turns "desktop ui components" into desktop/ui.py +
+    # desktop/components.py when no filename is mentioned outright.
+    # ponytail: substring scoring, no stopwords — noise only widens the
+    # allowlist; tighten if wrong-file answers ever come back.
+    keywords = re.findall(r"[a-z_]{2,}", lowered)
+    mentioned: list[str] = []
+    scored: list[tuple[int, str]] = []
+    file_records: list[tuple[str, str, str]] = []
+    try:
+        # One os.walk both discovers files and counts basenames, so an
+        # explicit ``main.py`` can be rejected when duplicate paths exist
+        # without traversing the workspace twice.
+        for root, dirs, files_os in os.walk(ws_path):
+            dirs[:] = [
+                d for d in dirs
+                if not d.startswith(".") and d not in ("__pycache__", "venv", ".venv", "build", "dist", "node_modules")
+            ]
+            for fname in files_os:
+                p = Path(root) / fname
+                if p.suffix.lower() not in {
+                    ".py", ".js", ".ts", ".tsx", ".jsx", ".md", ".json", ".toml",
+                    ".yaml", ".yml", ".rs", ".go", ".c", ".h", ".cpp", ".java",
+                    ".rb", ".php", ".sh", ".ps1", ".sql", ".css", ".html",
+                }:
+                    continue
+                rel = p.relative_to(ws_path).as_posix()
+                name = fname.lower()
+                file_records.append((rel, name, root))
+                basename_counts[name] = basename_counts.get(name, 0) + 1
+
+        for rel, name, root in file_records:
+                if (
+                    len(mentioned) < 3
+                    and (
+                        any(
+                            (
+                                ("/" in cand or "\\" in cand)
+                                and rel.lower() == cand.replace("\\", "/")
+                            )
+                            or (
+                                "/" not in cand
+                                and "\\" not in cand
+                                and name == cand
+                                and basename_counts.get(cand, 0) == 1
+                            )
+                            for cand in candidates
+                        )
+                    )
+                ):
+                    mentioned.append(rel)
+                    continue
+                if keywords:
+                    stem = name.rsplit(".", 1)[0]
+                    parent = Path(root).name.lower()
+                    score = 0
+                    for kw in keywords:
+                        if len(kw) >= 4:
+                            if kw in stem:
+                                score += 2
+                            elif kw in rel.lower():
+                                score += 1
+                        elif kw == stem or kw == parent:
+                            score += 2
+                    if score:
+                        scored.append((score, rel))
+    except Exception:
+        pass
+    if mentioned:
+        return mentioned
+    if any(
+        "/" not in candidate and "\\" not in candidate and basename_counts.get(candidate, 0) > 1
+        for candidate in candidates
+    ):
+        return []
+    if scored:
+        scored.sort(key=lambda t: (-t[0], t[1]))
+        return [rel for _, rel in scored[:3]]
+
+    # No explicit or high-confidence scope: callers must request context
+    # instead of turning dirty files or a guessed ``src/main.py`` into a
+    # permission to patch an arbitrary file.
+    return []
+
+
+def detect_plan_candidates(workspace: str) -> list[str]:
+    """Return existing dirty files as read-only plan suggestions.
+
+    Plan mode may show the user what changed, but this candidate list is not
+    reused as a build/apply allowlist.  An unavailable Git view yields no
+    fabricated path.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain=v1", "-z", "--untracked-files=all"],
+            cwd=workspace,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            return []
+        candidates: list[str] = []
+        entries = result.stdout.split("\0")
+        index = 0
+        while index < len(entries):
+            entry = entries[index]
+            index += 1
+            if len(entry) < 4:
+                continue
+            status, path = entry[:2], entry[3:].replace("\\", "/")
+            if "R" in status or "C" in status:
+                index += 1
+            if not path or any(part.startswith(".") for part in Path(path).parts):
+                continue
+            if (Path(workspace) / path).is_file():
+                candidates.append(path)
+        return candidates[:3]
+    except (OSError, subprocess.SubprocessError):
+        return []
+
+
+def detect_test_checks(workspace: str) -> list[str]:
+    ws_path = Path(workspace)
+    package_path = ws_path / "package.json"
+    if package_path.is_file():
+        try:
+            package = json.loads(package_path.read_text(encoding="utf-8-sig"))
+            scripts = package.get("scripts") if isinstance(package, dict) else None
+            if isinstance(scripts, dict) and isinstance(scripts.get("test"), str) and scripts["test"].strip():
+                return ["npm test"]
+        except (OSError, UnicodeError, json.JSONDecodeError):
+            return []
+
+    if (ws_path / "Cargo.toml").is_file():
+        return ["cargo test"]
+    if (ws_path / "go.mod").is_file():
+        return ["go test ./..."]
+
+    python_manifest = any(
+        (ws_path / name).is_file()
+        for name in ("pyproject.toml", "setup.cfg", "setup.py", "pytest.ini", "tox.ini")
+    )
+    if python_manifest:
+        if (ws_path / "tests").is_dir():
+            return ["pytest tests/"]
+        if (ws_path / "test").is_dir():
+            return ["pytest test/"]
+        return ["pytest"]
+    return []