@grifhinz/logics-manager 2.8.0 → 2.9.0

package/logics_manager/viewer.py

@@ -2,7 +2,9 @@ from __future__ import annotations
 
 import argparse
 import hashlib
+import hmac
 import json
+import secrets
 import mimetypes
 import os
 import re
@@ -10,6 +12,7 @@ import shutil
 import socket
 import subprocess
 import sys
+import tomllib
 import webbrowser
 from dataclasses import dataclass
 from datetime import datetime
@@ -49,6 +52,8 @@ CDX_MISSION_STRENGTHS = {
     "deep": {"id": "deep", "label": "Deep", "timeout": 300, "reasoningEffort": "high", "power": "high"},
     "max": {"id": "max", "label": "Max", "timeout": 600, "reasoningEffort": "high", "power": "high"},
 }
+CDX_MISSION_PARENT_TIMEOUT_GRACE_SECONDS = 90
+CDX_WRITABLE_MISSION_MIN_TIMEOUT_SECONDS = 600
 CDX_MISSION_CATALOG = {
     "full-audit": {
         "id": "full-audit",
@@ -142,6 +147,26 @@ GIT_FILE_PREVIEW_MAX_BYTES = 30000
 GIT_FILE_PREVIEW_MAX_CHARS = 20000
 FILE_PREVIEW_MAX_BYTES = 300000
 FILE_PREVIEW_MAX_CHARS = 200000
+WORKSPACE_TREE_MAX_ENTRIES = 250
+WORKSPACE_PREVIEW_MAX_BYTES = 30000
+WORKSPACE_PREVIEW_MAX_CHARS = 20000
+WORKSPACE_IGNORED_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".venv",
+    "venv",
+}
 REPO_ROOT = Path(__file__).resolve().parents[1]
 PACKAGE_VIEWER_ASSETS_ROOT = Path(__file__).resolve().parent / "viewer_assets"
 VIEWER_ROOT = REPO_ROOT / "clients" / "viewer"
@@ -442,6 +467,7 @@ def viewer_data_payload(
     selected_id: str | None = None,
     *,
     auto_refresh_interval_seconds: int = 15,
+    auto_refresh_interval_forced: bool = False,
     projects: list[dict[str, Any]] | None = None,
 ) -> dict[str, Any]:
     capabilities = viewer_project_capabilities(repo_root)
@@ -457,6 +483,7 @@ def viewer_data_payload(
         "capabilities": capabilities,
         "projects": projects if projects is not None else viewer_project_registry(repo_root),
         "autoRefreshIntervalSeconds": auto_refresh_interval_seconds,
+        "autoRefreshIntervalForced": auto_refresh_interval_forced,
         "items": collect_viewer_items(repo_root),
         "updateInfo": get_update_info(_current_version()).to_payload(),
         "selectedId": selected_id,
@@ -611,9 +638,31 @@ def viewer_project_capabilities(
     else:
         cdx = _viewer_capability("missing", available=False, message="CDX executable is not available.")
         cdx_runs = _viewer_capability("missing", available=False, message="CDX is required before assistant runs can be tracked.")
+    workspace = _viewer_capability(
+        "ready" if repo_root.is_dir() else "missing",
+        available=repo_root.is_dir(),
+        message="Workspace root can be inspected." if repo_root.is_dir() else "Workspace root is unavailable.",
+        detail={"root": str(repo_root.resolve())} if repo_root.is_dir() else {},
+    )
+    workshop_available = repo_root.is_dir()
+    terminals_available = workshop_available and workshop_terminals_available()
+    if terminals_available:
+        workshop_message = "Workshop command runner and PTY terminals are available."
+    elif workshop_available:
+        workshop_message = "Workshop command runner is available; PTY terminals require a Unix host with stdlib pty support."
+    else:
+        workshop_message = "Workshop is not available without a workspace root."
+    workshop = _viewer_capability(
+        "ready" if workshop_available else "missing",
+        available=workshop_available,
+        message=workshop_message,
+        detail={"terminalsAvailable": terminals_available, "commandsAvailable": workshop_available},
+    )
 
     return {
         "logics": logics,
+        "workspace": workspace,
+        "workshop": workshop,
         "git": git,
         "ci": ci,
         "cdx": cdx,
@@ -1156,6 +1205,278 @@ def git_file_preview_payload(
     }
 
 
+def _normalize_workspace_path(rel_path: str) -> str:
+    normalized = unquote(rel_path or "").replace("\\", "/").strip()
+    normalized = normalized.lstrip("/")
+    if normalized in {"", "."}:
+        return ""
+    if normalized.startswith("~") or re.match(r"^[A-Za-z]:", normalized):
+        raise ValueError("Unsafe workspace path.")
+    parts = [part for part in normalized.split("/") if part not in {"", "."}]
+    if any(part == ".." for part in parts):
+        raise ValueError("Workspace path escapes root.")
+    return "/".join(parts)
+
+
+def _resolve_workspace_path(repo_root: Path, rel_path: str) -> tuple[str, Path]:
+    normalized = _normalize_workspace_path(rel_path)
+    root = repo_root.resolve()
+    target = (root / normalized).resolve()
+    try:
+        target.relative_to(root)
+    except ValueError as exc:
+        raise ValueError("Workspace path escapes root.") from exc
+    return normalized, target
+
+
+def _workspace_entry_payload(root: Path, path: Path) -> dict[str, Any]:
+    try:
+        stat = path.stat()
+    except OSError:
+        stat = None
+    rel_path = path.relative_to(root).as_posix()
+    is_dir = path.is_dir()
+    ignored = is_dir and path.name in WORKSPACE_IGNORED_DIRS
+    return {
+        "name": path.name or root.name,
+        "path": rel_path,
+        "kind": "directory" if is_dir else "file",
+        "size": stat.st_size if stat else 0,
+        "ignored": ignored,
+        "childrenAvailable": is_dir and not ignored,
+    }
+
+
+def workspace_tree_payload(
+    repo_root: Path,
+    rel_path: str = "",
+    *,
+    max_entries: int = WORKSPACE_TREE_MAX_ENTRIES,
+) -> dict[str, Any]:
+    normalized, target = _resolve_workspace_path(repo_root, rel_path)
+    root = repo_root.resolve()
+    if not target.exists():
+        return {"state": "missing", "path": normalized, "message": "Workspace path does not exist."}
+    if not target.is_dir():
+        return {"state": "not-directory", "path": normalized, "message": "Workspace path is not a directory."}
+    entries = []
+    truncated = False
+    try:
+        children = sorted(target.iterdir(), key=lambda path: (not path.is_dir(), path.name.lower()))
+    except OSError as exc:
+        return {"state": "error", "path": normalized, "message": f"Unable to list workspace path: {exc}"}
+    for child in children:
+        if len(entries) >= max_entries:
+            truncated = True
+            break
+        entries.append(_workspace_entry_payload(root, child))
+    return {
+        "state": "ok",
+        "root": str(root),
+        "path": normalized,
+        "entries": entries,
+        "truncated": truncated,
+        "ignoredDirectories": sorted(WORKSPACE_IGNORED_DIRS),
+    }
+
+
+def workspace_preview_payload(
+    repo_root: Path,
+    rel_path: str,
+    *,
+    max_bytes: int = WORKSPACE_PREVIEW_MAX_BYTES,
+    max_chars: int = WORKSPACE_PREVIEW_MAX_CHARS,
+) -> dict[str, Any]:
+    normalized, target = _resolve_workspace_path(repo_root, rel_path)
+    if not target.exists():
+        return {"state": "missing", "path": normalized, "message": "Workspace path does not exist."}
+    if target.is_dir():
+        try:
+            count = sum(1 for _ in target.iterdir())
+        except OSError:
+            count = 0
+        return {
+            "state": "directory",
+            "path": normalized,
+            "name": target.name or repo_root.resolve().name,
+            "kind": "directory",
+            "message": f"{count} item(s)",
+            "childrenAvailable": target.name not in WORKSPACE_IGNORED_DIRS,
+        }
+    if not target.is_file():
+        return {"state": "unsupported", "path": normalized, "message": "Workspace object cannot be previewed."}
+    try:
+        size = target.stat().st_size
+    except OSError as exc:
+        return {"state": "error", "path": normalized, "message": f"Unable to inspect file: {exc}"}
+    if size > max_bytes:
+        return {
+            "state": "oversized",
+            "path": normalized,
+            "name": target.name,
+            "size": size,
+            "message": f"File preview is limited to {max_bytes} bytes; this file is {size} bytes.",
+        }
+    try:
+        data = target.read_bytes()
+    except OSError as exc:
+        return {"state": "error", "path": normalized, "message": f"Unable to read file preview: {exc}"}
+    content_type = mimetypes.guess_type(target.name)[0] or ""
+    if content_type.startswith("image/"):
+        return {
+            "state": "image",
+            "path": normalized,
+            "name": target.name,
+            "size": size,
+            "contentType": content_type,
+            "message": "Image preview is available from the workspace file endpoint.",
+        }
+    if b"\x00" in data:
+        return {
+            "state": "unsupported",
+            "path": normalized,
+            "name": target.name,
+            "size": size,
+            "message": "Binary or unsupported file content cannot be previewed.",
+        }
+    try:
+        content = data.decode("utf-8")
+    except UnicodeDecodeError:
+        return {
+            "state": "unsupported",
+            "path": normalized,
+            "name": target.name,
+            "size": size,
+            "message": "Binary or unsupported file encoding cannot be previewed.",
+        }
+    content = content.replace("\r\n", "\n").replace("\r", "\n")
+    truncated = len(content) > max_chars
+    if truncated:
+        content = content[:max_chars]
+    return {
+        "state": "ok",
+        "path": normalized,
+        "name": target.name,
+        "kind": "file",
+        "size": size,
+        "contentType": content_type or "text/plain",
+        "content": content,
+        "truncated": truncated,
+        "logicsType": _logics_doc_type(normalized),
+        "message": "",
+    }
+
+
+WORKSHOP_COMMAND_MAX = 200
+
+
+def _workshop_command_id(group: str, name: str) -> str:
+    safe = re.sub(r"[^a-z0-9._-]+", "-", f"{group}:{name}".lower()).strip("-") or "command"
+    return safe[:80]
+
+
+def _discover_package_json_scripts(repo_root: Path) -> list[dict[str, Any]]:
+    target = repo_root / "package.json"
+    if not target.is_file():
+        return []
+    try:
+        with target.open("rb") as handle:
+            payload = json.load(handle)
+    except (OSError, ValueError):
+        return []
+    scripts = payload.get("scripts") if isinstance(payload, dict) else None
+    if not isinstance(scripts, dict):
+        return []
+    entries: list[dict[str, Any]] = []
+    for name, command in scripts.items():
+        if not isinstance(name, str) or not isinstance(command, str):
+            continue
+        entries.append(
+            {
+                "id": _workshop_command_id("npm", name),
+                "source": "package.json",
+                "group": "npm scripts",
+                "name": name,
+                "command": command,
+                "runner": ["npm", "run", name],
+            }
+        )
+        if len(entries) >= WORKSHOP_COMMAND_MAX:
+            break
+    return entries
+
+
+def _discover_pyproject_scripts(repo_root: Path) -> list[dict[str, Any]]:
+    target = repo_root / "pyproject.toml"
+    if not target.is_file():
+        return []
+    try:
+        with target.open("rb") as handle:
+            payload = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError):
+        return []
+    entries: list[dict[str, Any]] = []
+    project_scripts = (payload.get("project") or {}).get("scripts")
+    if isinstance(project_scripts, dict):
+        for name, target_ref in project_scripts.items():
+            if not isinstance(name, str) or not isinstance(target_ref, str):
+                continue
+            entries.append(
+                {
+                    "id": _workshop_command_id("pyproject", name),
+                    "source": "pyproject.toml [project.scripts]",
+                    "group": "Project scripts",
+                    "name": name,
+                    "command": target_ref,
+                    "runner": [name],
+                }
+            )
+            if len(entries) >= WORKSHOP_COMMAND_MAX:
+                return entries
+    poetry_scripts = (
+        ((payload.get("tool") or {}).get("poetry") or {}).get("scripts")
+        if isinstance(payload.get("tool"), dict)
+        else None
+    )
+    if isinstance(poetry_scripts, dict):
+        for name, target_ref in poetry_scripts.items():
+            if not isinstance(name, str) or not isinstance(target_ref, str):
+                continue
+            entries.append(
+                {
+                    "id": _workshop_command_id("poetry", name),
+                    "source": "pyproject.toml [tool.poetry.scripts]",
+                    "group": "Poetry scripts",
+                    "name": name,
+                    "command": target_ref,
+                    "runner": ["poetry", "run", name],
+                }
+            )
+            if len(entries) >= WORKSHOP_COMMAND_MAX:
+                break
+    return entries
+
+
+def workshop_commands_payload(repo_root: Path) -> dict[str, Any]:
+    if not repo_root.is_dir():
+        return {"state": "unavailable", "commands": [], "message": "Workspace root is unavailable."}
+    commands: list[dict[str, Any]] = []
+    commands.extend(_discover_package_json_scripts(repo_root))
+    commands.extend(_discover_pyproject_scripts(repo_root))
+    seen: set[str] = set()
+    deduped: list[dict[str, Any]] = []
+    for entry in commands:
+        if entry["id"] in seen:
+            continue
+        seen.add(entry["id"])
+        deduped.append(entry)
+    return {
+        "state": "ok" if deduped else "empty",
+        "commands": deduped,
+        "message": "" if deduped else "No package.json or pyproject.toml entry points were found in the workspace root.",
+    }
+
+
 def _current_git_ci_context(repo_root: Path, *, runner: Any | None = None) -> dict[str, str]:
     context = {"branch": "", "headSha": "", "subject": "", "author": ""}
     commands = {
@@ -1195,28 +1516,21 @@ def _is_active_ci_status(run: dict[str, Any]) -> bool:
 
 
 def _select_github_actions_run(runs: list[dict[str, Any]], head_sha: str) -> tuple[dict[str, Any], str]:
-    head_runs = [run for run in runs if head_sha and str(run.get("head_sha") or "") == head_sha]
+    ci_runs = [run for run in runs if str(run.get("name") or "").strip().lower() == "ci"]
+    candidate_runs = ci_runs or runs
+    head_runs = [run for run in candidate_runs if head_sha and str(run.get("head_sha") or "") == head_sha]
     active_head_run = next((run for run in head_runs if _is_active_ci_status(run)), None)
     if active_head_run is not None:
         return active_head_run, "head-active"
-    failing_head_run = next((run for run in head_runs if _ci_badge_state(str(run.get("status") or ""), str(run.get("conclusion") or "")) == "failing"), None)
-    if failing_head_run is not None:
-        return failing_head_run, "head-failing"
-    cancelled_head_run = next((run for run in head_runs if _ci_badge_state(str(run.get("status") or ""), str(run.get("conclusion") or "")) == "cancelled"), None)
-    if cancelled_head_run is not None:
-        return cancelled_head_run, "head-cancelled"
-    unknown_head_run = next((run for run in head_runs if _ci_badge_state(str(run.get("status") or ""), str(run.get("conclusion") or "")) == "unknown"), None)
-    if unknown_head_run is not None:
-        return unknown_head_run, "head-unknown"
     if head_runs:
+        head_state = _ci_badge_state(str(head_runs[0].get("status") or ""), str(head_runs[0].get("conclusion") or ""))
+        if head_state in {"failing", "cancelled", "unknown"}:
+            return head_runs[0], f"head-{head_state}"
         return head_runs[0], "head"
-    active_branch_run = next((run for run in runs if _is_active_ci_status(run)), None)
+    active_branch_run = next((run for run in candidate_runs if _is_active_ci_status(run)), None)
     if active_branch_run is not None:
         return active_branch_run, "branch-active"
-    failing_branch_run = next((run for run in runs if _ci_badge_state(str(run.get("status") or ""), str(run.get("conclusion") or "")) == "failing"), None)
-    if failing_branch_run is not None:
-        return failing_branch_run, "branch-failing"
-    return runs[0], "branch-latest"
+    return candidate_runs[0], "branch-latest"
 
 
 def _parse_github_actions_run(run: dict[str, Any], *, match_source: str) -> dict[str, Any]:
@@ -1605,6 +1919,13 @@ def _cdx_mission_prompt(
     raise ValueError("Unknown CDX mission.")
 
 
+def _cdx_mission_timeout(strength: dict[str, Any], *, allow_file_writes: bool = False, commit_at_end: bool = False) -> int:
+    timeout = int(strength.get("timeout") or 180)
+    if allow_file_writes or commit_at_end:
+        return max(timeout, CDX_WRITABLE_MISSION_MIN_TIMEOUT_SECONDS)
+    return timeout
+
+
 def _cdx_mission_command(
     repo_root: Path,
     mission_id: str,
@@ -1627,7 +1948,7 @@ def _cdx_mission_command(
         direct_fixes=mission_inputs.get("directFixes") == "true",
         commit_at_end=commit_at_end,
     )
-    timeout = int(strength.get("timeout") or 180)
+    timeout = _cdx_mission_timeout(strength, allow_file_writes=allow_file_writes, commit_at_end=commit_at_end)
     reasoning_effort = str(strength.get("reasoningEffort") or "medium")
     power = str(strength.get("power") or "medium")
     permission = "workspace-write" if allow_file_writes else "read-only"
@@ -1868,6 +2189,7 @@ def cdx_mission_plan_payload(
         "requestedCommitAtEnd": requested_commit_at_end,
         "supportsFileWrites": supports_file_writes,
         "permission": permission,
+        "timeoutSeconds": _cdx_mission_timeout(strength_def, allow_file_writes=allow_file_writes, commit_at_end=commit_at_end),
         "command": ["cdx", *command],
         "arguments": command,
         "warnings": warnings,
@@ -1895,9 +2217,10 @@ def cdx_mission_run_payload(
     if plan_payload.get("state") != "ok":
         return {"state": plan_payload.get("state") or "error", "message": plan_payload.get("message") or "Unable to plan CDX mission.", "plan": plan_payload.get("plan"), "run": None}
     plan = plan_payload["plan"]
-    timeout = int(plan["strength"].get("timeout") or 180)
+    timeout = int(plan.get("timeoutSeconds") or plan["strength"].get("timeout") or 180)
+    process_timeout = timeout + CDX_MISSION_PARENT_TIMEOUT_GRACE_SECONDS
     try:
-        result = _run_cdx_mission(repo_root, list(plan["arguments"]), timeout=timeout, runner=cdx_runner)
+        result = _run_cdx_mission(repo_root, list(plan["arguments"]), timeout=process_timeout, runner=cdx_runner)
     except subprocess.TimeoutExpired:
         return {"state": "timeout", "message": "CDX mission timed out.", "plan": plan, "run": None}
     except (OSError, subprocess.SubprocessError) as exc:
@@ -2116,6 +2439,556 @@ def _json_bytes(payload: Any) -> bytes:
     return json.dumps(payload, indent=2, sort_keys=True).encode("utf-8")
 
 
+VIEWER_MUTATING_ROUTES = frozenset(
+    {
+        "/api/edit",
+        "/api/open-file",
+        "/api/open-repo-folder",
+        "/api/bootstrap-logics",
+        "/api/switch-project",
+        "/api/cdx-report-request",
+        "/api/cdx-mission-run",
+        "/api/cdx-mission-apply-plan",
+        "/api/workshop-command-start",
+        "/api/workshop-command-stop",
+        "/api/workshop-terminal-start",
+        "/api/workshop-terminal-stop",
+        "/api/workshop-terminal-input",
+        "/api/workshop-terminal-resize",
+    }
+)
+
+
+_WORKSHOP_SESSION_BUFFER_MAX = 4000
+_WORKSHOP_SESSION_TTL_SECONDS = 600
+
+
+class WorkshopCommandSession:
+    """Sandboxed subprocess for a Workshop command run.
+
+    Captures merged stdout+stderr into a ring buffer that SSE consumers can
+    tail incrementally via a monotonically increasing sequence number. Stop
+    delivers SIGTERM (Unix) or CTRL_BREAK_EVENT (Windows) to the process
+    group and falls back to SIGKILL if the process refuses to exit.
+    """
+
+    def __init__(self, session_id: str, command_id: str, runner: list[str], cwd: Path):
+        import collections
+        import threading
+        self.session_id = session_id
+        self.command_id = command_id
+        self.runner = list(runner)
+        self.cwd = cwd
+        self.started_at = ""
+        self.finished_at = ""
+        self.exit_code: int | None = None
+        self.state = "starting"
+        self.error: str = ""
+        self._buffer: collections.deque[tuple[int, str]] = collections.deque(maxlen=_WORKSHOP_SESSION_BUFFER_MAX)
+        self._seq = 0
+        self._lock = threading.Lock()
+        self._proc: subprocess.Popen[bytes] | None = None
+        self._reader: threading.Thread | None = None
+        self._waiter: threading.Thread | None = None
+        self._created_at = self._now()
+        self._last_activity = self._created_at
+
+    @staticmethod
+    def _now() -> float:
+        import time
+        return time.monotonic()
+
+    @staticmethod
+    def _iso_now() -> str:
+        return datetime.utcnow().isoformat(timespec="seconds") + "Z"
+
+    def append_line(self, channel: str, text: str) -> None:
+        with self._lock:
+            self._seq += 1
+            self._buffer.append((self._seq, f"{channel}\t{text}"))
+            self._last_activity = self._now()
+
+    def tail(self, since_seq: int) -> tuple[int, list[tuple[int, str]]]:
+        with self._lock:
+            snapshot = [(seq, line) for (seq, line) in self._buffer if seq > since_seq]
+            return self._seq, snapshot
+
+    def status_payload(self) -> dict[str, Any]:
+        with self._lock:
+            return {
+                "id": self.session_id,
+                "commandId": self.command_id,
+                "runner": list(self.runner),
+                "state": self.state,
+                "exitCode": self.exit_code,
+                "startedAt": self.started_at,
+                "finishedAt": self.finished_at,
+                "lastSeq": self._seq,
+                "error": self.error,
+            }
+
+    def is_expired(self, ttl_seconds: float = _WORKSHOP_SESSION_TTL_SECONDS) -> bool:
+        if self.state in {"running", "starting"}:
+            return False
+        return (self._now() - self._last_activity) > ttl_seconds
+
+    def start(self) -> None:
+        import threading
+        creation_flags = 0
+        popen_kwargs: dict[str, Any] = {
+            "cwd": str(self.cwd),
+            "stdout": subprocess.PIPE,
+            "stderr": subprocess.STDOUT,
+            "stdin": subprocess.DEVNULL,
+        }
+        if sys.platform == "win32":
+            creation_flags = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+            popen_kwargs["creationflags"] = creation_flags
+        else:
+            popen_kwargs["start_new_session"] = True
+        try:
+            self._proc = subprocess.Popen(self.runner, **popen_kwargs)
+        except (OSError, ValueError) as exc:
+            self.state = "error"
+            self.error = f"Unable to start command: {exc}"
+            self.finished_at = self._iso_now()
+            return
+        self.started_at = self._iso_now()
+        self.state = "running"
+        self._reader = threading.Thread(target=self._read_loop, name=f"workshop-reader-{self.session_id}", daemon=True)
+        self._reader.start()
+        self._waiter = threading.Thread(target=self._wait_loop, name=f"workshop-waiter-{self.session_id}", daemon=True)
+        self._waiter.start()
+
+    def _read_loop(self) -> None:
+        proc = self._proc
+        if proc is None or proc.stdout is None:
+            return
+        try:
+            for raw in iter(proc.stdout.readline, b""):
+                try:
+                    text = raw.decode("utf-8", errors="replace").rstrip("\r\n")
+                except Exception:
+                    continue
+                self.append_line("stdout", text)
+        except (OSError, ValueError):
+            pass
+
+    def _wait_loop(self) -> None:
+        proc = self._proc
+        if proc is None:
+            return
+        try:
+            code = proc.wait()
+        except Exception as exc:
+            self.error = f"Wait failed: {exc}"
+            code = -1
+        with self._lock:
+            self.exit_code = code
+            self.finished_at = self._iso_now()
+            self.state = "finished" if code == 0 else ("stopped" if code in (-15, 143, -9, 137) else "failed")
+            self._last_activity = self._now()
+
+    def stop(self, *, timeout: float = 5.0) -> None:
+        proc = self._proc
+        if proc is None or proc.poll() is not None:
+            return
+        try:
+            if sys.platform == "win32":
+                sig = getattr(__import__("signal"), "CTRL_BREAK_EVENT", None)
+                if sig is not None:
+                    proc.send_signal(sig)
+                else:
+                    proc.terminate()
+            else:
+                import os as _os
+                import signal as _signal
+                try:
+                    _os.killpg(proc.pid, _signal.SIGTERM)
+                except (OSError, ProcessLookupError):
+                    proc.terminate()
+        except Exception:
+            proc.terminate()
+        try:
+            proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            try:
+                if sys.platform == "win32":
+                    proc.kill()
+                else:
+                    import os as _os
+                    import signal as _signal
+                    _os.killpg(proc.pid, _signal.SIGKILL)
+            except Exception:
+                proc.kill()
+
+
+class WorkshopSessionRegistry:
+    def __init__(self) -> None:
+        import threading
+        self._sessions: dict[str, WorkshopCommandSession] = {}
+        self._lock = threading.Lock()
+        self._counter = 0
+
+    def create(self, command_entry: dict[str, Any], repo_root: Path) -> WorkshopCommandSession:
+        runner = command_entry.get("runner")
+        if not isinstance(runner, list) or not runner or not all(isinstance(part, str) and part for part in runner):
+            raise ValueError("Command entry is missing a valid runner.")
+        if not repo_root.is_dir():
+            raise ValueError("Workspace root is unavailable.")
+        with self._lock:
+            self._counter += 1
+            session_id = f"ws-{self._counter:06d}"
+        session = WorkshopCommandSession(
+            session_id=session_id,
+            command_id=str(command_entry.get("id") or ""),
+            runner=runner,
+            cwd=repo_root,
+        )
+        with self._lock:
+            self._prune_locked()
+            self._sessions[session_id] = session
+        session.start()
+        return session
+
+    def get(self, session_id: str) -> WorkshopCommandSession | None:
+        with self._lock:
+            return self._sessions.get(session_id)
+
+    def list(self) -> list[dict[str, Any]]:
+        with self._lock:
+            self._prune_locked()
+            return [session.status_payload() for session in self._sessions.values()]
+
+    def _prune_locked(self) -> None:
+        for sid in list(self._sessions.keys()):
+            if self._sessions[sid].is_expired():
+                del self._sessions[sid]
+
+    def shutdown(self) -> None:
+        with self._lock:
+            sessions = list(self._sessions.values())
+        for session in sessions:
+            session.stop(timeout=1.0)
+
+
+_WORKSHOP_TERMINAL_BUFFER_MAX = 8000
+_WORKSHOP_TERMINAL_TTL_SECONDS = 1800
+_WORKSHOP_TERMINAL_IDLE_KILL_SECONDS = 60.0
+
+
+def workshop_terminals_available() -> bool:
+    """True when the host can spawn PTY sessions through the stdlib backend."""
+    if sys.platform == "win32":
+        return False
+    try:
+        import pty  # noqa: F401
+        import termios  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def _default_workshop_shell() -> list[str]:
+    candidate = os.environ.get("SHELL") or ""
+    if candidate and os.access(candidate, os.X_OK):
+        return [candidate, "-i"]
+    for fallback in ("/bin/zsh", "/bin/bash", "/bin/sh"):
+        if os.access(fallback, os.X_OK):
+            return [fallback, "-i"]
+    return ["/bin/sh"]
+
+
+class WorkshopTerminalSession:
+    """Interactive PTY-backed terminal session using stdlib `pty`.
+
+    Reads from the master fd in a daemon thread, buffers output bytes
+    (decoded utf-8 with replace) into a ring; writes from the client land
+    on the master fd directly. Resize uses TIOCSWINSZ ioctl. Stop sends
+    SIGTERM to the session leader and falls back to SIGKILL after a grace
+    window. Unix-only: Windows callers must check
+    workshop_terminals_available() before instantiating.
+    """
+
+    def __init__(self, session_id: str, command: list[str], cwd: Path, *, label: str = ""):
+        import collections
+        import threading
+        self.session_id = session_id
+        self.command = list(command)
+        self.cwd = cwd
+        self.label = label or (command[0] if command else "shell")
+        self.started_at = ""
+        self.finished_at = ""
+        self.exit_code: int | None = None
+        self.state = "starting"
+        self.error: str = ""
+        self._buffer: collections.deque[tuple[int, str]] = collections.deque(maxlen=_WORKSHOP_TERMINAL_BUFFER_MAX)
+        self._seq = 0
+        self._lock = threading.Lock()
+        self._master_fd: int | None = None
+        self._pid: int | None = None
+        self._reader: threading.Thread | None = None
+        self._reaper: threading.Thread | None = None
+        self._created_at = self._now()
+        self._last_activity = self._created_at
+        self._listeners = 0
+        self._idle_timer: threading.Timer | None = None
+        self._idle_kill_seconds = _WORKSHOP_TERMINAL_IDLE_KILL_SECONDS
+
+    @staticmethod
+    def _now() -> float:
+        import time
+        return time.monotonic()
+
+    @staticmethod
+    def _iso_now() -> str:
+        return datetime.utcnow().isoformat(timespec="seconds") + "Z"
+
+    def _append(self, text: str) -> None:
+        with self._lock:
+            self._seq += 1
+            self._buffer.append((self._seq, text))
+            self._last_activity = self._now()
+
+    def tail(self, since_seq: int) -> tuple[int, list[tuple[int, str]]]:
+        with self._lock:
+            snapshot = [(seq, chunk) for (seq, chunk) in self._buffer if seq > since_seq]
+            return self._seq, snapshot
+
+    def status_payload(self) -> dict[str, Any]:
+        with self._lock:
+            return {
+                "id": self.session_id,
+                "label": self.label,
+                "command": list(self.command),
+                "state": self.state,
+                "exitCode": self.exit_code,
+                "startedAt": self.started_at,
+                "finishedAt": self.finished_at,
+                "lastSeq": self._seq,
+                "error": self.error,
+            }
+
+    def is_expired(self, ttl_seconds: float = _WORKSHOP_TERMINAL_TTL_SECONDS) -> bool:
+        if self.state in {"running", "starting"}:
+            return False
+        return (self._now() - self._last_activity) > ttl_seconds
+
+    def attach_listener(self) -> None:
+        """Register a live SSE consumer for this session."""
+        with self._lock:
+            self._listeners += 1
+            if self._idle_timer is not None:
+                self._idle_timer.cancel()
+                self._idle_timer = None
+
+    def detach_listener(self) -> None:
+        """Release an SSE consumer; arm the idle-kill timer if none remain."""
+        import threading
+        arm = False
+        with self._lock:
+            self._listeners = max(0, self._listeners - 1)
+            if self._listeners == 0 and self.state in {"running", "starting"}:
+                if self._idle_timer is not None:
+                    self._idle_timer.cancel()
+                self._idle_timer = threading.Timer(self._idle_kill_seconds, self._on_idle_timeout)
+                self._idle_timer.daemon = True
+                arm = True
+        if arm and self._idle_timer is not None:
+            self._idle_timer.start()
+
+    def _on_idle_timeout(self) -> None:
+        with self._lock:
+            still_idle = self._listeners == 0 and self.state in {"running", "starting"}
+            self._idle_timer = None
+        if not still_idle:
+            return
+        # Best-effort: SIGTERM the session group, falling back to SIGKILL.
+        self.stop(timeout=3.0)
+
+    def start(self) -> None:
+        import threading
+        if not workshop_terminals_available():
+            self.state = "error"
+            self.error = "PTY backend is not available on this host."
+            self.finished_at = self._iso_now()
+            return
+        import pty
+        try:
+            pid, master_fd = pty.fork()
+        except (OSError, RuntimeError) as exc:
+            self.state = "error"
+            self.error = f"Unable to fork PTY: {exc}"
+            self.finished_at = self._iso_now()
+            return
+        if pid == 0:
+            try:
+                os.chdir(str(self.cwd))
+            except OSError:
+                pass
+            env = os.environ.copy()
+            env.setdefault("TERM", "xterm-256color")
+            env.setdefault("COLORTERM", "truecolor")
+            try:
+                os.execvpe(self.command[0], self.command, env)
+            except Exception as exc:  # noqa: BLE001
+                sys.stderr.write(f"Unable to exec {self.command[0]}: {exc}\n")
+                os._exit(127)
+        self._pid = pid
+        self._master_fd = master_fd
+        self.started_at = self._iso_now()
+        self.state = "running"
+        self._reader = threading.Thread(target=self._read_loop, name=f"workshop-pty-reader-{self.session_id}", daemon=True)
+        self._reader.start()
+        self._reaper = threading.Thread(target=self._reap_loop, name=f"workshop-pty-reaper-{self.session_id}", daemon=True)
+        self._reaper.start()
+
+    def write(self, data: str) -> None:
+        if not data or self._master_fd is None:
+            return
+        try:
+            os.write(self._master_fd, data.encode("utf-8"))
+        except OSError as exc:
+            self.error = f"Write failed: {exc}"
+
+    def resize(self, rows: int, cols: int) -> None:
+        if self._master_fd is None or rows <= 0 or cols <= 0:
+            return
+        try:
+            import fcntl
+            import struct
+            import termios
+            fcntl.ioctl(self._master_fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+        except (OSError, ImportError):
+            return
+
+    def _read_loop(self) -> None:
+        fd = self._master_fd
+        if fd is None:
+            return
+        try:
+            while True:
+                try:
+                    chunk = os.read(fd, 4096)
+                except OSError:
+                    break
+                if not chunk:
+                    break
+                try:
+                    text = chunk.decode("utf-8", errors="replace")
+                except Exception:  # noqa: BLE001
+                    continue
+                self._append(text)
+        finally:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+
+    def _reap_loop(self) -> None:
+        pid = self._pid
+        if pid is None:
+            return
+        try:
+            _, status = os.waitpid(pid, 0)
+        except OSError as exc:
+            self.error = f"waitpid failed: {exc}"
+            status = -1
+        if isinstance(status, int):
+            if os.WIFEXITED(status):
+                code = os.WEXITSTATUS(status)
+            elif os.WIFSIGNALED(status):
+                code = -os.WTERMSIG(status)
+            else:
+                code = -1
+        else:
+            code = -1
+        with self._lock:
+            self.exit_code = code
+            self.finished_at = self._iso_now()
+            self.state = "finished" if code == 0 else ("stopped" if code in (-15, -9) else "failed")
+            self._last_activity = self._now()
+            if self._idle_timer is not None:
+                self._idle_timer.cancel()
+                self._idle_timer = None
+
+    def stop(self, *, timeout: float = 3.0) -> None:
+        pid = self._pid
+        if pid is None:
+            return
+        import signal as _signal
+        import time as _time
+        try:
+            os.killpg(os.getpgid(pid), _signal.SIGTERM)
+        except (OSError, ProcessLookupError):
+            try:
+                os.kill(pid, _signal.SIGTERM)
+            except OSError:
+                return
+        deadline = _time.monotonic() + timeout
+        while _time.monotonic() < deadline:
+            with self._lock:
+                if self.state in {"finished", "failed", "stopped"}:
+                    return
+            _time.sleep(0.05)
+        try:
+            os.killpg(os.getpgid(pid), _signal.SIGKILL)
+        except (OSError, ProcessLookupError):
+            try:
+                os.kill(pid, _signal.SIGKILL)
+            except OSError:
+                return
+
+
+class WorkshopTerminalRegistry:
+    def __init__(self) -> None:
+        import threading
+        self._sessions: dict[str, WorkshopTerminalSession] = {}
+        self._lock = threading.Lock()
+        self._counter = 0
+
+    def create(self, command: list[str], cwd: Path, *, label: str = "") -> WorkshopTerminalSession:
+        if not workshop_terminals_available():
+            raise ValueError("PTY backend is not available on this host.")
+        if not command or not isinstance(command, list):
+            raise ValueError("Terminal command must be a non-empty list.")
+        if not cwd.is_dir():
+            raise ValueError("Workspace root is unavailable.")
+        with self._lock:
+            self._counter += 1
+            session_id = f"wt-{self._counter:06d}"
+        session = WorkshopTerminalSession(session_id=session_id, command=command, cwd=cwd, label=label)
+        with self._lock:
+            self._prune_locked()
+            self._sessions[session_id] = session
+        session.start()
+        return session
+
+    def get(self, session_id: str) -> WorkshopTerminalSession | None:
+        with self._lock:
+            return self._sessions.get(session_id)
+
+    def list(self) -> list[dict[str, Any]]:
+        with self._lock:
+            self._prune_locked()
+            return [session.status_payload() for session in self._sessions.values()]
+
+    def _prune_locked(self) -> None:
+        for sid in list(self._sessions.keys()):
+            if self._sessions[sid].is_expired():
+                del self._sessions[sid]
+
+    def shutdown(self) -> None:
+        with self._lock:
+            sessions = list(self._sessions.values())
+        for session in sessions:
+            session.stop(timeout=1.0)
+
+
+def workshop_terminal_default_command() -> list[str]:
+    return _default_workshop_shell()
+
+
 class LogicsViewerServer(ThreadingHTTPServer):
     def __init__(
         self,
@@ -2123,6 +2996,8 @@ class LogicsViewerServer(ThreadingHTTPServer):
         repo_root: Path,
         *,
         auto_refresh_interval_seconds: int = 15,
+        auto_refresh_interval_forced: bool = False,
+        lan_mode: bool = False,
     ):
         self.launch_repo_root = repo_root.resolve()
         self.project_roots = discover_viewer_project_roots(self.launch_repo_root)
@@ -2130,18 +3005,41 @@ class LogicsViewerServer(ThreadingHTTPServer):
         self.active_project_id = _viewer_project_id(self.launch_repo_root)
         self.repo_root = self.launch_repo_root
         self.auto_refresh_interval_seconds = auto_refresh_interval_seconds
+        self.auto_refresh_interval_forced = auto_refresh_interval_forced
+        self.lan_mode = bool(lan_mode)
+        self.lan_token = secrets.token_urlsafe(32) if self.lan_mode else ""
+        self.workshop_sessions = WorkshopSessionRegistry()
+        self.workshop_terminals = WorkshopTerminalRegistry()
         super().__init__(server_address, LogicsViewerRequestHandler)
 
+    def server_close(self) -> None:
+        try:
+            self.workshop_sessions.shutdown()
+        finally:
+            try:
+                self.workshop_terminals.shutdown()
+            finally:
+                super().server_close()
+
     def project_registry_payload(self) -> list[dict[str, Any]]:
         return viewer_project_registry(self.repo_root, project_roots=self.project_roots)
 
     def viewer_payload(self, *, selected_id: str | None = None) -> dict[str, Any]:
-        return viewer_data_payload(
+        payload = viewer_data_payload(
             self.repo_root,
             selected_id=selected_id,
             auto_refresh_interval_seconds=self.auto_refresh_interval_seconds,
+            auto_refresh_interval_forced=self.auto_refresh_interval_forced,
             projects=self.project_registry_payload(),
         )
+        payload["lanMode"] = bool(self.lan_mode)
+        if self.lan_mode and self.lan_token:
+            host, port = self.server_address[:2]
+            lan_url = _network_viewer_url(str(host), int(port)) or build_viewer_url(str(host), int(port))
+            payload["lanShareUrl"] = _append_lan_token(lan_url, self.lan_token)
+        else:
+            payload["lanShareUrl"] = ""
+        return payload
 
     def switch_project(self, project_id: str) -> dict[str, Any]:
         target = self.project_root_by_id.get(project_id)
@@ -2185,8 +3083,175 @@ class LogicsViewerRequestHandler(BaseHTTPRequestHandler):
             content_type = f"{content_type}; charset=utf-8"
         self._send_bytes(path.read_bytes(), content_type=content_type)
 
+    def _stream_workshop_terminal(self, session: "WorkshopTerminalSession", parsed: Any) -> None:
+        import time as _time
+        try:
+            since = int(parse_qs(parsed.query).get("since", ["0"])[0])
+        except (TypeError, ValueError):
+            since = 0
+        try:
+            self.send_response(200)
+            self.send_header("Content-Type", "text/event-stream; charset=utf-8")
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("X-Accel-Buffering", "no")
+            self.end_headers()
+        except (BrokenPipeError, ConnectionResetError):
+            return
+        session.attach_listener()
+        try:
+            last_seq = since
+            idle_ticks = 0
+            while True:
+                latest_seq, snapshot = session.tail(last_seq)
+                if snapshot:
+                    idle_ticks = 0
+                    for seq, chunk in snapshot:
+                        last_seq = seq
+                        try:
+                            payload = json.dumps({"seq": seq, "data": chunk})
+                            self.wfile.write(f"event: data\ndata: {payload}\n\n".encode("utf-8"))
+                            self.wfile.flush()
+                        except (BrokenPipeError, ConnectionResetError):
+                            return
+                state = session.state
+                if state in {"finished", "failed", "stopped", "error"} and last_seq >= latest_seq:
+                    try:
+                        payload = json.dumps(session.status_payload())
+                        self.wfile.write(f"event: end\ndata: {payload}\n\n".encode("utf-8"))
+                        self.wfile.flush()
+                    except (BrokenPipeError, ConnectionResetError):
+                        return
+                    return
+                idle_ticks += 1
+                if idle_ticks >= 30:
+                    try:
+                        self.wfile.write(b": keep-alive\n\n")
+                        self.wfile.flush()
+                    except (BrokenPipeError, ConnectionResetError):
+                        return
+                    idle_ticks = 0
+                _time.sleep(0.1)
+        except (BrokenPipeError, ConnectionResetError):
+            return
+        finally:
+            session.detach_listener()
+
+    def _stream_workshop_session(self, session: "WorkshopCommandSession", parsed: Any) -> None:
+        import time as _time
+        try:
+            since = int(parse_qs(parsed.query).get("since", ["0"])[0])
+        except (TypeError, ValueError):
+            since = 0
+        try:
+            self.send_response(200)
+            self.send_header("Content-Type", "text/event-stream; charset=utf-8")
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("X-Accel-Buffering", "no")
+            self.end_headers()
+        except (BrokenPipeError, ConnectionResetError):
+            return
+        last_seq = since
+        idle_ticks = 0
+        try:
+            while True:
+                latest_seq, snapshot = session.tail(last_seq)
+                if snapshot:
+                    idle_ticks = 0
+                    for seq, line in snapshot:
+                        last_seq = seq
+                        try:
+                            channel, _, text = line.partition("\t")
+                            payload = json.dumps({"seq": seq, "channel": channel, "line": text})
+                            self.wfile.write(f"event: line\ndata: {payload}\n\n".encode("utf-8"))
+                            self.wfile.flush()
+                        except (BrokenPipeError, ConnectionResetError):
+                            return
+                state = session.state
+                if state in {"finished", "failed", "stopped", "error"} and last_seq >= latest_seq:
+                    try:
+                        payload = json.dumps(session.status_payload())
+                        self.wfile.write(f"event: end\ndata: {payload}\n\n".encode("utf-8"))
+                        self.wfile.flush()
+                    except (BrokenPipeError, ConnectionResetError):
+                        return
+                    return
+                idle_ticks += 1
+                if idle_ticks >= 30:
+                    try:
+                        self.wfile.write(b": keep-alive\n\n")
+                        self.wfile.flush()
+                    except (BrokenPipeError, ConnectionResetError):
+                        return
+                    idle_ticks = 0
+                _time.sleep(0.2)
+        except (BrokenPipeError, ConnectionResetError):
+            return
+
+    def _client_is_loopback(self) -> bool:
+        try:
+            host = self.client_address[0]
+        except (IndexError, AttributeError):
+            return False
+        if not host:
+            return False
+        if host in {"127.0.0.1", "::1"}:
+            return True
+        if host.startswith("127."):
+            return True
+        if host.startswith("::ffff:127."):
+            return True
+        return False
+
+    def _is_public_get_route(self, route: str) -> bool:
+        """Static UI assets that must load before the JS can attach the bearer.
+
+        Browsers do not auto-attach Authorization headers to <script src>,
+        <link href>, or @font-face fetches, and we cannot put ?t= on every
+        asset URL the page references. We let these routes through
+        unauthenticated; they expose no repository data — every actual
+        payload lives under /api/* which stays gated.
+        """
+        if route in {"/", "/browser-host.js", "/viewer.css", "/vendor/mermaid.min.js"}:
+            return True
+        if route.startswith("/media/"):
+            return True
+        return False
+
+    def _lan_auth_passes(self, parsed: Any, *, method: str = "GET") -> bool:
+        token = self.server.lan_token
+        if not token:
+            return True
+        if self._client_is_loopback():
+            return True
+        if method == "GET" and self._is_public_get_route(parsed.path):
+            return True
+        header = self.headers.get("Authorization", "")
+        if header.lower().startswith("bearer "):
+            candidate = header.split(" ", 1)[1].strip()
+            if candidate and hmac.compare_digest(candidate, token):
+                return True
+        query_token = (parse_qs(parsed.query).get("t") or [""])[0]
+        if query_token and hmac.compare_digest(query_token, token):
+            return True
+        return False
+
+    def _send_lan_unauthorized(self) -> None:
+        body = _json_bytes({"ok": False, "error": "LAN viewer requires a bearer token. Open the share URL from the launch banner."})
+        try:
+            self.send_response(HTTPStatus.UNAUTHORIZED)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("WWW-Authenticate", 'Bearer realm="logics-viewer"')
+            self.end_headers()
+            self.wfile.write(body)
+        except (BrokenPipeError, ConnectionResetError):
+            return
+
     def do_GET(self) -> None:
         parsed = urlparse(self.path)
+        if not self._lan_auth_passes(parsed, method="GET"):
+            self._send_lan_unauthorized()
+            return
         route = parsed.path
         if route == "/":
             self._serve_file(VIEWER_ROOT / "index.html")
@@ -2266,10 +3331,91 @@ class LogicsViewerRequestHandler(BaseHTTPRequestHandler):
             rel_path = params.get("path", [""])[0]
             self._send_json({"ok": True, "payload": git_file_preview_payload(self.server.repo_root, rel_path)})
             return
+        if route == "/api/workspace-tree":
+            rel_path = parse_qs(parsed.query).get("path", [""])[0]
+            try:
+                self._send_json({"ok": True, "payload": workspace_tree_payload(self.server.repo_root, rel_path)})
+            except ValueError as exc:
+                self._send_error_json(HTTPStatus.FORBIDDEN, str(exc))
+            return
+        if route == "/api/workspace-preview":
+            rel_path = parse_qs(parsed.query).get("path", [""])[0]
+            try:
+                self._send_json({"ok": True, "payload": workspace_preview_payload(self.server.repo_root, rel_path)})
+            except ValueError as exc:
+                self._send_error_json(HTTPStatus.FORBIDDEN, str(exc))
+            return
+        if route == "/api/workshop-commands":
+            try:
+                self._send_json({"ok": True, "payload": workshop_commands_payload(self.server.repo_root)})
+            except ValueError as exc:
+                self._send_error_json(HTTPStatus.FORBIDDEN, str(exc))
+            return
+        if route == "/api/workshop-sessions":
+            self._send_json({"ok": True, "payload": {"sessions": self.server.workshop_sessions.list()}})
+            return
+        if route == "/api/workshop-terminals":
+            self._send_json({"ok": True, "payload": {"sessions": self.server.workshop_terminals.list(), "available": workshop_terminals_available()}})
+            return
+        if route.startswith("/api/workshop-terminal/"):
+            tail = route[len("/api/workshop-terminal/"):]
+            parts = tail.split("/", 1)
+            session_id = parts[0]
+            kind = parts[1] if len(parts) > 1 else "status"
+            session = self.server.workshop_terminals.get(session_id)
+            if session is None:
+                self._send_error_json(HTTPStatus.NOT_FOUND, "Workshop terminal not found.")
+                return
+            if kind == "status":
+                self._send_json({"ok": True, "payload": session.status_payload()})
+                return
+            if kind == "stream":
+                self._stream_workshop_terminal(session, parsed)
+                return
+            self._send_error_json(HTTPStatus.NOT_FOUND, "Unknown terminal sub-resource.")
+            return
+        if route.startswith("/api/workshop-session/"):
+            tail = route[len("/api/workshop-session/"):]
+            parts = tail.split("/", 1)
+            session_id = parts[0]
+            kind = parts[1] if len(parts) > 1 else "status"
+            session = self.server.workshop_sessions.get(session_id)
+            if session is None:
+                self._send_error_json(HTTPStatus.NOT_FOUND, "Workshop session not found.")
+                return
+            if kind == "status":
+                self._send_json({"ok": True, "payload": session.status_payload()})
+                return
+            if kind == "stream":
+                self._stream_workshop_session(session, parsed)
+                return
+            self._send_error_json(HTTPStatus.NOT_FOUND, "Unknown session sub-resource.")
+            return
+        if route == "/api/workspace-file":
+            rel_path = parse_qs(parsed.query).get("path", [""])[0]
+            try:
+                payload = workspace_preview_payload(self.server.repo_root, rel_path)
+                if payload.get("state") != "image":
+                    self._send_error_json(HTTPStatus.BAD_REQUEST, "Workspace file is not an image preview.")
+                    return
+                _normalized, absolute = _resolve_workspace_path(self.server.repo_root, rel_path)
+                self._serve_file(absolute)
+            except (FileNotFoundError, ValueError) as exc:
+                self._send_error_json(HTTPStatus.NOT_FOUND, str(exc))
+            return
         self._send_error_json(HTTPStatus.NOT_FOUND, "Not found")
 
     def do_POST(self) -> None:
         parsed = urlparse(self.path)
+        if not self._lan_auth_passes(parsed, method="POST"):
+            self._send_lan_unauthorized()
+            return
+        if self.server.lan_mode and parsed.path in VIEWER_MUTATING_ROUTES:
+            self._send_error_json(
+                HTTPStatus.FORBIDDEN,
+                "Mutating endpoint refused: the viewer is exposed on the LAN in read-only mode.",
+            )
+            return
         if parsed.path == "/api/refresh":
             self._send_json(
                 {
@@ -2292,6 +3438,105 @@ class LogicsViewerRequestHandler(BaseHTTPRequestHandler):
             except FileNotFoundError as exc:
                 self._send_error_json(HTTPStatus.NOT_FOUND, str(exc))
             return
+        if parsed.path == "/api/workshop-command-start":
+            try:
+                length = int(self.headers.get("Content-Length", "0") or "0")
+                raw_body = self.rfile.read(length).decode("utf-8") if length > 0 else "{}"
+                body = json.loads(raw_body or "{}")
+                command_id = str(body.get("commandId") or "")
+                if not command_id:
+                    self._send_error_json(HTTPStatus.BAD_REQUEST, "Missing commandId.")
+                    return
+                catalog = workshop_commands_payload(self.server.repo_root)
+                entry = next((c for c in catalog.get("commands", []) if c.get("id") == command_id), None)
+                if entry is None:
+                    self._send_error_json(HTTPStatus.NOT_FOUND, "Unknown command id.")
+                    return
+                session = self.server.workshop_sessions.create(entry, self.server.repo_root)
+                self._send_json({"ok": True, "payload": session.status_payload()})
+            except json.JSONDecodeError:
+                self._send_error_json(HTTPStatus.BAD_REQUEST, "Invalid JSON body.")
+            except ValueError as exc:
+                self._send_error_json(HTTPStatus.FORBIDDEN, str(exc))
+            return
+        if parsed.path == "/api/workshop-terminal-start":
+            try:
+                length = int(self.headers.get("Content-Length", "0") or "0")
+                raw_body = self.rfile.read(length).decode("utf-8") if length > 0 else "{}"
+                body = json.loads(raw_body or "{}")
+                command_override = body.get("command")
+                label = str(body.get("label") or "")
+                command = command_override if isinstance(command_override, list) and all(isinstance(p, str) for p in command_override) and command_override else workshop_terminal_default_command()
+                session = self.server.workshop_terminals.create(command, self.server.repo_root, label=label)
+                self._send_json({"ok": True, "payload": session.status_payload()})
+            except json.JSONDecodeError:
+                self._send_error_json(HTTPStatus.BAD_REQUEST, "Invalid JSON body.")
+            except ValueError as exc:
+                self._send_error_json(HTTPStatus.FORBIDDEN, str(exc))
+            return
+        if parsed.path == "/api/workshop-terminal-input":
+            try:
+                length = int(self.headers.get("Content-Length", "0") or "0")
+                raw_body = self.rfile.read(length).decode("utf-8") if length > 0 else "{}"
+                body = json.loads(raw_body or "{}")
+                session_id = str(body.get("sessionId") or "")
+                data = str(body.get("data") or "")
+                session = self.server.workshop_terminals.get(session_id)
+                if session is None:
+                    self._send_error_json(HTTPStatus.NOT_FOUND, "Workshop terminal not found.")
+                    return
+                session.write(data)
+                self._send_json({"ok": True})
+            except json.JSONDecodeError:
+                self._send_error_json(HTTPStatus.BAD_REQUEST, "Invalid JSON body.")
+            return
+        if parsed.path == "/api/workshop-terminal-resize":
+            try:
+                length = int(self.headers.get("Content-Length", "0") or "0")
+                raw_body = self.rfile.read(length).decode("utf-8") if length > 0 else "{}"
+                body = json.loads(raw_body or "{}")
+                session_id = str(body.get("sessionId") or "")
+                rows = int(body.get("rows") or 0)
+                cols = int(body.get("cols") or 0)
+                session = self.server.workshop_terminals.get(session_id)
+                if session is None:
+                    self._send_error_json(HTTPStatus.NOT_FOUND, "Workshop terminal not found.")
+                    return
+                session.resize(rows, cols)
+                self._send_json({"ok": True})
+            except (json.JSONDecodeError, ValueError):
+                self._send_error_json(HTTPStatus.BAD_REQUEST, "Invalid resize body.")
+            return
+        if parsed.path == "/api/workshop-terminal-stop":
+            try:
+                length = int(self.headers.get("Content-Length", "0") or "0")
+                raw_body = self.rfile.read(length).decode("utf-8") if length > 0 else "{}"
+                body = json.loads(raw_body or "{}")
+                session_id = str(body.get("sessionId") or "")
+                session = self.server.workshop_terminals.get(session_id)
+                if session is None:
+                    self._send_error_json(HTTPStatus.NOT_FOUND, "Workshop terminal not found.")
+                    return
+                session.stop()
+                self._send_json({"ok": True, "payload": session.status_payload()})
+            except json.JSONDecodeError:
+                self._send_error_json(HTTPStatus.BAD_REQUEST, "Invalid JSON body.")
+            return
+        if parsed.path == "/api/workshop-command-stop":
+            try:
+                length = int(self.headers.get("Content-Length", "0") or "0")
+                raw_body = self.rfile.read(length).decode("utf-8") if length > 0 else "{}"
+                body = json.loads(raw_body or "{}")
+                session_id = str(body.get("sessionId") or "")
+                session = self.server.workshop_sessions.get(session_id)
+                if session is None:
+                    self._send_error_json(HTTPStatus.NOT_FOUND, "Workshop session not found.")
+                    return
+                session.stop()
+                self._send_json({"ok": True, "payload": session.status_payload()})
+            except json.JSONDecodeError:
+                self._send_error_json(HTTPStatus.BAD_REQUEST, "Invalid JSON body.")
+            return
         if parsed.path == "/api/bootstrap-logics":
             try:
                 bootstrap = bootstrap_payload(self.server.repo_root, check=False)
@@ -2394,22 +3639,82 @@ def create_viewer_server(
     port: int = 8765,
     *,
     auto_refresh_interval_seconds: int = 15,
+    auto_refresh_interval_forced: bool = False,
+    lan_mode: bool = False,
 ) -> LogicsViewerServer:
     return LogicsViewerServer(
         (host, port),
         repo_root,
         auto_refresh_interval_seconds=auto_refresh_interval_seconds,
+        auto_refresh_interval_forced=auto_refresh_interval_forced,
+        lan_mode=lan_mode,
     )
 
 
-def _network_viewer_url(host: str, port: int, *, focus: str | None = None, read: bool = False) -> str | None:
-    if host not in {"0.0.0.0", "::", ""}:
-        return None
+def _render_qr_lines(url: str) -> list[str]:
+    if not url:
+        return []
     try:
-        candidate = socket.gethostbyname(socket.gethostname())
+        import segno  # type: ignore
+    except ImportError:
+        return [
+            "+" + "-" * (len(url) + 2) + "+",
+            "| " + url + " |",
+            "+" + "-" * (len(url) + 2) + "+",
+            "(Install the optional `segno` package to render a scannable QR matrix.)",
+        ]
+    try:
+        qr = segno.make(url, error="m")
+        buffer: list[str] = []
+        qr.terminal(out=type("Buf", (), {"write": lambda self, value: buffer.append(value)})(), border=1)
+        # segno's terminal output ends each line with newline; flatten back into lines.
+        return ("".join(buffer)).splitlines() or [url]
+    except Exception:
+        return [url]
+
+
+def _append_lan_token(url: str, token: str) -> str:
+    if not url or not token:
+        return url
+    sep = "&" if "?" in url else "?"
+    return f"{url}{sep}t={quote(token, safe='')}"
+
+
+def _detect_lan_ip() -> str:
+    """Best-effort detection of the host's primary LAN IPv4 address.
+
+    Uses the standard UDP-socket trick: open a non-blocking connection to a
+    routable but unreachable target and read the local socket name. This
+    yields the address the OS would use for outbound traffic, which is the
+    one a phone on the same LAN should target.
+    """
+    candidate = ""
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        s.setblocking(False)
+        try:
+            s.connect(("10.255.255.255", 1))
+            candidate = s.getsockname()[0]
+        except OSError:
+            candidate = ""
+    finally:
+        s.close()
+    if candidate and not candidate.startswith("127."):
+        return candidate
+    try:
+        fallback = socket.gethostbyname(socket.gethostname())
     except OSError:
+        return ""
+    if fallback and not fallback.startswith("127."):
+        return fallback
+    return ""
+
+
+def _network_viewer_url(host: str, port: int, *, focus: str | None = None, read: bool = False) -> str | None:
+    if host not in {"0.0.0.0", "::", ""}:
         return None
-    if not candidate or candidate.startswith("127."):
+    candidate = _detect_lan_ip()
+    if not candidate:
         return None
     return build_viewer_url(candidate, port, focus=focus, read=read)
 
@@ -2422,13 +3727,18 @@ def render_start_status(
     network_url: str | None = None,
     bind_host: str = "localhost",
     auto_refresh_interval_seconds: int = 15,
+    lan_mode: bool = False,
+    lan_token: str | None = None,
+    lan_url: str | None = None,
+    qr_lines: list[str] | None = None,
 ) -> str:
+    mode_label = "LAN read-only (token required)" if lan_mode else "read-only"
     lines = [
         "Logics viewer running:",
         f"Local: {url}",
         "",
         f"Repo: {repo_root.name}",
-        "Mode: read-only",
+        f"Mode: {mode_label}",
         f"Bind: {bind_host}",
         f"Auto refresh: {auto_refresh_interval_seconds}s",
     ]
@@ -2436,6 +3746,16 @@ def render_start_status(
         lines.insert(2, f"Network: {network_url}")
     if focus:
         lines.append(f"Focus: {focus}")
+    if lan_mode:
+        lines.append("")
+        lines.append("LAN exposure is active. Mutating endpoints are refused; non-loopback clients must present the session token below.")
+        if lan_url:
+            lines.append(f"Share URL: {lan_url}")
+        if lan_token:
+            lines.append(f"Token: {lan_token}")
+        if qr_lines:
+            lines.append("")
+            lines.extend(qr_lines)
     return "\n".join(lines)
 
 
@@ -2443,10 +3763,15 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="logics-manager view", description="Start the local read-only Logics browser viewer.")
     parser.add_argument("--host", default="127.0.0.1", help="Bind host. Defaults to 127.0.0.1.")
     parser.add_argument("--port", type=int, default=8765, help="Bind port. Use 0 to select an available port.")
+    parser.add_argument(
+        "--lan",
+        action="store_true",
+        help="Expose the viewer on the local network (0.0.0.0). Enforces read-only access and requires a per-session bearer token for non-loopback requests.",
+    )
     parser.add_argument(
         "--refresh-interval",
         type=int,
-        default=15,
+        default=None,
         help="Automatic refresh interval in seconds. Defaults to 15; positive intervals are allowed.",
     )
     parser.add_argument("--focus", help="Open the viewer focused on a workflow ref or repo-relative Logics Markdown path.")
@@ -2459,7 +3784,9 @@ def build_parser() -> argparse.ArgumentParser:
 def main(argv: list[str]) -> int:
     args = build_parser().parse_args(argv)
     repo_root = find_repo_root(Path.cwd())
-    if args.refresh_interval <= 0:
+    refresh_interval_forced = args.refresh_interval is not None
+    refresh_interval = args.refresh_interval if args.refresh_interval is not None else 15
+    if refresh_interval <= 0:
         raise SystemExit("--refresh-interval must be a positive number of seconds.")
     if args.read and not args.focus:
         raise SystemExit("--read requires --focus.")
@@ -2467,15 +3794,24 @@ def main(argv: list[str]) -> int:
         focus = normalize_viewer_focus_target(repo_root, args.focus) if args.focus else None
     except ValueError as exc:
         raise SystemExit(str(exc)) from exc
+    bind_host = "0.0.0.0" if args.lan and args.host == "127.0.0.1" else args.host
     server = create_viewer_server(
         repo_root,
-        host=args.host,
+        host=bind_host,
         port=args.port,
-        auto_refresh_interval_seconds=args.refresh_interval,
+        auto_refresh_interval_seconds=refresh_interval,
+        auto_refresh_interval_forced=refresh_interval_forced,
+        lan_mode=bool(args.lan),
     )
     host, port = server.server_address[:2]
     url = build_viewer_url(str(host), int(port), focus=focus, read=bool(args.read))
     network_url = _network_viewer_url(str(host), int(port), focus=focus, read=bool(args.read))
+    lan_share_url = ""
+    qr_lines: list[str] = []
+    if args.lan and server.lan_token:
+        base_for_lan = network_url or url
+        lan_share_url = _append_lan_token(base_for_lan, server.lan_token)
+        qr_lines = _render_qr_lines(lan_share_url)
     print(
         render_start_status(
             url,
@@ -2483,7 +3819,11 @@ def main(argv: list[str]) -> int:
             focus=focus,
             network_url=network_url,
             bind_host=str(host),
-            auto_refresh_interval_seconds=args.refresh_interval,
+            auto_refresh_interval_seconds=refresh_interval,
+            lan_mode=bool(args.lan),
+            lan_token=server.lan_token if args.lan else None,
+            lan_url=lan_share_url or None,
+            qr_lines=qr_lines or None,
         ),
         flush=True,
     )