arkaos 3.66.1 → 3.68.0

package/VERSION

@@ -1 +1 @@
-3.66.1
+3.68.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/components/Terminal.vue

@@ -0,0 +1,150 @@
+<script setup lang="ts">
+// PR99b v3.68.0 — xterm.js terminal mount.
+//
+// Glues @xterm/xterm to a single PTY session from useTerminalSession.
+// One terminal per component instance; the multi-tab page in PR99c
+// will spawn N of these.
+
+import { Terminal as XTerm } from '@xterm/xterm'
+import { FitAddon } from '@xterm/addon-fit'
+import { WebLinksAddon } from '@xterm/addon-web-links'
+import { SearchAddon } from '@xterm/addon-search'
+import '@xterm/xterm/css/xterm.css'
+
+const container = ref<HTMLDivElement | null>(null)
+const session = useTerminalSession()
+const term = shallowRef<XTerm | null>(null)
+const fit = shallowRef<FitAddon | null>(null)
+const search = shallowRef<SearchAddon | null>(null)
+
+const decoder = new TextDecoder('utf-8', { fatal: false })
+
+const themeArkaOSDark = {
+  background: '#0a0a0f',
+  foreground: '#e6e6f0',
+  cursor: '#7dd3fc',
+  cursorAccent: '#0a0a0f',
+  selectionBackground: '#1e3a5f',
+  black: '#0a0a0f',
+  red: '#f87171',
+  green: '#86efac',
+  yellow: '#fde68a',
+  blue: '#7dd3fc',
+  magenta: '#f0abfc',
+  cyan: '#67e8f9',
+  white: '#e6e6f0',
+  brightBlack: '#3f3f46',
+  brightRed: '#fca5a5',
+  brightGreen: '#bbf7d0',
+  brightYellow: '#fef3c7',
+  brightBlue: '#bae6fd',
+  brightMagenta: '#f5d0fe',
+  brightCyan: '#a5f3fc',
+  brightWhite: '#fafafa',
+}
+
+let unsubscribeOutput: (() => void) | null = null
+let resizeObserver: ResizeObserver | null = null
+
+onMounted(async () => {
+  if (!container.value) return
+
+  const t = new XTerm({
+    cursorBlink: true,
+    fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+    fontSize: 13,
+    lineHeight: 1.2,
+    scrollback: 5000,
+    theme: themeArkaOSDark,
+    allowProposedApi: true,
+  })
+  const fitAddon = new FitAddon()
+  const searchAddon = new SearchAddon()
+  t.loadAddon(fitAddon)
+  t.loadAddon(new WebLinksAddon())
+  t.loadAddon(searchAddon)
+  t.open(container.value)
+  fitAddon.fit()
+
+  term.value = t
+  fit.value = fitAddon
+  search.value = searchAddon
+
+  await session.open()
+
+  unsubscribeOutput = session.onOutput((chunk) => {
+    const text = decoder.decode(chunk, { stream: true })
+    t.write(text)
+  })
+
+  t.onData((data) => {
+    session.sendInput(data)
+  })
+
+  // Initial size sync once the WS is open.
+  watch(session.status, (s) => {
+    if (s === 'open') {
+      const { cols, rows } = t
+      session.sendResize(cols, rows)
+    }
+  }, { immediate: true })
+
+  resizeObserver = new ResizeObserver(() => {
+    try {
+      fitAddon.fit()
+      session.sendResize(t.cols, t.rows)
+    } catch (_e) {
+      // dom may have unmounted
+    }
+  })
+  resizeObserver.observe(container.value)
+})
+
+onBeforeUnmount(async () => {
+  unsubscribeOutput?.()
+  resizeObserver?.disconnect()
+  await session.close()
+  term.value?.dispose()
+})
+
+defineExpose({
+  status: session.status,
+  error: session.error,
+  meta: session.meta,
+})
+</script>
+
+<template>
+  <div class="relative h-full w-full bg-[#0a0a0f] rounded-lg overflow-hidden border border-default">
+    <div
+      v-if="session.status.value === 'connecting'"
+      class="absolute inset-0 z-10 grid place-items-center text-muted text-sm bg-[#0a0a0f]/80 backdrop-blur"
+    >
+      <div class="flex items-center gap-2">
+        <UIcon name="i-lucide-loader" class="animate-spin size-4" />
+        Spawning PTY…
+      </div>
+    </div>
+    <div
+      v-else-if="session.status.value === 'error' || session.status.value === 'closed'"
+      class="absolute top-2 right-2 z-10 text-xs rounded-md bg-elevated/90 px-2 py-1 border border-default"
+    >
+      <span v-if="session.status.value === 'error'" class="text-red-400">
+        {{ session.error.value || 'error' }}
+      </span>
+      <span v-else class="text-muted">closed</span>
+    </div>
+    <div ref="container" class="absolute inset-0 p-2" />
+  </div>
+</template>
+
+<style scoped>
+:deep(.xterm) {
+  height: 100%;
+  width: 100%;
+  padding: 4px;
+}
+:deep(.xterm-viewport) {
+  background-color: transparent !important;
+}
+</style>

package/dashboard/app/composables/useTerminalSession.ts

@@ -0,0 +1,138 @@
+// PR99b v3.68.0 — single PTY session lifecycle.
+//
+// Encapsulates the REST + WebSocket handshake against /api/terminal/*.
+// The composable owns no DOM and no xterm instance — it just produces
+// the bytes-in/bytes-out duplex. The Terminal.vue component glues this
+// to an xterm.js canvas.
+
+export interface TerminalSessionMeta {
+  session_id: string
+  shell: string
+  cwd: string
+  token: string
+  ws_path: string
+  max_sessions: number
+  active_count: number
+}
+
+export interface TerminalSessionHandle {
+  meta: Ref<TerminalSessionMeta | null>
+  status: Ref<'idle' | 'connecting' | 'open' | 'closed' | 'error'>
+  error: Ref<string | null>
+  open: () => Promise<void>
+  sendInput: (data: string) => void
+  sendResize: (cols: number, rows: number) => void
+  close: () => Promise<void>
+  onOutput: (cb: (chunk: Uint8Array) => void) => () => void
+}
+
+export function useTerminalSession(): TerminalSessionHandle {
+  const { apiBase } = useApi()
+  const meta = ref<TerminalSessionMeta | null>(null)
+  const status = ref<'idle' | 'connecting' | 'open' | 'closed' | 'error'>('idle')
+  const error = ref<string | null>(null)
+
+  let ws: WebSocket | null = null
+  const listeners: Array<(chunk: Uint8Array) => void> = []
+
+  function wsUrl(path: string, token: string): string {
+    const base = apiBase.replace(/^http/, 'ws')
+    return `${base}${path}?token=${encodeURIComponent(token)}`
+  }
+
+  async function createSession(): Promise<TerminalSessionMeta> {
+    const r = await fetch(`${apiBase}/api/terminal/sessions`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ cols: 120, rows: 32 }),
+    })
+    if (!r.ok) {
+      const body = await r.text()
+      throw new Error(`create session failed: ${r.status} ${body}`)
+    }
+    return await r.json()
+  }
+
+  async function open() {
+    if (status.value === 'open' || status.value === 'connecting') return
+    status.value = 'connecting'
+    error.value = null
+    try {
+      const m = await createSession()
+      meta.value = m
+      ws = new WebSocket(wsUrl(m.ws_path, m.token))
+      ws.binaryType = 'arraybuffer'
+      ws.onopen = () => {
+        status.value = 'open'
+      }
+      ws.onmessage = (ev) => {
+        if (ev.data instanceof ArrayBuffer) {
+          const chunk = new Uint8Array(ev.data)
+          for (const cb of listeners) cb(chunk)
+        } else if (typeof ev.data === 'string') {
+          const enc = new TextEncoder().encode(ev.data)
+          for (const cb of listeners) cb(enc)
+        }
+      }
+      ws.onerror = () => {
+        status.value = 'error'
+        error.value = 'websocket error'
+      }
+      ws.onclose = (ev) => {
+        status.value = 'closed'
+        if (ev.code !== 1000 && ev.code !== 1005) {
+          error.value = `closed (${ev.code}) ${ev.reason || ''}`.trim()
+        }
+      }
+    } catch (e) {
+      status.value = 'error'
+      error.value = e instanceof Error ? e.message : String(e)
+    }
+  }
+
+  function sendInput(data: string) {
+    if (!ws || ws.readyState !== WebSocket.OPEN) return
+    ws.send(JSON.stringify({ type: 'input', data }))
+  }
+
+  function sendResize(cols: number, rows: number) {
+    if (!ws || ws.readyState !== WebSocket.OPEN) return
+    ws.send(JSON.stringify({ type: 'resize', cols, rows }))
+  }
+
+  async function close() {
+    try {
+      ws?.close(1000, 'client close')
+    } catch (_e) {
+      // ignore
+    }
+    const id = meta.value?.session_id
+    if (id) {
+      try {
+        await fetch(`${apiBase}/api/terminal/sessions/${id}`, { method: 'DELETE' })
+      } catch (_e) {
+        // ignore — best-effort cleanup; backend reaper will catch it
+      }
+    }
+    status.value = 'closed'
+  }
+
+  function onOutput(cb: (chunk: Uint8Array) => void) {
+    listeners.push(cb)
+    return () => {
+      const idx = listeners.indexOf(cb)
+      if (idx >= 0) listeners.splice(idx, 1)
+    }
+  }
+
+  return {
+    meta,
+    status,
+    error,
+    open,
+    sendInput,
+    sendResize,
+    close,
+    onOutput,
+  }
+}

package/dashboard/app/pages/terminal.vue

@@ -1,278 +1,51 @@
 <script setup lang="ts">
-// PR95a v3.51.0 — Dashboard terminal (allowlist mode).
+// PR99b v3.68.0 — Real-shell terminal (single session).
 //
-// Operator picks one of the allowlisted commands; backend runs it via
-// subprocess.run (no shell). Output streams into the history block.
-//
-// Note: vue-termui is for building Vue TUI apps that RUN in a terminal,
-// not for embedding an arbitrary shell in a browser. The dashboard
-// instead ships a controlled command runner with allowlist + capped
-// output. xterm.js-style PTY can be a later upgrade if needed.
-
-interface CommandArg {
-  name: string
-  label: string
-  choices: string[]
-  default: string
-}
-
-interface CommandEntry {
-  id: string
-  label: string
-  description: string
-  args?: CommandArg[]
-}
-
-interface ExecResult {
-  stdout: string
-  stderr: string
-  exit_code: number
-  duration_ms: number
-  command: string
-}
-
-interface HistoryEntry {
-  id: string
-  label: string
-  result: ExecResult
-  ts: string
-}
-
-const { fetchApi, apiBase } = useApi()
-const toast = useToast()
-
-const { data: cmdData, status } = await fetchApi<{ commands: CommandEntry[] }>(
-  '/api/terminal/commands',
-)
-const commands = computed<CommandEntry[]>(() => cmdData.value?.commands ?? [])
-
-const running = ref<string | null>(null)
-const history = ref<HistoryEntry[]>([])
+// Replaces the v3.51.0 allowlist UI. Each visit spawns a fresh PTY
+// session on the backend, wired to xterm.js. Multi-session tabs and
+// history land in PR99c. The old allowlist endpoints stay in parallel
+// until PR99d, but the UI is gone as of this release.
 
-// PR96b v3.56.0 — per-command arg state. Keyed by command id, holds
-// the operator's current selection for each arg.
-const argState = reactive<Record<string, Record<string, string>>>({})
+definePageMeta({ layout: 'default' })
 
-function ensureArgState(cmd: CommandEntry) {
-  if (!cmd.args || cmd.args.length === 0) return
-  if (!argState[cmd.id]) argState[cmd.id] = {}
-  for (const arg of cmd.args) {
-    if (argState[cmd.id][arg.name] === undefined) {
-      argState[cmd.id][arg.name] = arg.default
-    }
-  }
-}
-
-async function run(cmd: CommandEntry) {
-  running.value = cmd.id
-  ensureArgState(cmd)
-  try {
-    const res = await $fetch<ExecResult & { error?: string }>(
-      `${apiBase}/api/terminal/exec`,
-      {
-        method: 'POST',
-        body: {
-          command_id: cmd.id,
-          args: cmd.args ? argState[cmd.id] : undefined,
-        },
-      },
-    )
-    if (res.error) throw new Error(res.error)
-    history.value = [
-      {
-        id: cmd.id,
-        label: cmd.label,
-        result: res,
-        ts: new Date().toISOString(),
-      },
-      ...history.value,
-    ].slice(0, 20)
-    if (res.exit_code === 0) {
-      toast.add({
-        title: `${cmd.label} · ok`,
-        description: `${res.duration_ms}ms`,
-        color: 'success',
-        icon: 'i-lucide-check',
-      })
-    } else {
-      toast.add({
-        title: `${cmd.label} · exit ${res.exit_code}`,
-        description: `${res.duration_ms}ms · ${res.stderr.slice(0, 80) || 'no stderr'}`,
-        color: 'warning',
-      })
-    }
-  } catch (err) {
-    toast.add({
-      title: 'Run failed',
-      description: err instanceof Error ? err.message : 'unknown error',
-      color: 'error',
-    })
-  } finally {
-    running.value = null
-  }
-}
-
-function copyOutput(entry: HistoryEntry) {
-  if (typeof navigator === 'undefined' || !navigator.clipboard) return
-  const body = entry.result.stdout || entry.result.stderr
-  void navigator.clipboard.writeText(body)
-  toast.add({ title: 'Copied to clipboard', color: 'success', icon: 'i-lucide-clipboard-check' })
-}
-
-function clearHistory() {
-  history.value = []
-}
-
-function relative(iso: string): string {
-  const ts = Date.parse(iso)
-  if (Number.isNaN(ts)) return iso
-  const diff = Date.now() - ts
-  const s = Math.floor(diff / 1000)
-  if (s < 60) return `${s}s ago`
-  const m = Math.floor(s / 60)
-  if (m < 60) return `${m}m ago`
-  return `${Math.floor(m / 60)}h ago`
-}
+const terminalRef = ref<InstanceType<typeof import('~/components/Terminal.vue').default> | null>(null)
+const expanded = ref(false)
 </script>
 
 <template>
-  <UDashboardPanel id="terminal">
-    <template #header>
-      <UDashboardNavbar title="Terminal">
-        <template #leading>
-          <UDashboardSidebarCollapse />
-        </template>
-        <template #trailing>
-          <UBadge label="Allowlist mode" variant="subtle" color="primary" size="sm" />
-        </template>
-      </UDashboardNavbar>
-    </template>
-
-    <template #body>
-      <DashboardState
-        :status="status"
-        :empty="commands.length === 0"
-        empty-title="No allowlisted commands"
-        empty-description="The backend exposes no terminal commands. Add to TERMINAL_ALLOWLIST."
-        empty-icon="i-lucide-terminal"
-      >
-        <div class="space-y-5 max-w-4xl">
-          <UCard>
-            <template #header>
-              <div>
-                <h3 class="text-lg font-bold">Commands</h3>
-                <p class="text-xs text-muted mt-0.5">
-                  Server-enforced allowlist. Each command runs via
-                  <code class="font-mono">subprocess.run</code> with explicit argv —
-                  no shell, no globbing, no pipes. Cap: 15s timeout, 20K chars per stream.
-                </p>
-              </div>
-            </template>
-            <div class="grid grid-cols-1 md:grid-cols-2 gap-3">
-              <div
-                v-for="cmd in commands"
-                :key="cmd.id"
-                class="rounded-lg border border-default p-3 space-y-2"
-              >
-                <div>
-                  <p class="text-sm font-semibold">{{ cmd.label }}</p>
-                  <p class="text-xs text-muted">{{ cmd.description }}</p>
-                </div>
-                <!-- PR96b v3.56.0 — arg pickers for parameterised commands -->
-                <div v-if="cmd.args && cmd.args.length > 0" class="grid grid-cols-2 gap-2">
-                  <UFormField
-                    v-for="arg in cmd.args"
-                    :key="arg.name"
-                    :label="arg.label"
-                    size="xs"
-                  >
-                    <USelect
-                      :model-value="(argState[cmd.id] || {})[arg.name] || arg.default"
-                      :items="arg.choices.map((c) => ({ label: c, value: c }))"
-                      size="xs"
-                      class="w-full"
-                      @update:model-value="(v) => {
-                        ensureArgState(cmd)
-                        argState[cmd.id][arg.name] = String(v)
-                      }"
-                    />
-                  </UFormField>
-                </div>
-                <UButton
-                  label="Run"
-                  icon="i-lucide-play"
-                  color="primary"
-                  size="sm"
-                  block
-                  :loading="running === cmd.id"
-                  :disabled="running !== null && running !== cmd.id"
-                  @click="run(cmd)"
-                />
-              </div>
-            </div>
-          </UCard>
-
-          <UCard v-if="history.length > 0">
-            <template #header>
-              <div class="flex items-center justify-between gap-3">
-                <div>
-                  <h3 class="text-lg font-bold">Recent runs</h3>
-                  <p class="text-xs text-muted mt-0.5">
-                    Last {{ history.length }} commands · most recent first
-                  </p>
-                </div>
-                <UButton label="Clear" variant="ghost" size="xs" @click="clearHistory" />
-              </div>
-            </template>
-            <ul class="space-y-4">
-              <li
-                v-for="entry in history"
-                :key="`${entry.ts}-${entry.id}`"
-                class="rounded-lg border border-default overflow-hidden"
-              >
-                <div class="px-3 py-2 bg-elevated/30 flex items-center justify-between gap-3 text-xs">
-                  <div class="min-w-0 flex items-center gap-2">
-                    <UBadge
-                      :label="entry.result.exit_code === 0 ? 'ok' : `exit ${entry.result.exit_code}`"
-                      :color="entry.result.exit_code === 0 ? 'success' : 'warning'"
-                      variant="subtle"
-                      size="xs"
-                    />
-                    <span class="font-mono truncate">{{ entry.result.command }}</span>
-                  </div>
-                  <div class="flex items-center gap-2 shrink-0">
-                    <span class="text-muted font-mono">{{ entry.result.duration_ms }}ms</span>
-                    <span class="text-muted">{{ relative(entry.ts) }}</span>
-                    <UButton
-                      icon="i-lucide-clipboard-copy"
-                      variant="ghost"
-                      size="xs"
-                      aria-label="Copy output"
-                      @click="copyOutput(entry)"
-                    />
-                  </div>
-                </div>
-                <pre
-                  v-if="entry.result.stdout"
-                  class="p-3 text-xs font-mono whitespace-pre overflow-x-auto"
-                >{{ entry.result.stdout }}</pre>
-                <pre
-                  v-if="entry.result.stderr"
-                  class="p-3 text-xs font-mono whitespace-pre overflow-x-auto text-rose-500 border-t border-default"
-                >{{ entry.result.stderr }}</pre>
-              </li>
-            </ul>
-          </UCard>
-
-          <p class="text-xs text-muted">
-            Want a different command? Add it to
-            <code class="font-mono">TERMINAL_ALLOWLIST</code> in
-            <code class="font-mono">scripts/dashboard-api.py</code> and
-            restart the backend. Arbitrary shell execution from the
-            dashboard is intentionally not supported.
-          </p>
-        </div>
-      </DashboardState>
-    </template>
-  </UDashboardPanel>
+  <div class="flex flex-col gap-3 h-full">
+    <header class="flex items-center justify-between">
+      <div>
+        <h1 class="text-2xl font-semibold">Terminal</h1>
+        <p class="text-sm text-muted">
+          Real shell, PTY-backed. Runs the same commands as your local zsh —
+          claude, codex, git, anything. Session ends when you leave this page.
+        </p>
+      </div>
+      <div class="flex items-center gap-2">
+        <UBadge color="warning" variant="soft" size="sm">
+          <UIcon name="i-lucide-shield" class="size-3 mr-1" />
+          localhost only
+        </UBadge>
+        <UButton
+          size="xs"
+          variant="ghost"
+          :icon="expanded ? 'i-lucide-minimize-2' : 'i-lucide-maximize-2'"
+          @click="expanded = !expanded"
+        >
+          {{ expanded ? 'Restore' : 'Expand' }}
+        </UButton>
+      </div>
+    </header>
+
+    <Terminal
+      ref="terminalRef"
+      :class="expanded ? 'fixed inset-4 z-40' : 'flex-1 min-h-[520px]'"
+    />
+
+    <footer class="text-xs text-muted">
+      Multi-session tabs, command history search and theme picker arrive in
+      PR99c / PR99d. PR99a (backend PTY) is live.
+    </footer>
+  </div>
 </template>

package/dashboard/package.json

@@ -20,6 +20,10 @@
     "@unovis/vue": "^1.6.4",
     "@vueuse/core": "^14.2.1",
     "@vueuse/nuxt": "^14.2.1",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-search": "^0.16.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/xterm": "^6.0.0",
     "date-fns": "^4.1.0",
     "marked": "^15.0.0",
     "nuxt": "^4.4.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "3.66.1",
+  "version": "3.68.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "3.66.1"
+version = "3.68.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/dashboard-api.py

@@ -2467,6 +2467,194 @@ def workflow_update_yaml(workflow_id: str, body: dict):
     return {"updated": True, "id": workflow_id, "file": str(target)}
 
 
+# ============================================================================
+# PR99a v3.67.0 — Terminal PTY WebSocket + REST.
+#
+# Replaces the v3.51.0 allowlist runner. Spawns a real PTY per session
+# (`pty.fork` + user's $SHELL), streams bidirectionally over a WS to
+# xterm.js, and exposes thin REST endpoints to list / create / close
+# sessions. Origin pinning + bearer token in handshake. Idle-kill is
+# driven by a 60s background coroutine.
+# ============================================================================
+
+
+import re as _terminal_re
+
+
+def _terminal_origin_ok(origin: str) -> bool:
+    """Allow only http(s)://localhost or 127.0.0.1 (any port)."""
+    if not origin:
+        return False
+    return bool(
+        _terminal_re.match(r"^https?://(localhost|127\.0\.0\.1)(:\d+)?$", origin)
+    )
+
+
+@app.get("/api/terminal/token")
+def terminal_token_endpoint():
+    """Return the per-process bearer token used in WS handshakes.
+
+    The token rotates whenever the API restarts. CORS already pins
+    origins to localhost; this is the second factor that protects
+    against a malicious page on another localhost port opening the WS
+    without a CORS preflight.
+    """
+    from core.terminal import token as _token_mod
+    return {"token": _token_mod.current_token()}
+
+
+@app.get("/api/terminal/sessions")
+def terminal_sessions_list():
+    from core.terminal.session import default_manager
+    mgr = default_manager()
+    return {
+        "sessions": mgr.list_all(),
+        "max_sessions": mgr.max_sessions,
+        "idle_timeout_seconds": mgr.idle_timeout_s,
+    }
+
+
+@app.post("/api/terminal/sessions")
+def terminal_sessions_create(body: dict):
+    from core.terminal.session import default_manager, SessionCapacityError
+    from core.terminal import token as _token_mod
+    body = body if isinstance(body, dict) else {}
+    cwd = body.get("cwd")
+    shell = body.get("shell")
+    cols = int(body.get("cols") or 120)
+    rows = int(body.get("rows") or 32)
+    mgr = default_manager()
+    try:
+        s = mgr.create(shell=shell, cwd=cwd, cols=cols, rows=rows)
+    except SessionCapacityError as exc:
+        from fastapi import HTTPException
+        raise HTTPException(status_code=429, detail=str(exc))
+    return {
+        "session_id": s.session_id,
+        "shell": s.shell,
+        "cwd": s.cwd,
+        "token": _token_mod.current_token(),
+        "ws_path": f"/ws/terminal/{s.session_id}",
+        "max_sessions": mgr.max_sessions,
+        "active_count": mgr.count(),
+    }
+
+
+@app.delete("/api/terminal/sessions/{session_id}")
+def terminal_sessions_delete(session_id: str):
+    from core.terminal.session import default_manager
+    ok = default_manager().close(session_id, reason="manual-close")
+    return {"closed": ok, "session_id": session_id}
+
+
+@app.websocket("/ws/terminal/{session_id}")
+async def ws_terminal(ws: WebSocket, session_id: str, token: str = Query("")):
+    """Bidirectional PTY pump.
+
+    Client → server: either text frames `{"type": "resize", "cols", "rows"}`
+    / `{"type": "input", "data": "..."}` or raw binary frames (input bytes).
+    Server → client: raw binary frames of PTY output.
+
+    Closes with code 4401 on bad token, 4403 on bad origin, 4404 when the
+    session is not found.
+    """
+    origin = ws.headers.get("origin", "")
+    if not _terminal_origin_ok(origin):
+        await ws.close(code=4403, reason="origin not allowed")
+        return
+    from core.terminal import token as _token_mod
+    if not _token_mod.verify(token):
+        await ws.close(code=4401, reason="bad token")
+        return
+    from core.terminal.session import default_manager
+    session = default_manager().get(session_id)
+    if session is None:
+        await ws.close(code=4404, reason="session not found")
+        return
+
+    await ws.accept()
+    loop = asyncio.get_event_loop()
+    output_queue: asyncio.Queue = asyncio.Queue()
+
+    def _on_readable():
+        try:
+            data = session.read(8192)
+        except OSError:
+            data = b""
+        if data:
+            output_queue.put_nowait(data)
+
+    try:
+        loop.add_reader(session.master_fd, _on_readable)
+    except (ValueError, OSError):
+        await ws.close(code=1011, reason="pty unavailable")
+        return
+
+    async def pump_to_client():
+        while True:
+            data = await output_queue.get()
+            try:
+                await ws.send_bytes(data)
+            except Exception:
+                break
+
+    pump_task = asyncio.create_task(pump_to_client())
+
+    try:
+        while True:
+            msg = await ws.receive()
+            mtype = msg.get("type")
+            if mtype == "websocket.disconnect":
+                break
+            text = msg.get("text")
+            data = msg.get("bytes")
+            if text is not None:
+                try:
+                    payload = json.loads(text)
+                except json.JSONDecodeError:
+                    continue
+                if not isinstance(payload, dict):
+                    continue
+                kind = payload.get("type")
+                if kind == "resize":
+                    session.resize(
+                        int(payload.get("cols") or 80),
+                        int(payload.get("rows") or 24),
+                    )
+                elif kind == "input":
+                    session.write(str(payload.get("data") or "").encode("utf-8"))
+            elif data is not None:
+                session.write(data)
+    except WebSocketDisconnect:
+        pass
+    except Exception:
+        pass
+    finally:
+        pump_task.cancel()
+        try:
+            loop.remove_reader(session.master_fd)
+        except (ValueError, OSError):
+            pass
+
+
+@app.on_event("startup")
+async def _terminal_reaper_startup():
+    """Background loop that reaps dead and idle sessions every 60s."""
+    async def _loop():
+        from core.terminal.session import default_manager
+        while True:
+            try:
+                await asyncio.sleep(60)
+                mgr = default_manager()
+                mgr.reap_dead()
+                mgr.reap_idle()
+            except asyncio.CancelledError:
+                break
+            except Exception:
+                continue
+    asyncio.create_task(_loop())
+
+
 def _resolve_workflow_yaml(workflow_id: str):
     """Return the YAML path for a workflow id, or None when missing."""
     try: