arkaos 3.66.0 → 3.67.0

package/VERSION

@@ -1 +1 @@
-3.66.0
+3.67.0

package/core/terminal/__init__.py

@@ -0,0 +1,27 @@
+"""ArkaOS terminal — PTY session manager + audit log.
+
+PR99a v3.67.0 — replaces the v3.51.0 allowlist runner with a real
+multi-session PTY that lets the operator run claude, codex, anything,
+streamed bidirectionally over a WebSocket and rendered in xterm.js.
+
+Security: localhost-only binding (inherits from dashboard-api), origin
+pinning + per-process bearer token, idle-kill 30 min, hard cap on
+concurrent sessions, metadata-only audit log (no input capture).
+"""
+
+from core.terminal.session import (
+    TerminalSession,
+    TerminalSessionManager,
+    SessionCapacityError,
+)
+from core.terminal.audit import log_end, log_start
+from core.terminal.token import current_token
+
+__all__ = [
+    "TerminalSession",
+    "TerminalSessionManager",
+    "SessionCapacityError",
+    "log_start",
+    "log_end",
+    "current_token",
+]

package/core/terminal/audit.py

@@ -0,0 +1,58 @@
+"""Metadata-only audit log for terminal sessions.
+
+PR99a v3.67.0 — writes start/end events as JSONL to
+``~/.arkaos/terminal-audit.jsonl``. Deliberately captures NO input or
+output payload — only session lifecycle metadata — because terminal
+input frequently carries secrets (PATs, tokens, passwords) and
+operators paste them in.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+_LOCK = threading.Lock()
+
+
+def _audit_path() -> Path:
+    base = Path(os.environ.get("ARKAOS_HOME", Path.home() / ".arkaos"))
+    base.mkdir(parents=True, exist_ok=True)
+    return base / "terminal-audit.jsonl"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _write(event: dict) -> None:
+    path = _audit_path()
+    line = json.dumps(event, ensure_ascii=False)
+    with _LOCK:
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(line + "\n")
+
+
+def log_start(session_id: str, shell: str, cwd: str) -> None:
+    """Record that a PTY session has been created."""
+    _write({
+        "event": "start",
+        "session_id": session_id,
+        "shell": shell,
+        "cwd": cwd,
+        "ts": _now_iso(),
+    })
+
+
+def log_end(session_id: str, exit_code: int | None, reason: str = "closed") -> None:
+    """Record that a PTY session has terminated."""
+    _write({
+        "event": "end",
+        "session_id": session_id,
+        "exit_code": exit_code,
+        "reason": reason,
+        "ts": _now_iso(),
+    })

package/core/terminal/session.py

@@ -0,0 +1,288 @@
+"""PTY session + manager for the dashboard terminal.
+
+PR99a v3.67.0 — spawns a forked shell on a pseudo-terminal, exposes
+bidirectional read/write/resize over a file descriptor, and offers a
+manager that caps concurrent sessions and reaps dead/idle ones.
+
+Design notes
+------------
+* ``pty.fork`` is used (not ``pty.openpty`` + ``Popen``) because we want
+  the child to be a session leader with a controlling tty — that is what
+  makes the shell behave interactively (job control, signals, prompts,
+  ANSI rendering).
+* The master fd is set non-blocking so the asyncio loop in the
+  dashboard-api can ``add_reader`` it and pump bytes to the WebSocket
+  without a thread pool.
+* The manager keeps sessions in a dict keyed by url-safe id; nothing
+  here imports FastAPI so the unit tests can run without spinning up an
+  HTTP app.
+"""
+
+from __future__ import annotations
+
+import errno
+import fcntl
+import os
+import pty
+import secrets
+import signal
+import struct
+import termios
+import time
+from typing import Any, Optional
+
+from core.terminal import audit
+
+
+class SessionCapacityError(RuntimeError):
+    """Raised when ``create()`` is called past the configured cap."""
+
+
+def _default_shell() -> str:
+    return os.environ.get("SHELL") or "/bin/zsh"
+
+
+def _default_cwd() -> str:
+    return os.path.expanduser("~")
+
+
+class TerminalSession:
+    """A single forked PTY + the bookkeeping needed to drive it.
+
+    Public attributes are read-only from the outside; mutate state via
+    the methods so the manager can keep its invariants.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        shell: str,
+        cwd: str,
+        cols: int = 120,
+        rows: int = 32,
+    ) -> None:
+        self.session_id = session_id
+        self.shell = shell
+        self.cwd = cwd
+        self.created_at = time.time()
+        self.last_activity = time.monotonic()
+        self.exit_code: Optional[int] = None
+        self.title: str = ""
+        self._closed = False
+        self.pid, self.master_fd = pty.fork()
+        if self.pid == 0:
+            self._child_exec(shell, cwd)
+        os.set_blocking(self.master_fd, False)
+        self.resize(cols, rows)
+
+    @staticmethod
+    def _child_exec(shell: str, cwd: str) -> None:
+        try:
+            os.chdir(cwd)
+        except OSError:
+            pass
+        env = os.environ.copy()
+        env["TERM"] = env.get("TERM", "xterm-256color")
+        env["COLORTERM"] = env.get("COLORTERM", "truecolor")
+        try:
+            os.execvpe(shell, [shell, "-l"], env)
+        except OSError:
+            os._exit(127)
+
+    def read(self, max_bytes: int = 4096) -> bytes:
+        """Non-blocking read. Returns ``b""`` when there is nothing yet."""
+        if self._closed or self.master_fd < 0:
+            return b""
+        try:
+            data = os.read(self.master_fd, max_bytes)
+        except BlockingIOError:
+            return b""
+        except OSError as exc:
+            if exc.errno in (errno.EIO, errno.EBADF):
+                self._closed = True
+                return b""
+            raise
+        if data:
+            self.last_activity = time.monotonic()
+        return data
+
+    def write(self, data: bytes) -> int:
+        if self._closed or self.master_fd < 0 or not data:
+            return 0
+        try:
+            n = os.write(self.master_fd, data)
+        except OSError:
+            self._closed = True
+            return 0
+        self.last_activity = time.monotonic()
+        return n
+
+    def resize(self, cols: int, rows: int) -> None:
+        if self._closed or self.master_fd < 0:
+            return
+        cols = max(1, int(cols))
+        rows = max(1, int(rows))
+        try:
+            fcntl.ioctl(
+                self.master_fd,
+                termios.TIOCSWINSZ,
+                struct.pack("HHHH", rows, cols, 0, 0),
+            )
+        except OSError:
+            pass
+
+    def is_alive(self) -> bool:
+        if self._closed:
+            return False
+        try:
+            wpid, status = os.waitpid(self.pid, os.WNOHANG)
+        except ChildProcessError:
+            self._closed = True
+            return False
+        except OSError:
+            return False
+        if wpid == 0:
+            return True
+        self.exit_code = os.waitstatus_to_exitcode(status)
+        self._closed = True
+        return False
+
+    def kill(self, sig: int = signal.SIGTERM) -> None:
+        if self._closed:
+            return
+        try:
+            os.kill(self.pid, sig)
+        except (ProcessLookupError, PermissionError):
+            pass
+        for _ in range(10):
+            if not self.is_alive():
+                break
+            time.sleep(0.05)
+        if self.is_alive():
+            try:
+                os.kill(self.pid, signal.SIGKILL)
+            except (ProcessLookupError, PermissionError):
+                pass
+        self._close_fd()
+
+    def _close_fd(self) -> None:
+        if self.master_fd >= 0:
+            try:
+                os.close(self.master_fd)
+            except OSError:
+                pass
+            self.master_fd = -1
+        self._closed = True
+
+    def to_dict(self) -> dict[str, Any]:
+        idle_s = max(0.0, time.monotonic() - self.last_activity)
+        return {
+            "session_id": self.session_id,
+            "shell": self.shell,
+            "cwd": self.cwd,
+            "title": self.title or self.session_id,
+            "created_at": self.created_at,
+            "idle_seconds": round(idle_s, 1),
+            "alive": self.is_alive(),
+            "exit_code": self.exit_code,
+        }
+
+
+class TerminalSessionManager:
+    """Owns the dict of live sessions and enforces caps + idle-kill."""
+
+    DEFAULT_MAX = 8
+    DEFAULT_IDLE_S = 1800  # 30 minutes
+
+    def __init__(
+        self,
+        max_sessions: Optional[int] = None,
+        idle_timeout_s: Optional[int] = None,
+    ) -> None:
+        max_default = self.DEFAULT_MAX if max_sessions is None else max_sessions
+        idle_default = self.DEFAULT_IDLE_S if idle_timeout_s is None else idle_timeout_s
+        self.max_sessions = int(
+            os.environ.get("ARKAOS_TERMINAL_MAX_SESSIONS", max_default)
+        )
+        self.idle_timeout_s = int(
+            os.environ.get("ARKAOS_TERMINAL_IDLE_S", idle_default)
+        )
+        self._sessions: dict[str, TerminalSession] = {}
+
+    def create(
+        self,
+        shell: Optional[str] = None,
+        cwd: Optional[str] = None,
+        cols: int = 120,
+        rows: int = 32,
+    ) -> TerminalSession:
+        self.reap_dead()
+        if len(self._sessions) >= self.max_sessions:
+            raise SessionCapacityError(
+                f"max sessions ({self.max_sessions}) reached"
+            )
+        sid = secrets.token_urlsafe(8)
+        chosen_shell = shell or _default_shell()
+        chosen_cwd = cwd or _default_cwd()
+        session = TerminalSession(
+            session_id=sid,
+            shell=chosen_shell,
+            cwd=chosen_cwd,
+            cols=cols,
+            rows=rows,
+        )
+        self._sessions[sid] = session
+        audit.log_start(sid, chosen_shell, chosen_cwd)
+        return session
+
+    def get(self, session_id: str) -> Optional[TerminalSession]:
+        return self._sessions.get(session_id)
+
+    def list_all(self) -> list[dict]:
+        self.reap_dead()
+        return [s.to_dict() for s in self._sessions.values()]
+
+    def count(self) -> int:
+        return len(self._sessions)
+
+    def close(self, session_id: str, reason: str = "closed") -> bool:
+        session = self._sessions.pop(session_id, None)
+        if session is None:
+            return False
+        session.kill()
+        audit.log_end(session_id, session.exit_code, reason=reason)
+        return True
+
+    def reap_dead(self) -> int:
+        dead = [sid for sid, s in self._sessions.items() if not s.is_alive()]
+        for sid in dead:
+            session = self._sessions.pop(sid)
+            session._close_fd()
+            audit.log_end(sid, session.exit_code, reason="exited")
+        return len(dead)
+
+    def reap_idle(self) -> int:
+        now = time.monotonic()
+        timeout = self.idle_timeout_s
+        idle = [
+            sid for sid, s in self._sessions.items()
+            if now - s.last_activity > timeout
+        ]
+        for sid in idle:
+            self.close(sid, reason="idle-timeout")
+        return len(idle)
+
+    def shutdown(self) -> None:
+        for sid in list(self._sessions.keys()):
+            self.close(sid, reason="shutdown")
+
+
+_default_manager: Optional[TerminalSessionManager] = None
+
+
+def default_manager() -> TerminalSessionManager:
+    """Lazy global manager — one per process."""
+    global _default_manager
+    if _default_manager is None:
+        _default_manager = TerminalSessionManager()
+    return _default_manager

package/core/terminal/token.py

@@ -0,0 +1,38 @@
+"""Per-process bearer token for WebSocket terminal handshake.
+
+PR99a v3.67.0 — a random url-safe 32-byte token generated once at
+process startup. The frontend fetches it from `/api/terminal/token`
+(CORS-restricted to localhost) and includes it as a query parameter
+on the WebSocket upgrade. Token rotates whenever the API restarts.
+
+Rationale: CORS already blocks cross-origin XHR, but a malicious page
+on `http://localhost:9999` could open a WebSocket without a preflight,
+so we add a second authentication factor that only the dashboard
+(running on localhost too) can read.
+"""
+
+from __future__ import annotations
+
+import hmac
+import secrets
+
+_TOKEN: str = secrets.token_urlsafe(32)
+
+
+def current_token() -> str:
+    """Return the per-process terminal bearer token."""
+    return _TOKEN
+
+
+def verify(candidate: str) -> bool:
+    """Constant-time compare a candidate against the current token."""
+    if not isinstance(candidate, str) or not candidate:
+        return False
+    return hmac.compare_digest(candidate, _TOKEN)
+
+
+def rotate() -> str:
+    """Rotate the token (used by tests; never called in production)."""
+    global _TOKEN
+    _TOKEN = secrets.token_urlsafe(32)
+    return _TOKEN

package/dashboard/app/pages/agents/index.vue

@@ -79,6 +79,12 @@ const tierFilter = ref(String(route.query.tier ?? 'all'))
 const page = ref(1)
 const pageSize = 15
 
+// PR86a + PR92b — favorites refs must exist BEFORE the filter watcher
+// below references them (otherwise TDZ blows up the whole page).
+const favs = useFavorites()
+await favs.load()
+const favoritesOnly = ref(route.query.fav === '1')
+
 const departments = computed(() => {
   const depts = new Set(agents.value.map(a => a.department))
   return [
@@ -262,12 +268,6 @@ defineShortcuts({
   enter: () => cursorOpen(),
 })
 
-// PR86a v3.15.0 — favorites.
-// PR92b v3.40.0 — favoritesOnly persists in URL (`?fav=1`).
-const favs = useFavorites()
-await favs.load()
-const favoritesOnly = ref(route.query.fav === '1')
-
 // PR83b v3.4.0 — bulk selection + delete.
 // PR84b v3.8.0 — bulk move department.
 const confirmDialog = useConfirmDialog()