@rubytech/create-realagent 1.0.673 → 1.0.676

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.673",
+  "version": "1.0.676",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent": "./dist/index.js"

package/payload/platform/plugins/docs/references/memory-guide.md

@@ -84,7 +84,7 @@ Ask naturally:
 
 Maxy answers relational questions — "list all my people", "how many tasks do I have", "find the person with email X", "show me the 20 most recently created nodes" — via direct read-only Cypher against your Neo4j. This is faster and more precise than semantic search when the question is "the exact set where", not "things similar to".
 
-You can also open a visual view of your graph at any time from the burger menu → **Graph**. Click the **Filter** button in the toolbar to open the filter menu — it lists only the top-level entity types in your schema (Conversation, Person, Task, KnowledgeDocument, …), one row per type, showing your per-type node count and sorted so the most-connected types sit at the top. Child types (messages inside a conversation, sections inside a document), conversation channel variants (admin vs public), message role variants (user vs assistant), workflow execution plumbing (`ToolCall`, `WorkflowRun`, `WorkflowStep`, `StepResult`), and review signals (`ReviewAlert`) never appear as filter rows — you reach children by clicking the parent and exploring its neighbourhood, and review signals have their own dedicated surface in admin chat. Active rows render a force-directed map, coloured by label. Click a node to pivot into its 1-hop neighbourhood; click another node inside that neighbourhood to pivot again. A breadcrumb strip above the canvas shows where you are (`Filter › Conversation › AssistantMessage`). The **Back** control pops one level — three clicks in always undoes with three Back presses; the filter view is the irreducible root. Click the **×** inside the filter menu to clear your chip selection. Type in the search box to highlight matches; submitting a search also widens the filter to include any node types the hits belong to, so relevant matches render instead of disappearing into a "not in current view" banner.
+You can also open a visual view of your graph at any time from the burger menu → **Graph**. Click the **Filter** button in the toolbar to open the filter menu — it lists only the top-level entity types in your schema (Conversation, Person, Task, KnowledgeDocument, …), one row per type, showing your per-type node count and sorted so the most-connected types sit at the top. Child types (messages inside a conversation, sections inside a document), conversation channel variants (admin vs public), message role variants (user vs assistant), workflow execution plumbing (`ToolCall`, `WorkflowRun`, `WorkflowStep`, `StepResult`), and review signals (`ReviewAlert`) never appear as filter rows — you reach children by clicking the parent and exploring its neighbourhood, and review signals have their own dedicated surface in admin chat. Active rows render a force-directed map, coloured by label. Click a node to pivot into its 1-hop neighbourhood; click another node inside that neighbourhood to pivot again. Clicking a Message shows its details in the side panel; the Conversation view stays put — you read sibling messages without losing the chain on canvas. A breadcrumb strip above the canvas shows where you are (`Filter › Conversation › AssistantMessage`). The **Back** control pops one level — three clicks in always undoes with three Back presses; the filter view is the irreducible root. Click the **×** inside the filter menu to clear your chip selection. Type in the search box to highlight matches; submitting a search also widens the filter to include any node types the hits belong to, so relevant matches render instead of disappearing into a "not in current view" banner.
 
 Conversations and Messages carry role/channel sublabels so you can read the chat topology by colour alone — admin vs public conversations and user vs assistant messages render in distinct shades on the canvas. The filter menu intentionally does not split them into separate rows — the base chip is the entry point; you see the variants as colours once you're inside a neighbourhood.
 

package/payload/platform/plugins/docs/references/platform.md

@@ -64,15 +64,19 @@ The chat input auto-grows as you type — it expands to fit your message and shr
 
 ## Admin Terminal
 
-The admin UI includes a live terminal surface that opens a real shell on your Pi in the browser, reached via the Software Update modal. Under the hood it's a WebSocket (`/admin/terminal/ws`) attached through `@xterm/xterm` to `ttyd` on `127.0.0.1:7681`, backed by a persistent tmux session named `maxy-pty`.
+The admin UI has a single terminal surface — one pipeline (a real GUI terminal emulator running on the Pi's VNC display `:99`, rendered inside an `iframe` of `/vnc-viewer.html`) with two entry points: the burger menu's **Terminal** button (opens a plain operator shell) and the Software Update modal's **Upgrade** button (opens the same iframe with `npx -y @rubytech/create-maxy@latest` already running in the spawned shell).
 
-The tmux session outlives admin-server restarts — running an upgrade inside this terminal means you see the live shell output continuously, even through the admin server's own restart mid-upgrade. Closing the browser tab does not kill the running work; re-opening the Software Update window reattaches to the same session during an active upgrade and scrollback shows everything that happened in the meantime. Password-protected `sudo` prompts appear natively inside the terminal, and the password you type never leaves the Pi — the admin-server proxy is a raw byte pipe that never inspects frame payloads.
+The binary is chosen by target display. For the VNC virtual display `:99`, **xterm** is preferred because it honours `DISPLAY` directly with no IPC layer. For the native loopback display, **gnome-terminal** is preferred because the login session's `gnome-terminal-server` owns that display. (gnome-terminal cannot be used for the VNC display — it's a D-Bus launcher that delegates window creation to the session's server, and the window would appear on the physical screen instead of inside the admin iframe.) Post-spawn, the launch pipeline asserts the window actually landed on the target display via `xdotool search --onlyvisible --class '.'` — if anything went wrong (gnome-terminal D-Bus delegation, missing `xdotool`, broken X server), the 502 response body carries the exact diagnostic string inline in the UI instead of showing a black rectangle.
 
-The Software Update window mounts the terminal lazily: neither the terminal, its WebSocket, nor its black-backgrounded container render until you click Upgrade. Pre-click, the window shows a small "Ready to upgrade — click Upgrade to begin." line and no network traffic flows. On click, the window mounts the terminal and sends the npx command via `RemoteTerminal.onReady`; the terminal output is the only upgrade observability surface. A background version poll flips to the success row when `installed === latest` and reloads the page. The upgrade command is dispatched the moment the WebSocket opens — you won't see "terminal not ready" warnings on a healthy device. If the admin server cannot reach `ttyd`, the window renders an inline "Admin terminal not available" message with the exact re-install command and a Try again button. Closing the window does not kill the upgrade — the tmux session keeps running upstream — but the window itself starts fresh on every reopen: if you reopen during an in-flight upgrade, click Upgrade again and the scrollback shows the in-progress output.
+**Software Update flow.** Click Upgrade in the modal → the admin server kills any pre-existing terminal on `:99` (the upgrade must run in a fresh shell) and spawns the chosen binary with a command dispatcher: `xterm -e bash -c "npx …; exec bash"` or `gnome-terminal -- bash -c "npx …; exec bash"`. The trailing `exec bash` replaces the shell process after `npx` exits so the window stays open — you can scroll through the full installer output and read the final "Open in your browser:" line at your own pace. The modal mounts the fullscreen VNC terminal overlay (the same surface the burger menu's Terminal button uses) and the operator watches the installer run at viewport height. A background poll of `GET /api/admin/version` every 5 seconds detects completion: the moment `installed === latest`, the modal flips to success and the page reloads two seconds later. Password-protected `sudo` prompts appear natively inside the terminal — the password you type never leaves the Pi.
 
-Because the terminal is the only surface, it narrates its own state when something goes wrong. The moment you click Upgrade, the terminal echoes a timestamped `[upgrade] starting at <UTC> — shell+ws+tmux+xterm chain OK` line before the `npx` invocation begins — that single line confirms the WebSocket, tmux session, shell, and xterm renderer are all working end-to-end. If 5 seconds then pass with no output from `npx`, the terminal itself writes a `[terminal] no bytes from upstream in 5s — ws.readyState=…, bytesReceived=…, attempt=…` diagnostic into its own buffer, and repeats that narration every 30 seconds of continued silence. If even that narration never appears within ~10 seconds of click, the xterm renderer or its WebSocket is broken and reloading the admin UI is the fix. On the server side, `~/.maxy/logs/terminal.log` carries a `terminal-proxy-flow` heartbeat every 5 seconds while bytes are moving and every ~30 seconds while idle, with `clientBytes`, `upstreamBytes`, and `idleMs` fields — so a stuck upstream presents as `upstreamBytes` frozen and `idleMs` climbing, directly visible in a `tail -f` without any client-side evidence needed.
+**Operator Terminal flow.** The burger menu's Terminal button uses the exact same pipeline, minus the pre-loaded command. Click Terminal → the admin server spawns the same binary (no `-e`/`--` dispatcher, no `bash -c` wrapper) → the iframe shows an empty shell. Closing the overlay with Esc or × kills the spawned PID on the Pi via `POST /api/admin/terminal/close`; reopening launches a fresh shell.
 
-The burger menu in the admin chat also includes a standalone **Terminal** entry next to **Browser**, but this surface is intentionally *different* from the upgrade-modal terminal. Clicking it spawns a real GUI terminal emulator on the VNC virtual display `:99` via the same `/vnc-viewer.html` iframe that Browser uses. The binary is chosen by target display: for the VNC virtual display, **xterm** is preferred because it honours `DISPLAY` directly with no IPC layer; for the native loopback display, **gnome-terminal** is preferred because the login session's `gnome-terminal-server` owns that display. (gnome-terminal cannot be used for the VNC display — it's a D-Bus launcher that delegates window creation to the session's server, and the window would appear on the physical screen instead of inside the admin iframe.) The header Terminal is isomorphic to the header Browser: one pipeline (launch endpoint → display spawn → display-membership assertion → noVNC iframe), one failure domain — and deliberately decoupled from ttyd. Stopping `maxy-ttyd.service` leaves the header Terminal fully functional; only the in-modal upgrade terminal degrades. Closing the header Terminal overlay (Escape or the `×` button) kills the spawned emulator PID on the Pi via `POST /api/admin/terminal/close`; re-opening launches a fresh shell. Authorisation is inherited from the same `canAccessAdmin()` gate that wraps every `/api/admin/*` route. The launch endpoint logs to `~/.maxy/logs/terminal-launch.log` (script-level spawn/kill events, including `windowPresent=true` on success and `self-heal pid=... observed_windows=<n>` when a stale PID is respawned) and to `vnc-boot.log` via `vncLog('ensure-terminal', ...)` (Node-side state machine), mirroring the Browser's `ensure-cdp` observability shape. Any spawn failure surfaces verbatim in the 502 response body — no silent black rectangles.
+**If you click Upgrade while an operator Terminal is open** (or vice versa), the pre-existing shell is killed and the iframe refreshes with the new shell. The upgrade is disruptive by design — you cannot graft an installer onto a shell that already has your env, cwd, and aliases.
+
+**Error surface.** If the terminal emulator fails to spawn on `:99` (missing xterm, gnome-terminal broken, X server down), the UpdateModal renders the verbatim server-side diagnostic — e.g. `[terminal-launch] failed err="window absent from target display after spawn" pid=... display=:99 observed_windows=0 transport=vnc reason=upgrade` — and the Upgrade button re-labels to "Try again". The same string lands in `~/.maxy/logs/vnc-boot.log` under `action=launch-upgrade-failed err="..."`, so what you see in the modal and what your operator-visible diagnostic grep finds are identical.
+
+**Authorisation** is inherited from the same `canAccessAdmin()` gate that wraps every `/api/admin/*` route.
 
 ## AI Content Provenance
 

package/payload/platform/plugins/docs/references/troubleshooting.md

@@ -93,54 +93,66 @@ If the initial Cloudflare login fails during setup, Maxy will fall back to askin
 
 ---
 
-## Admin Terminal Stuck Disconnected After Upgrade
+## Software Update click shows an error instead of opening the terminal
 
-**Symptom:** The Software Update window's terminal goes blank, says "server restart detected — reconnecting…" and never comes back, or the window sits empty after you open it.
+**Symptom:** You clicked **Upgrade** in the Software Update modal, but instead of the VNC terminal overlay appearing, the modal shows a red error row like:
 
-**Check:** `sudo systemctl --user status maxy-ttyd` — the unit should be `active (running)`. If it is, the admin-server proxy should reattach automatically within a few seconds.
+```
+[terminal-launch] failed err="window absent from target display after spawn" pid=1234 display=:99 observed_windows=0 transport=vnc reason=upgrade
+```
 
-**Fix:** Restart the unit:
+…and the Upgrade button re-labels to "Try again".
 
-```bash
-sudo systemctl --user restart maxy-ttyd
-```
+**What it means:** `POST /api/admin/terminal/launch-upgrade` returned a 502 — the admin server tried to spawn a real terminal on the VNC display `:99` with `npx -y @rubytech/create-maxy@latest` pre-loaded, but the spawn failed or the window never appeared on the target display. The modal's upgrade path uses the same pipeline as the header-menu Terminal; if the operator Terminal button works, the VNC stack itself is healthy and the fault is usually a missing dep or a stale binary. If the operator Terminal also fails, start with the "Header Terminal click shows an error alert" section below.
 
-This is safe — the tmux session survives the ttyd restart because `tmux new-session -A -s maxy-pty` is idempotent. Any upgrade or other shell command still running inside the session continues uninterrupted; ttyd simply re-attaches to it. If the session itself is wedged, you can kill it explicitly with `tmux kill-session -t maxy-pty` and the next attach will create a fresh one.
+Step-by-step diagnosis — the error string in the modal is identical to the entry in `~/.maxy/logs/vnc-boot.log`, so you can grep it directly:
 
-**Terminal unit missing entirely?** If `sudo systemctl --user status maxy-ttyd` reports `unit not found`, the installer's ttyd provisioning step failed — typically on a Bookworm device where `ttyd` is not available via apt and the upstream download (or SHA256 check) failed at install time. Re-run `npx -y @rubytech/create-maxy@latest`; the operator-visible remediation command is also printed at install time in `~/.maxy/logs/install-*.log`.
+```bash
+# 1. Find the latest upgrade launch attempt
+sudo grep 'action=launch-upgrade' ~/.maxy/logs/vnc-boot.log | tail -10
 
----
+# 2. See the script-level failure line (same string the modal shows)
+sudo tail -n 30 ~/.maxy/logs/terminal-launch.log
+
+# 3. Verify binaries are present
+which xterm xdotool
 
-## "Admin terminal not available" in the Software Update window
+# 4. Confirm the VNC display itself is up
+DISPLAY=:99 xdpyinfo >/dev/null 2>&1 && echo "display :99 ok" || echo "display dead"
+```
 
-**Symptom:** The Software Update window displays "Admin terminal not available. Re-run the installer from a shell: `npx -y @rubytech/create-maxy@latest`" with a Try again button, instead of the usual terminal area.
+**Common upgrade-specific failures:**
 
-**What it means:** The admin server could not reach `ttyd` on `127.0.0.1:7681`. Either `maxy-ttyd.service` is not running, or it failed to install during setup.
+- `err="no terminal emulator installed"` → run `sudo apt-get install -y xterm xdotool` or re-run `npx -y @rubytech/create-maxy@latest` — the installer provisions both as hard deps.
+- `err="spawn detached but no terminal PID visible within 1s" ... reason=upgrade` → X server on `:99` is wedged; `sudo systemctl --user restart maxy-ui` cycles the VNC stack via `vnc.sh start`. Then click **Try again** in the modal.
+- `err="window absent from target display after spawn" ... reason=upgrade` → the spawn succeeded but landed on the wrong display (Task 632 class). Re-run the installer to refresh the `resolve_terminal_bin` logic. If a stale `gnome-terminal` is hitting `:99` via D-Bus delegation, the installer's `xterm` fallback is the fix.
+- `err="xdotool not installed — re-run installer to repair"` → Task 634 preflight. `sudo apt-get install -y xdotool` or re-run the installer.
+- `err="VNC failed to start after recovery attempt"` → `Xtigervnc` itself is not coming up. Inspect `~/.maxy/logs/vnc-boot.log` for tigervnc startup lines; `ss -ltn '( sport = 6080 or sport = 5900 )'` should show both ports listening.
 
-**Fix:** Run the exact command shown in the error message from a shell on the device:
+**Click Try again** after applying any fix — the modal re-POSTs the launch-upgrade request.
 
-```bash
-npx -y @rubytech/create-maxy@latest
-```
+---
 
-Then return to the upgrade window and click **Try again**. The window re-probes `/api/health` and, once ttyd is listening, the terminal area mounts as normal. If the problem persists, check the boot log for `[ttyd] upstream NOT reachable on 127.0.0.1:7681` and follow the `maxy-ttyd` restart steps above.
+## Upgrade terminal opens but npx never runs
 
-## Upgrade terminal stays blank after clicking Upgrade
+**Symptom:** You clicked **Upgrade**, the VNC overlay opened with a visible shell prompt, but `npx -y @rubytech/create-maxy@latest` does not execute and the shell is idle.
 
-**Symptom:** You clicked **Upgrade**, the terminal area mounted, but the terminal looks empty.
+**What it means:** The VNC spawn succeeded but the binary-specific command dispatcher (xterm `-e` or gnome-terminal `--`) did not forward the command. Given the installer ships `xterm` on `:99` by default (with D-Bus-safe dispatching), the likely causes are:
 
-**What you should see — the terminal narrates itself.** Within a few hundred milliseconds of click, the terminal echoes a line like `[upgrade] starting at 2026-04-21T11:48:33Z — shell+ws+tmux+xterm chain OK`. That single line confirms the WebSocket, tmux session, shell, and xterm renderer are all working. Within ~2 seconds on a warm npx cache, the installer's own first line arrives on top of that.
+- A stale binary override has re-pointed `resolve_terminal_bin` to `gnome-terminal` on `:99` despite the Task 632 fix.
+- A shell the operator manually spawned (via the header Terminal) wasn't killed before the upgrade click, and `ensureTerminalUpgrade`'s pre-kill step silently failed.
 
-**If the terminal is silent for more than 5 seconds:** the terminal itself writes a yellow diagnostic like `[terminal] no bytes from upstream in 5s — ws.readyState=1, bytesReceived=0, attempt=1` into its own buffer, and repeats that narration every 30 seconds of continued silence. If those lines appear, the WebSocket and renderer are fine — the problem is upstream. SSH to the device and check `ttyd`:
+**Check:**
 
 ```bash
-sudo systemctl --user status maxy-ttyd
-sudo tail -f ~/.maxy/logs/terminal.log
+# The spawned binary must appear in this log with the bash-c wrapper
+sudo grep 'started.*reason=upgrade' ~/.maxy/logs/terminal-launch.log | tail -3
+# Expected shape: started pid=<N> display=:99 cmd="/usr/bin/xterm ... -e bash -c 'npx -y @rubytech/create-maxy@latest; exec bash'" transport=vnc windowPresent=true reason=upgrade
 ```
 
-In `terminal.log`, look for `terminal-proxy-flow` lines — they're emitted every 5 seconds when bytes are moving and every ~30 seconds while idle, with `clientBytes`, `upstreamBytes`, and `idleMs` fields. A stuck upstream shows `upstreamBytes` frozen and `idleMs` climbing. If `maxy-ttyd` is not running, restart it with `sudo systemctl --user restart maxy-ttyd`, then close and reopen the Software Update window. If `ttyd` is healthy and `idleMs` keeps climbing, the installer process itself has died — re-run `npx -y @rubytech/create-maxy@latest` from an SSH shell directly.
+If the `cmd=` field does not contain `-e bash -c`, re-run the installer — the vnc.sh on the device is pre-Task-643. If the command IS logged correctly but nothing is running, open the VNC overlay and type `history | tail` inside the shell — if the npx line is there, it ran and exited (check `~/.maxy/logs/install-*.log` for the exit status).
 
-**If no narration appears at all within ~10 seconds of click:** the xterm renderer or its WebSocket is broken — reload the admin UI in your browser. The absence of the self-narration is itself the diagnostic. On reload, if the preamble line does not appear again within a few hundred milliseconds of clicking Upgrade, the admin server cannot reach `ttyd`; follow the "Admin terminal not available" steps above.
+---
 
 ## Header Terminal click shows an error alert
 
@@ -270,7 +282,7 @@ grep 'cmd=' ~/.maxy/logs/terminal-launch.log | tail -3
 
 If the failure log shows `window absent from target display`, the fix already ran but spawn still went to the wrong display — re-run the installer (`npx -y @rubytech/create-maxy@latest`) from a shell to pick up the latest `xterm` + `xdotool` preflight. If the failure log shows no recent entries and the iframe is still black, check `ss -ltn '( sport = 6080 or sport = 5900 )'` and `pgrep -af Xtigervnc|websockify` — the symptom might be a VNC-stack regression rather than a terminal-binary mismatch.
 
-The header Terminal is decoupled from `maxy-ttyd.service` by design — stopping that service should *not* break the header Terminal. If the upgrade modal breaks but the header Terminal still works, the problem is isolated to ttyd (see the "Admin Terminal Stuck Disconnected After Upgrade" and "Admin terminal not available" sections above).
+Both the header Terminal and the Software Update modal's Upgrade button now share the same VNC spawn pipeline, so a failure in one usually reproduces in the other — if the header Terminal opens a blank shell cleanly but the Upgrade modal errors, the problem is upgrade-specific (see "Software Update click shows an error" above).
 
 ## Orphan Account Directory Archived to `.trash/`
 

package/payload/platform/scripts/vnc.sh

@@ -3,7 +3,8 @@
 # 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 | status
+#                | start-terminal | start-terminal-native | start-terminal-upgrade
+#                | kill-terminal | status-terminal | status
 #
 # Components:
 #   Xtigervnc :99        — virtual X11 display + VNC server on port 5900
@@ -430,6 +431,114 @@ start_terminal_native() {
   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
+
+  log "Starting ${bin} ${flags} ${dispatch_flag} bash -c \"${upgrade_cmd}; exec bash\" on ${target_display} (${label}) reason=upgrade"
+
+  # setsid -f detaches from this script's process group so the spawned terminal
+  # survives vnc.sh exiting. Output to TERMINAL_LOG so spawn-time stderr is
+  # captured. $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.
+  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
+
+  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
 
@@ -556,6 +665,10 @@ case "${1:-}" in
     start_terminal_native
     ;;
 
+  start-terminal-upgrade)
+    start_terminal_upgrade
+    ;;
+
   kill-terminal)
     pid="$(terminal_pid)"
     kill_terminal_emulators
@@ -583,7 +696,7 @@ case "${1:-}" in
     ;;
 
   *)
-    echo "Usage: vnc.sh start | stop | start-chrome | start-chrome-native | start-terminal | start-terminal-native | kill-terminal | status-terminal | status" >&2
+    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
     exit 1
     ;;
 esac