@vibe-x/dsh-html-workbench 0.3.0 → 0.3.2

package/scripts/workbench.py

@@ -14,6 +14,7 @@ import logging
 import mimetypes
 import os
 import re
+import secrets
 import signal
 import subprocess
 import sys
@@ -21,6 +22,7 @@ import tarfile
 import tempfile
 import threading
 import time
+import traceback
 import urllib.error
 import urllib.parse
 import urllib.request
@@ -34,7 +36,7 @@ from typing import Any
 
 
 SERVICE_NAME = "html-workbench"
-SERVICE_VERSION = "2.1.0"
+SERVICE_VERSION = "2.2.0"
 
 DEFAULT_PORT = 4317
 # Capability names advertised by /api/health. `command_open` refuses to reuse a
@@ -113,8 +115,10 @@ def default_vendor_cache() -> Path:
     return base / "html-workbench" / "vendor" / "grapesjs" / GRAPESJS_VERSION
 
 
-LOG_MAX_BYTES = 1_000_000
+LOG_MAX_BYTES = 1024 * 1024
 LOG_BACKUP_COUNT = 5
+LOG_RECORD_MAX_BYTES = 16 * 1024
+BOOTSTRAP_MAX_BYTES = 256 * 1024
 
 
 def default_log_dir() -> Path:
@@ -126,6 +130,218 @@ def default_log_dir() -> Path:
     return base / "html-workbench" / "logs"
 
 
+# Name of the runtime-state folder this process keeps beside its working
+# directory. The DSH plugin resolves the same name host-side, so both halves
+# agree on one location instead of scattering `.html-workbench` and
+# `html-workbench-dsh` through the user's workspace.
+RUNTIME_DIR_NAME = ".html-workbench"
+
+
+def runtime_directory() -> Path:
+    """Return this process's runtime-state root: `<cwd>/<RUNTIME_DIR_NAME>`.
+
+    Under DSH the working directory is the session workspace, which is one of the
+    only two trees the subprocess sandbox grants write access to — the other is a
+    private temp directory it hands the child through TEMP/TMP. Everywhere else
+    the working directory is simply a sensible, self-cleaning location. Logs and
+    the GrapesJS cache are disposable, so either is acceptable; what is NOT
+    acceptable is a path the sandbox refuses (see `pick_writable_dir`).
+    """
+    return Path.cwd() / RUNTIME_DIR_NAME
+
+
+def make_temp_file(directory: Path, prefix: str, suffix: str = "") -> tuple[int, Path]:
+    """Create a uniquely named temporary file in `directory`; return (fd, path).
+
+    Deliberately NOT `tempfile.mkstemp`. On Windows CPython's `_mkstemp_inner`
+    treats a `PermissionError` as "that name is already taken": it re-checks the
+    directory with `os.access(dir, os.W_OK)` and then retries with a NEW random
+    name, up to TMP_MAX (10 000) times. A real DACL always looks writable to
+    `os.access`, which cannot see the restricted token DSH's sandbox runs the
+    child under — so a directory the sandbox refuses makes `mkstemp` spin for
+    minutes (one denied `os.open` per iteration, ~4 ms each) instead of failing
+    in milliseconds. A single O_EXCL open turns that into an immediate error the
+    caller can catch and recover from.
+    """
+    for attempt in range(64):
+        candidate = Path(directory) / f"{prefix}{os.getpid()}-{attempt}-{os.urandom(6).hex()}{suffix}"
+        try:
+            descriptor = os.open(
+                candidate,
+                os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_BINARY", 0),
+                0o600,
+            )
+        except FileExistsError:
+            continue
+        return descriptor, candidate
+    raise FileExistsError(f"无法在 {directory} 创建临时文件：连续的文件名冲突")
+
+
+def self_ignore(directory: Path) -> None:
+    """Make a runtime directory invisible to git, best effort.
+
+    The runtime root usually lands inside the session workspace, which for most
+    users is a repository: without this, every start dirties `git status` with a
+    folder holding nothing but logs and a re-downloadable cache, and the noise
+    lands in the user's own project rather than ours. A `.gitignore` containing
+    `*` excludes the tree including that file, so nothing has to be added to the
+    repository's own ignore rules.
+
+    Only the runtime root is marked — never an arbitrary directory the caller
+    happened to pass, which may be the user's source tree (`--log-dir .`).
+    """
+    root = next((parent for parent in (directory, *directory.parents) if parent.name == RUNTIME_DIR_NAME), None)
+    if root is None:
+        return
+    marker = root / ".gitignore"
+    if marker.exists():
+        return
+    try:
+        marker.write_text("# Created by html-workbench: disposable logs and cache.\n*\n", encoding="utf-8")
+    except OSError:
+        pass
+
+
+def pick_writable_dir(*candidates: Path, failures: list[str] | None = None) -> Path:
+    """Return the first candidate directory this process can really write into.
+
+    Existence proves nothing: the sandbox DACL looks writable on paper while the
+    restricted token is denied, and a folder the unconfined parent created may
+    reject every file creation here with EACCES / WinError 5. The only reliable
+    test is an actual create, which `make_temp_file` performs and fails fast.
+    Falls back to the first candidate so a caller with nothing writable at all
+    still gets a deterministic path (and a clear error at the real write).
+    """
+    fallback: Path | None = None
+    for candidate in dict.fromkeys(candidates):
+        if fallback is None:
+            fallback = candidate
+        try:
+            candidate.mkdir(parents=True, exist_ok=True)
+            descriptor, probe = make_temp_file(candidate, prefix=".wb-write-probe.")
+        except OSError as caught:
+            if failures is not None:
+                failures.append(f"{candidate}: {caught}")
+            continue
+        os.close(descriptor)
+        try:
+            probe.unlink()
+        except OSError:
+            pass
+        self_ignore(candidate)
+        return candidate
+    return fallback if fallback is not None else Path.cwd()
+
+
+def log_candidates(log_dir: Path | str) -> tuple[Path, ...]:
+    """Log directories to try, best first: the caller's, then writable fallbacks."""
+    return (
+        Path(log_dir).expanduser(),
+        runtime_directory() / "logs",
+        temporary_runtime_directory() / "logs",
+    )
+
+
+def vendor_candidates(vendor_cache: Path | str, log_dir: Path) -> tuple[Path, ...]:
+    """Vendor-cache directories to try, best first.
+
+    The cache sits beside whichever directory accepted the log: both are
+    re-creatable, and the log's parent already proved it is writable.
+    """
+    return (
+        Path(vendor_cache).expanduser(),
+        Path(log_dir).parent / "vendor",
+        runtime_directory() / "vendor",
+        temporary_runtime_directory() / "vendor",
+    )
+
+def temporary_runtime_directory() -> Path:
+    try:
+        return Path(tempfile.gettempdir()) / RUNTIME_DIR_NAME
+    except OSError:
+        # A denied TEMP must not prevent trying the explicitly supplied directory.
+        return runtime_directory()
+
+
+def bounded_utf8(text: str, limit: int) -> bytes:
+    data = text.encode("utf-8", errors="backslashreplace")
+    if len(data) <= limit:
+        return data
+    marker = b"\n...[truncated]...\n"
+    remaining = limit - len(marker)
+    head = data[:remaining // 3].decode("utf-8", errors="ignore").encode("utf-8")
+    tail = data[-(remaining - remaining // 3):].decode("utf-8", errors="ignore").encode("utf-8")
+    return head + marker + tail
+
+
+class BoundedRotatingFileHandler(RotatingFileHandler):
+    """Bound UTF-8 bytes, including exception stacks; back off on disk failures."""
+
+    last_error: str | None = None
+    dropped_records = 0
+    retry_at = 0.0
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if time.monotonic() < self.retry_at:
+            self.dropped_records += 1
+            return
+        try:
+            data = bounded_utf8(self.format(record), min(LOG_RECORD_MAX_BYTES, self.maxBytes) - 1) + b"\n"
+            if self.stream is None:
+                self.stream = self._open()
+            if os.fstat(self.stream.fileno()).st_size + len(data) > self.maxBytes:
+                self.doRollover()
+            # Binary writes avoid Windows newline translation and count CJK bytes.
+            self.stream.buffer.write(data)
+            self.stream.flush()
+            self.last_error = None
+        except Exception as caught:
+            self.last_error = str(caught)[:500]
+            self.dropped_records += 1
+            self.retry_at = time.monotonic() + 60
+            try:
+                print(json.dumps({"event": "log_write_failed", "message": self.last_error}), file=sys.stderr, flush=True)
+            except OSError:
+                pass
+
+
+class BoundedOutput(io.TextIOBase):
+    """Cap the detached child's combined stdout/stderr, including library output."""
+
+    def __init__(self, output: Any) -> None:
+        self.output = output
+        self.lock = threading.Lock()
+        self.full = False
+
+    @property
+    def encoding(self) -> str:
+        return "utf-8"
+
+    def write(self, text: str) -> int:
+        with self.lock:
+            if self.full:
+                return len(text)
+            try:
+                remaining = BOOTSTRAP_MAX_BYTES - os.fstat(self.output.fileno()).st_size
+                data = text.encode("utf-8", errors="backslashreplace")
+                marker = b"\n[bootstrap output limit reached]\n"
+                if len(data) + len(marker) > remaining:
+                    self.full = True
+                    data = data[:max(0, remaining - len(marker))].decode("utf-8", errors="ignore").encode("utf-8")
+                    data += marker[:max(0, remaining - len(data))]
+                self.output.write(data)
+                self.output.flush()
+            except OSError:
+                self.full = True
+        return len(text)
+
+    def flush(self) -> None:
+        try:
+            self.output.flush()
+        except (OSError, ValueError):
+            pass
+
+
 _logger: logging.Logger | None = None
 
 
@@ -144,27 +360,48 @@ def get_logger() -> logging.Logger:
     return _logger
 
 
-def setup_logging(log_dir: Path | str, port: int | None = None) -> logging.Logger:
-    """Attach the rotating file handler and return the module logger."""
-    global _logger
-    directory = Path(log_dir).expanduser()
-    directory.mkdir(parents=True, exist_ok=True)
+def setup_logging(log_dir: Path | str, port: int | None = None) -> tuple[logging.Logger, Path]:
+    """Attach the rotating file handler; return the logger and the directory used.
+
+    The requested `--log-dir` can be unusable even when it already exists — the
+    sandbox denies writes to a folder whose DACL looks writable (see
+    `pick_writable_dir`). The directory is therefore probed and handed back to
+    the caller, so the host can report where the log really is instead of echoing
+    the path it merely asked for. A missing service log is never worth failing
+    the whole start: when EVERY candidate refuses writes, `pick_writable_dir`
+    returns a deterministic path that the handler cannot open, so the failure is
+    swallowed and the service runs without a file log rather than never binding
+    its port.
+    """
+    failures: list[str] = []
+    directory = pick_writable_dir(*log_candidates(log_dir), failures=failures)
     filename = f"workbench-{port}.log" if port is not None else "workbench.log"
-    handler = RotatingFileHandler(
-        directory / filename,
-        maxBytes=LOG_MAX_BYTES,
-        backupCount=LOG_BACKUP_COUNT,
-        encoding="utf-8",
-    )
-    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
     logger = get_logger()
     for existing in list(logger.handlers):
         if isinstance(existing, RotatingFileHandler):
             existing.close()
             logger.removeHandler(existing)
-    logger.addHandler(handler)
     logger.setLevel(logging.INFO)
-    return logger
+    try:
+        handler = BoundedRotatingFileHandler(
+            directory / filename,
+            maxBytes=LOG_MAX_BYTES,
+            backupCount=LOG_BACKUP_COUNT,
+            encoding="utf-8",
+        )
+    except OSError as caught:
+        print(json.dumps({
+            "level": "warning", "event": "log_file_unavailable",
+            "message": str(caught), "attempts": failures,
+        }, ensure_ascii=False), file=sys.stderr, flush=True)
+        return logger, directory
+    formatter = logging.Formatter("%(asctime)s.%(msecs)03dZ %(levelname)s pid=%(process)d %(message)s", "%Y-%m-%dT%H:%M:%S")
+    formatter.converter = time.gmtime
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    for failure in failures:
+        logger.warning("log_directory_rejected %s", failure)
+    return logger, directory
 
 
 def sha256_bytes(content: bytes) -> str:
@@ -218,7 +455,7 @@ def vendor_from_cdn(base_url: str) -> dict[str, bytes]:
 def write_vendor_cache(cache_dir: Path, files: dict[str, bytes]) -> None:
     cache_dir.mkdir(parents=True, exist_ok=True)
     for name, content in files.items():
-        descriptor, temporary_name = tempfile.mkstemp(prefix=f".{name}.", dir=cache_dir)
+        descriptor, temporary_name = make_temp_file(cache_dir, prefix=f".{name}.")
         try:
             with os.fdopen(descriptor, "wb") as output:
                 output.write(content)
@@ -231,13 +468,15 @@ def write_vendor_cache(cache_dir: Path, files: dict[str, bytes]) -> None:
 
 
 def ensure_vendor_assets(cache_dir: Path) -> dict[str, Path]:
+    logger = get_logger()
     paths = {name: cache_dir / name for name in VENDOR_ASSETS}
     try:
         for name, path in paths.items():
             verify_vendor_content(name, path.read_bytes())
+        logger.info("vendor_cache_ready grapesjs=%s", GRAPESJS_VERSION)
         return paths
-    except (OSError, ValueError):
-        pass
+    except (OSError, ValueError) as caught:
+        logger.info("vendor_cache_miss grapesjs=%s reason=%s", GRAPESJS_VERSION, caught)
 
     failures: list[str] = []
     sources = [
@@ -245,12 +484,23 @@ def ensure_vendor_assets(cache_dir: Path) -> dict[str, Path]:
         *((name, url, vendor_from_cdn) for name, url in VENDOR_CDNS),
     ]
     for source_name, url, loader in sources:
+        started = time.monotonic()
         try:
+            logger.info("vendor_download_start source=%s", source_name)
             files = loader(url)
-            write_vendor_cache(cache_dir, files)
-            return paths
         except (OSError, ValueError, tarfile.TarError, urllib.error.URLError) as caught:
             failures.append(f"{source_name}: {caught}")
+            logger.warning("vendor_download_failed source=%s elapsed_ms=%.0f reason=%s",
+                           source_name, (time.monotonic() - started) * 1000, caught)
+            continue
+        try:
+            write_vendor_cache(cache_dir, files)
+        except (OSError, ValueError) as caught:
+            failures.append(f"{source_name} cache write: {caught}")
+            logger.warning("vendor_cache_write_failed source=%s reason=%s", source_name, caught)
+            continue
+        logger.info("vendor_download_ready source=%s elapsed_ms=%.0f", source_name, (time.monotonic() - started) * 1000)
+        return paths
     raise WorkbenchError(
         "VENDOR_DOWNLOAD_FAILED",
         "首次启动需要下载约 1.2 MB 的 GrapesJS，但所有下载源均不可用。请检查网络后重试。",
@@ -982,9 +1232,9 @@ def promote_identities(target: Path, descriptors: list[dict[str, Any]], base_rev
 
 
 def write_atomic(target: Path, content: str) -> None:
-    temporary_name: str | None = None
+    temporary_name: Path | None = None
     try:
-        descriptor, temporary_name = tempfile.mkstemp(prefix=f".{target.name}.workbench-", suffix=".tmp", dir=target.parent)
+        descriptor, temporary_name = make_temp_file(target.parent, prefix=f".{target.name}.workbench-", suffix=".tmp")
         with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as output:
             output.write(content)
             output.flush()
@@ -1231,7 +1481,7 @@ def save_document(target: Path, body: dict[str, Any]) -> dict[str, Any]:
     if latest["revision"] != base_revision:
         raise WorkbenchError("REVISION_CONFLICT", "保存期间文件发生外部修改，未覆盖最新版。", 409, document=latest)
 
-    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{target.name}.workbench-", suffix=".tmp", dir=target.parent)
+    descriptor, temporary_name = make_temp_file(target.parent, prefix=f".{target.name}.workbench-", suffix=".tmp")
     try:
         with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as output:
             output.write(source)
@@ -1249,11 +1499,26 @@ class WorkbenchServer(ThreadingHTTPServer):
     daemon_threads = True
     allow_reuse_address = True
 
-    def __init__(self, address: tuple[str, int], asset_file: Path, editor_root: Path, vendor_files: dict[str, Path]) -> None:
+    def __init__(
+        self,
+        address: tuple[str, int],
+        asset_file: Path,
+        editor_root: Path,
+        vendor_files: dict[str, Path],
+        log_dir: Path | None = None,
+        vendor_cache: Path | None = None,
+        log_file: Path | None = None,
+    ) -> None:
         self.asset_file = asset_file.resolve(strict=True)
         self.editor_root = editor_root.resolve(strict=True)
         self.vendor_files = {name: path.resolve(strict=True) for name, path in vendor_files.items()}
         self.vendor_routes = {str(metadata["route"]): name for name, metadata in VENDOR_ASSETS.items()}
+        # Advertised by /api/health so the host can report the directories actually
+        # in use — including when it REUSES a service it did not start and has no
+        # startup output to read them from.
+        self.log_dir = Path(log_dir) if log_dir is not None else None
+        self.vendor_cache = Path(vendor_cache) if vendor_cache is not None else None
+        self.log_file = log_file
         super().__init__(address, WorkbenchHandler)
 
 
@@ -1261,10 +1526,42 @@ class WorkbenchHandler(BaseHTTPRequestHandler):
     server: WorkbenchServer
     protocol_version = "HTTP/1.1"
 
-    def log_message(self, format_string: str, *args: Any) -> None:
-        message = format_string % args
-        get_logger().info("%s %s", self.log_date_time_string(), message)
-        sys.stderr.write(f"{self.log_date_time_string()} {message}\n")
+    def handle_one_request(self) -> None:
+        self.request_id = secrets.token_hex(6)
+        self.request_started = time.monotonic()
+        self.error_code = None
+        self.file_ref = "-"
+        super().handle_one_request()
+
+    def parse_request(self) -> bool:
+        # The connection may sit idle before its next request line arrives.
+        self.request_started = time.monotonic()
+        return super().parse_request()
+
+    def log_request(self, code: int | str = "-", size: int | str = "-") -> None:
+        route = getattr(self, "path", "").partition("?")[0]
+        if route == "/api/health" and code == 200:
+            return
+        if route.startswith("/assets/"):
+            route = "/assets/*"
+        elif route not in {"/", "/api/health", "/api/document", "/api/events", "/api/context", "/api/anchor", "/api/shutdown"}:
+            route = route if route in self.server.vendor_routes else "other"
+        status = int(code) if str(code).isdigit() else 0
+        level = logging.ERROR if status >= 500 else logging.WARNING if status >= 400 else logging.INFO
+        method = self.command if self.command in {"GET", "PUT", "POST", "HEAD", "OPTIONS"} else "other"
+        get_logger().log(level, "http_request id=%s method=%s route=%s status=%s elapsed_ms=%.1f code=%s file_ref=%s",
+                         self.request_id, method, route, code,
+                         (time.monotonic() - self.request_started) * 1000, self.error_code or "-", self.file_ref)
+
+    def log_error(self, format_string: str, *args: Any) -> None:
+        # Base HTTP errors also pass through log_request. Skip the raw message,
+        # which can contain user-controlled request text.
+        if format_string.startswith("Request timed out"):
+            get_logger().warning("http_timeout id=%s", self.request_id)
+
+    def end_headers(self) -> None:
+        self.send_header("X-Workbench-Request-Id", self.request_id)
+        super().end_headers()
 
     def send_bytes(self, status: int, content: bytes, content_type: str, cache: str = "no-store") -> None:
         self.send_response(status)
@@ -1281,33 +1578,52 @@ class WorkbenchHandler(BaseHTTPRequestHandler):
         self.wfile.write(content)
 
     def send_json(self, status: int, payload: dict[str, Any]) -> None:
+        if status >= 400:
+            self.error_code = payload.get("error")
         content = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
         self.send_bytes(status, content, "application/json; charset=utf-8")
 
     def send_error_payload(self, caught: Exception) -> None:
         if isinstance(caught, WorkbenchError):
-            get_logger().warning("request failed: %s (%s)", caught.code, caught)
+            get_logger().warning("request_failed id=%s code=%s reason=%s", self.request_id, caught.code, caught)
             self.send_json(caught.status, {"error": caught.code, "message": str(caught), **caught.extra})
         else:
-            get_logger().exception("unhandled request error")
+            get_logger().exception("request_failed id=%s code=SERVER_ERROR", self.request_id)
             self.send_json(500, {"error": "SERVER_ERROR", "message": str(caught)})
 
     def query_file(self, query: dict[str, list[str]]) -> Path:
-        return resolve_html_file(query.get("file", [""])[0])
+        raw = query.get("file", [""])[0]
+        self.file_ref = hashlib.sha256(raw.encode("utf-8")).hexdigest()[:12]
+        return resolve_html_file(raw)
 
     def do_GET(self) -> None:
-        parsed = urllib.parse.urlsplit(self.path)
-        query = urllib.parse.parse_qs(parsed.query)
         try:
+            parsed = urllib.parse.urlsplit(self.path)
+            query = urllib.parse.parse_qs(parsed.query)
             if parsed.path == "/api/health":
-                self.send_json(200, {
+                payload: dict[str, Any] = {
                     "ok": True,
                     "service": SERVICE_NAME,
                     "version": SERVICE_VERSION,
+                    "pythonVersion": ".".join(map(str, sys.version_info[:3])),
+                    "pythonExecutable": sys.executable,
+                    "platform": sys.platform,
+                    "pid": os.getpid(),
+                    "logging": logging_status(),
                     "port": self.server.server_port,
                     "editorRoot": str(self.server.editor_root),
                     "capabilities": list(SERVICE_CAPABILITIES),
-                })
+                }
+                # Report where this process really writes. The host shows these in
+                # its diagnostics, so a REUSED service describes its own
+                # directories instead of the ones the caller asked for — which may
+                # be exactly what the sandbox refused.
+                if self.server.log_dir is not None:
+                    payload["logDir"] = str(self.server.log_dir)
+                    payload["logFile"] = str(self.server.log_file) if self.server.log_file is not None else None
+                if self.server.vendor_cache is not None:
+                    payload["vendorCache"] = str(self.server.vendor_cache)
+                self.send_json(200, payload)
                 return
             if parsed.path == "/api/document":
                 self.send_json(200, read_document(self.query_file(query)))
@@ -1330,23 +1646,25 @@ class WorkbenchHandler(BaseHTTPRequestHandler):
             self.send_error_payload(caught)
 
     def do_PUT(self) -> None:
-        parsed = urllib.parse.urlsplit(self.path)
-        if parsed.path != "/api/document":
-            self.send_json(404, {"error": "NOT_FOUND", "message": "接口不存在。"})
-            return
         try:
+            parsed = urllib.parse.urlsplit(self.path)
+            if parsed.path != "/api/document":
+                self.send_json(404, {"error": "NOT_FOUND", "message": "接口不存在。"})
+                return
             body = self.read_json_body()
             query = urllib.parse.parse_qs(parsed.query)
             self.send_json(200, save_document(self.query_file(query), body))
+        except (BrokenPipeError, ConnectionResetError):
+            return
         except json.JSONDecodeError as caught:
             self.send_error_payload(WorkbenchError("INVALID_SAVE", f"保存请求不是有效 JSON：{caught}", 400))
         except Exception as caught:
             self.send_error_payload(caught)
 
     def do_POST(self) -> None:
-        parsed = urllib.parse.urlsplit(self.path)
-        query = urllib.parse.parse_qs(parsed.query)
         try:
+            parsed = urllib.parse.urlsplit(self.path)
+            query = urllib.parse.parse_qs(parsed.query)
             if parsed.path == "/api/shutdown":
                 # Lets a newer `open` retire this process cleanly. The service
                 # holds no state of its own, so exiting is always safe.
@@ -1369,6 +1687,8 @@ class WorkbenchHandler(BaseHTTPRequestHandler):
                 self.send_json(200, promote_identities(target, selections, str(body.get("baseRevision") or "")))
                 return
             self.send_json(200, build_selection_context(target, selections))
+        except (BrokenPipeError, ConnectionResetError):
+            return
         except json.JSONDecodeError as caught:
             self.send_error_payload(WorkbenchError("INVALID_ANCHOR", f"请求不是有效 JSON：{caught}", 400))
         except Exception as caught:
@@ -1401,15 +1721,20 @@ class WorkbenchHandler(BaseHTTPRequestHandler):
         self.send_header("Connection", "keep-alive")
         self.end_headers()
         last_revision = ""
+        missing = False
         while True:
             try:
                 document = read_document(target)
+                missing = False
                 if document["revision"] != last_revision:
                     last_revision = document["revision"]
                     payload = json.dumps({"revision": last_revision, "mtimeMs": document["mtimeMs"]}, separators=(",", ":"))
                     self.wfile.write(f"data: {payload}\n\n".encode("utf-8"))
                     self.wfile.flush()
             except FileNotFoundError:
+                if not missing:
+                    get_logger().warning("file_watch_missing id=%s code=FILE_NOT_FOUND", self.request_id)
+                    missing = True
                 self.wfile.write(b'event: error\ndata: {"error":"FILE_NOT_FOUND"}\n\n')
                 self.wfile.flush()
             time.sleep(0.5)
@@ -1422,12 +1747,19 @@ def default_asset_file(script_file: Path) -> Path:
     raise WorkbenchError("ASSET_NOT_FOUND", f"找不到前端资源：{packaged}", 500)
 
 
-def health(port: int, timeout: float = 0.5) -> dict[str, Any] | None:
+def health(port: int, timeout: float = 0.5, failures: list[str] | None = None) -> dict[str, Any] | None:
     try:
         with urllib.request.urlopen(f"http://127.0.0.1:{port}/api/health", timeout=timeout) as response:
-            payload = json.loads(response.read().decode("utf-8"))
-        return payload if payload.get("service") == SERVICE_NAME else None
-    except (OSError, ValueError, urllib.error.URLError):
+            content = response.read(64 * 1024 + 1)
+        if len(content) > 64 * 1024:
+            raise ValueError("health response exceeds 64 KiB")
+        payload = json.loads(content.decode("utf-8"))
+        if not isinstance(payload, dict) or payload.get("service") != SERVICE_NAME:
+            raise ValueError("port responded with a different service identity")
+        return payload
+    except (OSError, ValueError, urllib.error.URLError) as caught:
+        if failures is not None:
+            failures.append(type(caught).__name__ + ": " + str(caught)[:1000])
         return None
 
 
@@ -1536,11 +1868,16 @@ def terminate_process(pid: int) -> None:
         pass
 
 
-def start_detached(script_file: Path, port: int, editor_root: Path, asset_file: Path | None, vendor_cache: Path, log_dir: Path) -> tuple[int, Path]:
-    directory = Path(log_dir).expanduser()
-    directory.mkdir(parents=True, exist_ok=True)
-    log_file = directory / f"html-workbench-{port}.log"
-    command = [sys.executable, str(script_file), "serve", "--port", str(port), "--editor-root", str(editor_root), "--vendor-cache", str(vendor_cache), "--log-dir", str(directory)]
+def start_detached(script_file: Path, port: int, editor_root: Path, asset_file: Path | None, vendor_cache: Path, log_dir: Path) -> tuple[int, Path | None]:
+    """Spawn a detached `serve` and return (pid, path of its captured output).
+
+    The path is None when no candidate directory accepted the file: a service
+    whose console output cannot be captured must still start, so the output is
+    discarded rather than the spawn abandoned (see `setup_logging`).
+    """
+    directory = pick_writable_dir(*log_candidates(log_dir))
+    log_file: Path | None = directory / f"html-workbench-{port}.log"
+    command = [sys.executable, str(script_file), "serve", "--bounded-output", "--port", str(port), "--editor-root", str(editor_root), "--vendor-cache", str(vendor_cache), "--log-dir", str(directory)]
     if asset_file is not None:
         command.extend(["--asset", str(asset_file)])
     flags = 0
@@ -1549,26 +1886,66 @@ def start_detached(script_file: Path, port: int, editor_root: Path, asset_file:
         flags = subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.DETACHED_PROCESS  # type: ignore[attr-defined]
         kwargs["creationflags"] = flags
         kwargs.pop("start_new_session", None)
-    with log_file.open("ab") as log:
-        process = subprocess.Popen(command, stdout=log, stderr=subprocess.STDOUT, close_fds=True, **kwargs)
+    try:
+        if log_file.is_file():
+            # Migrate historical unbounded output using a bounded tail read.
+            with log_file.open("rb") as previous:
+                previous.seek(max(0, os.fstat(previous.fileno()).st_size - BOOTSTRAP_MAX_BYTES))
+                # A tail offset can bisect a multibyte character in old logs.
+                tail = previous.read(BOOTSTRAP_MAX_BYTES).decode("utf-8", errors="replace")
+                log_file.with_suffix(".log.1").write_bytes(bounded_utf8(tail, BOOTSTRAP_MAX_BYTES))
+        log = log_file.open("wb")
+    except OSError:
+        log_file = None
+        log = None
+    try:
+        process = subprocess.Popen(
+            command,
+            stdout=log if log is not None else subprocess.DEVNULL,
+            stderr=subprocess.STDOUT,
+            close_fds=True,
+            **kwargs,
+        )
+    finally:
+        if log is not None:
+            log.close()
     return process.pid, log_file
 
 
 def command_serve(args: argparse.Namespace, script_file: Path) -> int:
-    logger = setup_logging(args.log_dir, args.port)
+    logger, log_directory = setup_logging(args.log_dir, args.port)
+    log_file = service_log_file(logger)
+    logger.info("service_starting version=%s python=%s platform=%s port=%s executable=%s cwd=%s",
+                SERVICE_VERSION, sys.version.split()[0], sys.platform, args.port, sys.executable, Path.cwd())
     asset_file = Path(args.asset).expanduser().resolve(strict=True) if args.asset else default_asset_file(script_file)
     editor_root = Path(args.editor_root).expanduser().resolve(strict=True)
-    vendor_files = ensure_vendor_assets(Path(args.vendor_cache).expanduser())
-    server = WorkbenchServer(("127.0.0.1", args.port), asset_file, editor_root, vendor_files)
-    logger.info("service started: port=%s editorRoot=%s logDir=%s", args.port, editor_root, Path(args.log_dir).expanduser())
-    print(json.dumps({"ok": True, "url": f"http://127.0.0.1:{args.port}", "editorRoot": str(editor_root)}, ensure_ascii=False), flush=True)
+    # Logs and cache are both disposable, so they follow the writable location the
+    # sandbox really granted instead of the path the parent requested.
+    failures: list[str] = []
+    vendor_cache = pick_writable_dir(*vendor_candidates(args.vendor_cache, log_directory), failures=failures)
+    for failure in failures:
+        logger.warning("vendor_directory_rejected %s", failure)
+    vendor_files = ensure_vendor_assets(vendor_cache)
+    server = WorkbenchServer(("127.0.0.1", args.port), asset_file, editor_root, vendor_files, log_directory, vendor_cache, log_file)
+    logger.info("service_ready port=%s editorRoot=%s logFile=%s vendorCache=%s", args.port, editor_root, log_file, vendor_cache)
+    # The host surfaces these two paths in its diagnostics, so the panel shows the
+    # directories actually in use rather than echoing the ones it asked for — the
+    # requested ones may be exactly what the sandbox refused.
+    print(json.dumps({
+        "ok": True,
+        "url": f"http://127.0.0.1:{args.port}",
+        "editorRoot": str(editor_root),
+        "logDir": str(log_directory),
+        "logFile": str(log_file) if log_file is not None else None,
+        "vendorCache": str(vendor_cache),
+    }, ensure_ascii=False), flush=True)
     try:
         server.serve_forever(poll_interval=0.25)
     except KeyboardInterrupt:
         pass
     finally:
         server.server_close()
-        logger.info("service stopped: port=%s", args.port)
+        logger.info("service_stopped port=%s", args.port)
     return 0
 
 
@@ -1600,7 +1977,8 @@ def command_open(args: argparse.Namespace, script_file: Path) -> int:
                 break
             time.sleep(0.1)
         else:
-            raise WorkbenchError("SERVER_UNAVAILABLE", f"服务启动失败，请查看日志：{log_file}", 500)
+            where = f"，请查看日志：{log_file}" if log_file is not None else "（没有可写的日志目录，输出已丢弃）"
+            raise WorkbenchError("SERVER_UNAVAILABLE", f"服务启动失败{where}", 500)
     query = urllib.parse.urlencode({"file": str(target)})
     print(json.dumps({
         "ok": True,
@@ -1621,6 +1999,7 @@ def build_parser() -> argparse.ArgumentParser:
     serve.add_argument("--asset", help="override the bundled workbench.html path")
     serve.add_argument("--vendor-cache", default=str(default_vendor_cache()), help="directory for verified GrapesJS files")
     serve.add_argument("--log-dir", default=str(default_log_dir()), help="directory for rotating service logs")
+    serve.add_argument("--bounded-output", action="store_true", help=argparse.SUPPRESS)
 
     open_command = subparsers.add_parser("open", help="start or reuse the service and print an editor URL")
     open_command.add_argument("file")
@@ -1655,11 +2034,48 @@ def command_stop(args: argparse.Namespace) -> int:
     raise WorkbenchError("SERVER_OUTDATED", f"端口 {args.port} 上的进程无法停止，请手动结束后重试。", 500)
 
 
+def service_log_file(logger: logging.Logger) -> Path | None:
+    for handler in logger.handlers:
+        if isinstance(handler, RotatingFileHandler):
+            return Path(handler.baseFilename)
+    return None
+
+
+def logging_status() -> dict[str, Any]:
+    for handler in get_logger().handlers:
+        if isinstance(handler, BoundedRotatingFileHandler):
+            return {
+                "file": handler.baseFilename, "error": handler.last_error,
+                "droppedRecords": handler.dropped_records,
+                "maxBytes": LOG_MAX_BYTES, "backups": LOG_BACKUP_COUNT,
+                "recordMaxBytes": LOG_RECORD_MAX_BYTES,
+            }
+    return {"file": None, "error": "file logging unavailable"}
+
+
+def report_cli_error(command: str, code: str, caught: Exception, **details: Any) -> int:
+    payload = {"ok": False, "error": code, "message": str(caught), **details}
+    if command == "serve":
+        logger = get_logger()
+        log_file = service_log_file(logger)
+        payload["logFile"] = str(log_file) if log_file is not None else None
+        logger.exception("service_failed code=%s", code)
+        if log_file is None or logging_status().get("error"):
+            print(bounded_utf8(traceback.format_exc(), LOG_RECORD_MAX_BYTES).decode("utf-8"), file=sys.stderr)
+    print(json.dumps(payload, ensure_ascii=False), file=sys.stderr, flush=True)
+    return 1
+
+
 def main() -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="backslashreplace")
     if sys.version_info < (3, 9):
         print(json.dumps({"ok": False, "error": "PYTHON_TOO_OLD", "message": "需要 Python 3.9 或更高版本。"}, ensure_ascii=False), file=sys.stderr)
         return 2
     args = build_parser().parse_args()
+    if getattr(args, "bounded_output", False):
+        sys.stdout = sys.stderr = BoundedOutput(sys.stdout.buffer)
     script_file = Path(__file__).resolve()
     try:
         if args.command == "serve":
@@ -1668,19 +2084,21 @@ def main() -> int:
             return command_open(args, script_file)
         if args.command == "stop":
             return command_stop(args)
-        payload = health(args.port)
-        print(json.dumps(payload or {"ok": False, "error": "SERVER_UNAVAILABLE"}, ensure_ascii=False))
+        failures: list[str] = []
+        payload = health(args.port, failures=failures)
+        print(json.dumps(payload or {"ok": False, "error": "SERVER_UNAVAILABLE", "detail": failures}, ensure_ascii=False))
         return 0 if payload else 1
     except WorkbenchError as caught:
-        print(json.dumps({"ok": False, "error": caught.code, "message": str(caught)}, ensure_ascii=False), file=sys.stderr)
-        return 1
+        return report_cli_error(args.command, caught.code, caught, **caught.extra)
     except FileNotFoundError as caught:
-        print(json.dumps({"ok": False, "error": "FILE_NOT_FOUND", "message": str(caught)}, ensure_ascii=False), file=sys.stderr)
-        return 1
+        return report_cli_error(args.command, "FILE_NOT_FOUND", caught)
     except OSError as caught:
         code = "PORT_IN_USE" if getattr(caught, "errno", None) in {48, 98, 10048} else "SERVER_UNAVAILABLE"
-        print(json.dumps({"ok": False, "error": code, "message": str(caught)}, ensure_ascii=False), file=sys.stderr)
-        return 1
+        return report_cli_error(args.command, code, caught)
+    except Exception as caught:
+        if args.command != "serve":
+            raise
+        return report_cli_error(args.command, "SERVER_ERROR", caught)
 
 
 if __name__ == "__main__":