@rubytech/create-maxy 1.0.680 → 1.0.682

package/payload/platform/scripts/vnc.sh

@@ -2,19 +2,17 @@
 # VNC + browser lifecycle — single source of truth.
 # Called by systemd ExecStartPre (boot) and lib/vnc.ts ensureVnc() (recovery).
 #
-# Usage: vnc.sh start | stop | start-chrome | start-chrome-native
-#                | start-terminal | start-terminal-native | start-terminal-upgrade
-#                | kill-terminal | status-terminal | status
+# Usage: vnc.sh start | stop | start-chrome | start-chrome-native | status
 #
 # Components:
 #   Xtigervnc :99        — virtual X11 display + VNC server on port 5900
 #   websockify :6080     — WebSocket bridge serving noVNC static files
 #   Chromium :9222       — headed browser with CDP enabled
 #                          (Playwright MCP connects via --cdp-endpoint)
-#   Terminal emulator    — gnome-terminal or xterm, spawned on demand for the
-#                          admin Terminal overlay (Task 627). Isomorphic to the
-#                          Chromium pipeline — same :99 VNC display, same
-#                          /vnc-viewer.html iframe surface.
+#
+# Task 657: the admin Terminal overlay and upgrade modal now use the
+# byte-stream xterm.js surface over /ttyd on maxy-edge, not VNC. This
+# script no longer spawns GUI terminal emulators.
 #
 # Display modes (DISPLAY_MODE env var, set by installer --display flag):
 #   virtual (default) — Chromium runs on :99 (VNC virtual display)
@@ -39,19 +37,13 @@ fi
 MAXY_DIR="${HOME}/${CONFIG_DIR}"
 LOG_DIR="${MAXY_DIR}/logs"
 LOG_FILE="${LOG_DIR}/vnc-boot.log"
-TERMINAL_LOG="${LOG_DIR}/terminal-launch.log"
 
 mkdir -p "$LOG_DIR"
 
 log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> "$LOG_FILE"; }
-tlog() { echo "[$(date '+%Y-%m-%dT%H:%M:%S%z')] [terminal-launch] $*" >> "$TERMINAL_LOG"; }
 
 kill_stale() {
   pkill -f 'chromium.*remote-debugging-port=9222' 2>/dev/null || true
-  # Terminal emulators launched by start-terminal[-native] (Task 627).
-  # Regex is anchored to avoid killing gnome-terminal-server (D-Bus service
-  # always running on GNOME desktops — not ours to manage).
-  kill_terminal_emulators
   pkill -f 'Xtigervnc :99' 2>/dev/null || true
   pkill -f 'websockify.*6080' 2>/dev/null || true
   rm -f /tmp/.X99-lock /tmp/.X11-unix/X99
@@ -174,8 +166,8 @@ start_chrome_on() {
   if wait_for_port 9222; then
     # Log-only observability (Task 632): the display-membership invariant is
     # asserted but does NOT gate success here. Chromium does not D-Bus-delegate
-    # like gnome-terminal does, so the failure mode is not currently reachable
-    # — but making the invariant visible now means future backend swaps (e.g.
+    # its window creation, so the failure mode is not currently reachable — but
+    # making the invariant visible now means future backend swaps (e.g.
     # snap-installed Chromium on Ubuntu with different IPC) surface the drift
     # in vnc-boot.log rather than as a silent-black iframe.
     if check_window_on_display "${target_display}"; then
@@ -193,373 +185,12 @@ start_chrome() {
 }
 
 # ---------------------------------------------------------------------------
-# Terminal emulator lifecycle (Task 627) — isomorphic to Chromium's.
+# Task 657 retired the VNC-as-terminal path (Task 627/643): the header
+# TerminalOverlay and UpdateModal now mount xterm.js against /ttyd on
+# maxy-edge. The GUI-terminal spawn pipeline that lived here is gone.
+# Only the Chromium surface remains for BrowserOverlay.
 # ---------------------------------------------------------------------------
 
-# Resolve the preferred terminal binary + its required flags. Selection depends
-# on the target display because gnome-terminal is a D-Bus launcher that routes
-# through /usr/libexec/gnome-terminal-server — and that server is bound to the
-# operator's login session bus (typically :0 on a GNOME desktop). Calling
-# `DISPLAY=:99 /usr/bin/gnome-terminal` does NOT open a window on :99; the
-# D-Bus request is delegated to the server on :0 and the window appears there
-# instead (Task 632 root cause). xterm is a standalone X client with no IPC
-# layer, so `DISPLAY=:99 xterm` lands on :99 regardless of session state.
-#
-# Selection rule:
-#   target_display == :99 (VNC virtual)   → xterm-first, gnome-terminal fallback
-#   target_display == :0  (native login)  → gnome-terminal-first, xterm fallback
-#     (the session's gnome-terminal-server owns :0, so D-Bus delegation lands
-#      on the right display here — no bug reachable on loopback)
-#
-# Prints "<bin>\t<flags>" on stdout (tab-separated), or exits non-zero with a
-# loud-fail log if neither is installed. gnome-terminal retains `--wait`
-# (see Task 627 pgrep-visibility fix). xterm takes no flag.
-# xterm flags for the :99 VNC framebuffer. Fontconfig alias `monospace`
-# resolves via /etc/fonts to the distro's default monospace face (DejaVu
-# Sans Mono on Ubuntu/Debian) — no quoting needed, so the flag string
-# survives unquoted $flags word-splitting in start_terminal_on. Geometry
-# 160x45 fills the Xtigervnc display (1280x800 — see Xtigervnc -geometry
-# flag below) at 11pt; the prior empty flag string left xterm at its 80x24
-# default with the 6x13 `fixed` bitmap font, which rendered ~480x312 px of
-# the 1280x800 framebuffer with a black void around it.
-XTERM_VNC_FLAGS='-fa monospace -fs 11 -geometry 160x45'
-
-resolve_terminal_bin() {
-  local target_display="${1:-:99}"
-  local xterm_bin='' gnome_bin=''
-  [ -x /usr/bin/xterm ] && xterm_bin='/usr/bin/xterm'
-  [ -x /usr/bin/gnome-terminal ] && gnome_bin='/usr/bin/gnome-terminal'
-
-  if [ "$target_display" = ":99" ]; then
-    [ -n "$xterm_bin" ] && { printf '%s\t%s\n' "$xterm_bin" "$XTERM_VNC_FLAGS"; return 0; }
-    [ -n "$gnome_bin" ] && { printf '%s\t%s\n' "$gnome_bin" '--wait'; return 0; }
-  else
-    [ -n "$gnome_bin" ] && { printf '%s\t%s\n' "$gnome_bin" '--wait'; return 0; }
-    [ -n "$xterm_bin" ] && { printf '%s\t%s\n' "$xterm_bin" "$XTERM_VNC_FLAGS"; return 0; }
-  fi
-  tlog "failed err=\"no terminal emulator installed (expected /usr/bin/gnome-terminal or /usr/bin/xterm)\""
-  log "ERROR: no terminal emulator binary found — install xterm (apt-get install -y xterm)"
-  return 1
-}
-
-# Task 634 — runtime preflight for terminal-launch dependencies. Separates
-# exit 127 (xdotool missing from PATH) from exit 1 (xdotool present but no
-# window mapped) in check_window_on_display. The installer now verifies
-# apt deps via `dpkg -s` but an operator can still `apt remove xdotool`
-# post-install, so this is the matching runtime guard. Emits the failure
-# string on stderr so ensureTerminal's extractFailureLine captures it
-# verbatim into server.log's `ensure-terminal err=...` field.
-preflight_terminal_deps() {
-  if command -v xdotool >/dev/null 2>&1; then
-    log "xdotool: $(command -v xdotool)"
-    return 0
-  fi
-  tlog "failed err=\"xdotool not installed — re-run installer to repair\""
-  log "ERROR: xdotool missing — start-terminal cannot assert display-membership (re-run: npx -y @rubytech/create-maxy@latest)"
-  echo "[terminal-launch] failed err=\"xdotool not installed — re-run installer to repair\"" >&2
-  return 1
-}
-
-# Verify that at least one visible window is mapped on $target_display. Closes
-# the "PID visible in pgrep but window is not on target" class of silent fail
-# (Task 632). Uses xdotool's exit code directly — no stdout parsing for
-# control flow (feedback_no_stdout_parsing_for_control_flow.md). `--class '.'`
-# matches WM_CLASS (static for the window's lifetime) instead of WM_NAME
-# (which can be empty in the microseconds between window-create and
-# title-set). Retries 3× at 0.3s to absorb the window-map race.
-#
-# Returns 0 if any visible window appears on the display within ~1s, 1 otherwise.
-check_window_on_display() {
-  local target_display="$1"
-  # Task 634 — route xdotool stderr to vnc-boot.log instead of /dev/null.
-  # preflight_terminal_deps removes the 127-vs-1 conflation from production,
-  # but if xdotool ever fails for a non-missing-binary reason (broken X
-  # server, malformed DISPLAY), the diagnostic now lands in a grep-addressable
-  # log instead of vanishing. Control flow still depends solely on the exit
-  # code (feedback_no_stdout_parsing_for_control_flow.md).
-  for _ in 1 2 3; do
-    if DISPLAY="$target_display" xdotool search --onlyvisible --class '.' >/dev/null 2>>"$LOG_FILE"; then
-      return 0
-    fi
-    sleep 0.3
-  done
-  return 1
-}
-
-# Count visible windows on $target_display (diagnostic; used in failure logs).
-# Prints the integer count. Returns 0 on empty display (not an error).
-_count_windows_on_display() {
-  local target_display="$1"
-  DISPLAY="$target_display" xdotool search --onlyvisible --class '.' 2>/dev/null | wc -l | tr -d ' '
-}
-
-# pgrep pattern that matches operator-launched terminals but NEVER matches
-# /usr/libexec/gnome-terminal-server (D-Bus service, pre-existing). Matches:
-#   - /usr/bin/gnome-terminal --wait            (Ubuntu's python wrapper, invoked with --wait)
-#   - /usr/bin/python3 /usr/bin/gnome-terminal  (wrapper as seen via pgrep -f)
-#   - /usr/bin/gnome-terminal.real --wait       (actual binary, child of wrapper)
-#   - /usr/bin/xterm, xterm -geometry ...       (xterm, single-process emulator)
-# Rejects:
-#   - /usr/libexec/gnome-terminal-server        (D-Bus service, not ours to manage)
-#
-# The `(^|/)` alternation anchors on either the start of the cmdline or a
-# preceding `/` path separator, so the python wrapper path `/usr/bin/python3
-# /usr/bin/gnome-terminal --wait` is matched via the inner `/gnome-terminal`.
-# The `(\.real)?` optional suffix catches the actual binary. The trailing
-# `([[:space:]]|$)` breaks the match on `-server` (dash is not whitespace).
-# POSIX ERE — procps `pgrep` does not support `\s`, so use [[:space:]].
-_terminal_pgrep_pattern() {
-  echo '(^|/)(gnome-terminal(\.real)?([[:space:]]|$)|xterm([[:space:]]|$))'
-}
-
-# Return 0 if a launched terminal is alive, 1 otherwise.
-# ensureTerminal() uses this as its post-spawn liveness probe (the
-# terminal-domain analogue of waitForPort — terminals have no port).
-terminal_alive() {
-  pgrep -f "$(_terminal_pgrep_pattern)" >/dev/null 2>&1
-}
-
-# Return the first matching PID (used in logs). Empty string if none alive.
-terminal_pid() {
-  pgrep -f "$(_terminal_pgrep_pattern)" 2>/dev/null | head -n 1
-}
-
-# Kill all operator-launched terminal emulators. Pre-existing
-# gnome-terminal-server is unaffected by the anchored regex.
-kill_terminal_emulators() {
-  pkill -f "$(_terminal_pgrep_pattern)" 2>/dev/null || true
-}
-
-# Wait up to 1s for the spawned terminal to show up in pgrep.
-# Mirrors wait_for_port's deadline semantics (3 × 0.3s = 0.9s wall-clock max).
-wait_for_terminal() {
-  for _ in 1 2 3; do
-    if terminal_alive; then
-      return 0
-    fi
-    sleep 0.3
-  done
-  return 1
-}
-
-start_terminal_on() {
-  local target_display="$1"
-  local label="$2"  # "vnc" | "native"
-
-  # Idempotency: if a terminal is already alive, verify its window is actually
-  # mapped on $target_display before accepting. The pgrep-based liveness probe
-  # cannot distinguish a terminal on :0 (stale from an unclean close, or
-  # D-Bus-delegated by a pre-Task-632 gnome-terminal call) from one on :99.
-  # Self-heal: if the PID exists but no window appears on the target display,
-  # kill the stale emulator and fall through to respawn.
-  if terminal_alive; then
-    local existing_pid
-    existing_pid="$(terminal_pid)"
-    if check_window_on_display "$target_display"; then
-      tlog "already-running pid=${existing_pid} display=${target_display} windowPresent=true"
-      log "Terminal already running pid=${existing_pid} (${label})"
-      return 0
-    fi
-    local observed
-    observed="$(_count_windows_on_display "$target_display")"
-    tlog "self-heal pid=${existing_pid} display=${target_display} observed_windows=${observed} transport=${label} reason=\"window absent on target, respawning\""
-    log "Terminal pid=${existing_pid} alive but no window on ${target_display} — self-healing"
-    kill_terminal_emulators
-    sleep 0.3
-  fi
-
-  local resolved bin flags
-  if ! resolved="$(resolve_terminal_bin "$target_display")"; then
-    # resolve_terminal_bin already echoed the diagnostic via tlog; mirror it
-    # to stderr so the Node caller (ensureTerminal) captures the exact string.
-    echo "[terminal-launch] failed err=\"no terminal emulator installed\" transport=${label}" >&2
-    return 1
-  fi
-  bin="${resolved%%$'\t'*}"
-  flags="${resolved#*$'\t'}"
-
-  log "Starting ${bin} ${flags} on ${target_display} (${label})"
-
-  # setsid -f detaches the process from our controlling terminal and this
-  # script's process group, so the spawned terminal survives vnc.sh exiting.
-  # Output redirected to the terminal-launch log (not /dev/null) so any
-  # spawn-time stderr is captured. Flags is unquoted on purpose so an empty
-  # value (xterm's case) does not produce a stray "" arg.
-  if [ -n "$flags" ]; then
-    DISPLAY="${target_display}" setsid -f "$bin" $flags >> "$TERMINAL_LOG" 2>&1 || true
-  else
-    DISPLAY="${target_display}" setsid -f "$bin" >> "$TERMINAL_LOG" 2>&1 || true
-  fi
-
-  if ! wait_for_terminal; then
-    local diag="failed err=\"spawn detached but no terminal PID visible within 1s\" transport=${label} cmd=\"${bin} ${flags}\""
-    tlog "$diag"
-    echo "[terminal-launch] $diag" >&2
-    log "ERROR: terminal failed to appear in pgrep within 1s on ${target_display} (${label}) — investigate setsid -f detachment / --wait flag"
-    return 1
-  fi
-
-  local pid
-  pid="$(terminal_pid)"
-
-  # Post-spawn invariant (Task 632): PID presence is necessary but not
-  # sufficient — assert the window actually landed on the target display.
-  if ! check_window_on_display "$target_display"; then
-    local observed
-    observed="$(_count_windows_on_display "$target_display")"
-    local diag="failed err=\"window absent from target display after spawn\" pid=${pid} display=${target_display} observed_windows=${observed} transport=${label} cmd=\"${bin} ${flags}\""
-    tlog "$diag"
-    echo "[terminal-launch] $diag" >&2
-    log "ERROR: terminal pid=${pid} spawned but no window on ${target_display} (${label}) — likely D-Bus delegation to another display"
-    return 1
-  fi
-
-  tlog "started pid=${pid} display=${target_display} cmd=\"${bin} ${flags}\" transport=${label} windowPresent=true"
-  log "Terminal ready (${label}) pid=${pid}"
-  return 0
-}
-
-start_terminal() {
-  preflight_terminal_deps || return 1
-  start_terminal_on ":99" "vnc"
-}
-
-start_terminal_native() {
-  preflight_terminal_deps || return 1
-  discover_native_session
-  start_terminal_on "${NATIVE_DISPLAY}" "native"
-}
-
-# Task 643 — upgrade-specialised terminal spawn. Sibling of start_terminal_on
-# rather than a parameterised branch because two things diverge:
-#
-#   (1) idempotency inverts. start_terminal_on short-circuits when a terminal
-#       is already alive on the target display; the upgrade variant MUST kill
-#       any pre-existing shell and spawn a fresh one so npx runs in a clean
-#       environment (no operator aliases, cwd, or half-typed commands).
-#
-#   (2) binary invocation grows a command argument. Both binaries keep their
-#       existing flags (xterm: $XTERM_VNC_FLAGS, gnome-terminal: --wait), then
-#       append a binary-specific "run this command" dispatcher:
-#         xterm         -e bash -c "<cmd>; exec bash"
-#         gnome-terminal -- bash -c "<cmd>; exec bash"
-#       The trailing `exec bash` replaces the shell process after the upgrade
-#       exits, so the terminal window stays open for scrollback review.
-#
-# Everything else — preflight, binary resolution, setsid -f detach,
-# wait_for_terminal, check_window_on_display (Task 632 invariant) — is the
-# same pipeline as start_terminal_on. The two functions share helpers, not
-# bodies, so a future invariant addition (e.g. post-spawn keepalive) requires
-# two edits, not one — an intentional tradeoff for readability.
-start_terminal_upgrade_on() {
-  local target_display="$1"
-  local label="$2"  # "vnc" | "native"
-
-  # Unconditional kill: no "already running" short-circuit. An upgrade grafted
-  # onto a pre-existing operator shell would inherit that shell's env, cwd,
-  # and interactive state — not acceptable for an installer run.
-  if terminal_alive; then
-    local existing_pid
-    existing_pid="$(terminal_pid)"
-    tlog "upgrade-kill pid=${existing_pid} reason=\"pre-upgrade fresh shell required\""
-    log "Terminal pid=${existing_pid} killed to spawn fresh upgrade shell (${label})"
-    kill_terminal_emulators
-    sleep 0.3
-  fi
-
-  local resolved bin flags
-  if ! resolved="$(resolve_terminal_bin "$target_display")"; then
-    echo "[terminal-launch] failed err=\"no terminal emulator installed\" transport=${label} reason=upgrade" >&2
-    return 1
-  fi
-  bin="${resolved%%$'\t'*}"
-  flags="${resolved#*$'\t'}"
-
-  # Binary-specific command dispatcher. Both variants wrap the upgrade in
-  # `bash -c "<cmd>; exec bash"` so the shell persists after npx exits.
-  local upgrade_cmd='npx -y @rubytech/create-maxy@latest'
-  local bash_wrapper="${upgrade_cmd}; exec bash"
-  local dispatch_flag
-  case "$bin" in
-    */xterm)          dispatch_flag='-e' ;;
-    */gnome-terminal) dispatch_flag='--' ;;
-    *)
-      # resolve_terminal_bin only returns xterm or gnome-terminal paths. This
-      # branch is defensive; a future binary addition (e.g. kitty) would need
-      # its own dispatcher here.
-      tlog "failed err=\"unknown terminal binary dispatcher for ${bin}\" reason=upgrade"
-      echo "[terminal-launch] failed err=\"unknown terminal binary dispatcher for ${bin}\" transport=${label} reason=upgrade" >&2
-      return 1
-      ;;
-  esac
-
-  # Task 647: the upgrade command (`npx -y @rubytech/create-maxy@latest`) calls
-  # `systemctl --user restart maxy-ui` partway through. If the terminal shell
-  # lives in maxy-ui's cgroup it gets SIGKILL'd by that restart and the install
-  # aborts. `systemd-run --user --scope` places the shell in its own transient
-  # scope unit whose lifetime is independent of whichever service triggered
-  # vnc.sh. `setsid -f` is no longer needed — scope units handle detachment.
-  # Fallback (no systemd-run): `setsid -f`, with the known caveat that the
-  # caller must not be inside a unit scheduled for restart during the install.
-  local run_prefix=""
-  if command -v systemd-run >/dev/null 2>&1; then
-    run_prefix="systemd-run --user --quiet --scope --unit=maxy-upgrade-terminal-$$.scope --collect --"
-    log "Wrapping upgrade terminal in systemd-run --user --scope (Task 647)"
-  else
-    log "WARNING: systemd-run not available — falling back to setsid -f (terminal may die on maxy-ui restart)"
-  fi
-  log "Starting ${run_prefix} ${bin} ${flags} ${dispatch_flag} bash -c \"${upgrade_cmd}; exec bash\" on ${target_display} (${label}) reason=upgrade"
-
-  # $flags stays unquoted for word-splitting (xterm's flags have multiple
-  # tokens); bash_wrapper stays quoted so the whole command string reaches
-  # bash -c as one argument. $run_prefix is unquoted so its words expand.
-  if [ -n "$run_prefix" ]; then
-    if [ -n "$flags" ]; then
-      DISPLAY="${target_display}" $run_prefix "$bin" $flags "$dispatch_flag" bash -c "$bash_wrapper" >> "$TERMINAL_LOG" 2>&1 &
-    else
-      DISPLAY="${target_display}" $run_prefix "$bin" "$dispatch_flag" bash -c "$bash_wrapper" >> "$TERMINAL_LOG" 2>&1 &
-    fi
-    disown 2>/dev/null || true
-  else
-    if [ -n "$flags" ]; then
-      DISPLAY="${target_display}" setsid -f "$bin" $flags "$dispatch_flag" bash -c "$bash_wrapper" >> "$TERMINAL_LOG" 2>&1 || true
-    else
-      DISPLAY="${target_display}" setsid -f "$bin" "$dispatch_flag" bash -c "$bash_wrapper" >> "$TERMINAL_LOG" 2>&1 || true
-    fi
-  fi
-
-  if ! wait_for_terminal; then
-    local diag="failed err=\"spawn detached but no terminal PID visible within 1s\" transport=${label} cmd=\"${bin} ${flags} ${dispatch_flag} bash -c '${upgrade_cmd}; exec bash'\" reason=upgrade"
-    tlog "$diag"
-    echo "[terminal-launch] $diag" >&2
-    log "ERROR: upgrade terminal failed to appear in pgrep within 1s on ${target_display} (${label})"
-    return 1
-  fi
-
-  local pid
-  pid="$(terminal_pid)"
-
-  # Task 632 invariant: PID presence is necessary but not sufficient.
-  if ! check_window_on_display "$target_display"; then
-    local observed
-    observed="$(_count_windows_on_display "$target_display")"
-    local diag="failed err=\"window absent from target display after spawn\" pid=${pid} display=${target_display} observed_windows=${observed} transport=${label} cmd=\"${bin} ${flags} ${dispatch_flag} bash -c '${upgrade_cmd}; exec bash'\" reason=upgrade"
-    tlog "$diag"
-    echo "[terminal-launch] $diag" >&2
-    log "ERROR: upgrade terminal pid=${pid} spawned but no window on ${target_display} (${label})"
-    return 1
-  fi
-
-  tlog "started pid=${pid} display=${target_display} cmd=\"${bin} ${flags} ${dispatch_flag} bash -c '${upgrade_cmd}; exec bash'\" transport=${label} windowPresent=true reason=upgrade"
-  log "Upgrade terminal ready (${label}) pid=${pid} cmd=\"${upgrade_cmd}\""
-  return 0
-}
-
-start_terminal_upgrade() {
-  preflight_terminal_deps || return 1
-  start_terminal_upgrade_on ":99" "vnc"
-}
-
 start_chrome_native() {
   discover_native_session
 
@@ -678,34 +309,6 @@ case "${1:-}" in
     start_chrome_native
     ;;
 
-  start-terminal)
-    start_terminal
-    ;;
-
-  start-terminal-native)
-    start_terminal_native
-    ;;
-
-  start-terminal-upgrade)
-    start_terminal_upgrade
-    ;;
-
-  kill-terminal)
-    pid="$(terminal_pid)"
-    kill_terminal_emulators
-    if [ -n "$pid" ]; then
-      tlog "killed pid=${pid} reason=overlay-close"
-    else
-      tlog "killed-noop"
-    fi
-    ;;
-
-  status-terminal)
-    # Exit 0 if an operator-launched terminal is running, 1 otherwise.
-    # Used by ensureTerminal() in vnc.ts as the in-process liveness probe.
-    terminal_alive && exit 0 || exit 1
-    ;;
-
   stop)
     log "Stopping VNC stack"
     kill_stale
@@ -717,7 +320,7 @@ case "${1:-}" in
     ;;
 
   *)
-    echo "Usage: vnc.sh start | stop | start-chrome | start-chrome-native | start-terminal | start-terminal-native | start-terminal-upgrade | kill-terminal | status-terminal | status" >&2
+    echo "Usage: vnc.sh start | stop | start-chrome | start-chrome-native | status" >&2
     exit 1
     ;;
 esac

package/payload/platform/templates/dotfiles/.tmux.conf

@@ -0,0 +1 @@
+set -g history-limit 50000

package/payload/platform/templates/systemd/maxy-ttyd.service

@@ -0,0 +1,25 @@
+[Unit]
+Description=Maxy admin terminal (ttyd + tmux) — persistent PTY for admin UI
+After=default.target
+
+[Service]
+Type=simple
+# ttyd binary lives at /usr/local/bin/ttyd — installed from pinned upstream
+# GitHub releases (SHA256-verified) by create-maxy's step 11 (Task 602),
+# because Debian Bookworm's apt does NOT carry a ttyd package. /usr/local/bin
+# is the standard location for binaries installed outside the distro package
+# manager; /usr/bin is reserved for apt-owned files.
+# -p 7681   listen on 127.0.0.1:7681 (same-origin proxy in maxy-ui binds to it)
+# -i 127.0.0.1   reject non-loopback connections at the ttyd layer as well
+# -W        writable (allow client → server input bytes)
+# tmux new-session -A -s maxy-pty   attach if session exists, create otherwise.
+#   Lifetime = user session / device lifetime. Outlives maxy-ui restarts because
+#   this unit has no After=maxy-ui.service and no Requires= — independent.
+# -x 200 -y 50  initial geometry; xterm.js fit-addon drives runtime resizes.
+ExecStart=/usr/local/bin/ttyd -p 7681 -i 127.0.0.1 -W tmux new-session -A -s maxy-pty -x 200 -y 50
+Environment=TERM=xterm-256color
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target