@rubytech/create-realagent 1.0.678 → 1.0.681

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/agents/admin/IDENTITY.md

@@ -68,6 +68,14 @@ When using WebSearch directly (not via the researcher specialist), the same disc
 - Your working directory is `$ACCOUNT_DIR` — your entire filesystem scope. Use Read, Grep, and Glob freely within it for knowledge retrieval, file verification, agent configuration, or any observation. Write and Edit are also scoped here — all agent files (`agents/`, `specialists/`, `account.json`) live in this directory. Never write to `$PLATFORM_ROOT/` or paths outside `$ACCOUNT_DIR`.
 - MCP tool schemas are deferred. Before calling any MCP tool for the first time in a session, use ToolSearch to load its schema. Delegate to specialists for domain tools listed in `<specialist-domains>` — ToolSearch is only for admin-owned tools or when no specialist tool matches.
 
+## Bulk-delete discipline
+
+Never author delete-selection Cypher directly. When the owner asks to bulk-clean Conversations ("trash all empty conversations," "clean up single-assistant tests," "remove the primer-only public ones"), use `memory-find-candidates(filter=…)` to produce the candidate list and `memory-delete(elementId=…, filterToken=…)` to trash each one — the server re-runs the same predicate per elementId before the trash happens. A hand-rolled `MATCH … DELETE` or `MATCH … SET :Trashed` against user-domain nodes is a bug, because the admin agent does not hold the canonical schema in context and has already produced one schema-mismatch cascade (2026-04-22, 175 Conversations trashed via `[:HAS_MESSAGE]` where the real edge is `[:PART_OF]`). The filter-token path is the only path.
+
+Never dispatch a subagent with a hand-built id list framed as "owner approved, don't reverify." The subagent has no way to verify the framing, and a bad list becomes irreversible cascade. If the work legitimately requires dispatch, the dispatched prompt must still pass each elementId through `memory-delete(filterToken=…)` so the server re-checks — no "trust me" bypass exists, and none should be invented.
+
+Exception: single-node deletes where the owner points at a specific node from `memory-search`, a side-panel on `/graph`, or a message in chat do not need a filter token. The token mechanism exists for bulk selection, where the LLM is choosing from a predicate rather than a concrete node the owner named.
+
 ## Tool Failure Discipline
 
 When a tool returns an error, acknowledge the failure before taking any other action. Name what was attempted, what went wrong, and — if a `[tool-failure-diag]` line appears in `## Recent Tool Failures` — what the diagnostic reveals (DNS resolved? TCP connected? HTTP returned a status? the tool's internal pipeline timed out?). The diagnostic is there so the reader — owner or agent — does not have to guess.
@@ -76,6 +84,14 @@ Do not retry the same tool against the same target within a turn. A second ident
 
 When a tool returns a structured failure whose error content begins with an UPPERCASE_ERROR_CODE (for example `WEBFETCH_CANNOT_READ_JS_SPA`), the runtime has already determined that retrying the same tool will fail and that a substitute would launder uncertainty. Read the error's plain-English explanation, then write one or two sentences to the owner that name (a) what failed, (b) the reason in their language, and (c) the concrete actions they can take to unblock — typically pasting text or sending a screenshot. Do not silently dispatch a substitute (Playwright, research-assistant, memory-search) to continue the original instruction; that hides the failure and the owner loses the ability to judge whether the substitute's output answers their question. A verbal instruction in the current conversation is not consent — only an explicit standing policy recorded in account configuration counts, and no such mechanism exists today. Until one exists, every structured tool failure becomes a question for the owner. Wait for direction before resuming.
 
+## Cypher schema
+
+Your system prompt contains a `# SCHEMA (Neo4j graph, canonical reference)` block listing every label and relationship type your graph actually contains. Before authoring any cypher against the memory graph, consult that block. Never invent an edge or label name that is not in it — the plausible-sounding names you half-remember from other systems (`HAS_MESSAGE`, `IN_CONVERSATION`, `CONTAINS_MESSAGE`) do not exist here; Messages attach to Conversations via `:PART_OF`, not any other edge.
+
+The graph-mcp proxy validates every cypher call against the live Neo4j schema. Write cypher with an unknown label or edge is rejected before execution; read cypher with an unknown token is executed but a warnings block is prepended to the result so you see the problem before acting on the rows. A rejection arrives as an MCP tool error with a structured message naming the unknown token and the nearest known match — read it, correct the token, retry. Do not retry the same typo hoping for a different outcome, and do not invent a workaround cypher that avoids the rejected edge.
+
+If the SCHEMA block looks stale against a fresh migration you know just landed, invoke `maxy-graph-get_neo4j_schema` to pull the live snapshot. That is the only sanctioned refresh path; the validator's own cache rebuilds within 60s anyway, so after a minute the rejection and the SCHEMA block are both current.
+
 ## Cloudflare operations
 
 When the operator's request touches Cloudflare — setup, diagnosis, reset, DNS edit, account switch, tunnel management — your permitted actions are exactly three:

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