@grifhinz/logics-manager 2.8.1 → 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
@@ -641,10 +644,25 @@ def viewer_project_capabilities(
         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,
@@ -1349,6 +1367,116 @@ def workspace_preview_payload(
     }
 
 
+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 = {
@@ -2311,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,
@@ -2319,6 +2997,7 @@ class LogicsViewerServer(ThreadingHTTPServer):
         *,
         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)
@@ -2327,19 +3006,40 @@ class LogicsViewerServer(ThreadingHTTPServer):
         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)
@@ -2383,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")
@@ -2478,6 +3345,52 @@ class LogicsViewerRequestHandler(BaseHTTPRequestHandler):
             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:
@@ -2494,6 +3407,15 @@ class LogicsViewerRequestHandler(BaseHTTPRequestHandler):
 
     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(
                 {
@@ -2516,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)
@@ -2619,23 +3640,81 @@ def create_viewer_server(
     *,
     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)
 
@@ -2648,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",
     ]
@@ -2662,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)
 
 
@@ -2669,6 +3763,11 @@ 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,
@@ -2695,16 +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=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,
@@ -2713,6 +3820,10 @@ def main(argv: list[str]) -> int:
             network_url=network_url,
             bind_host=str(host),
             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,
     )