@rubytech/create-realagent 1.0.663 → 1.0.665

package/dist/index.js

@@ -219,7 +219,11 @@ function installSystemDeps() {
     if (canSudo()) {
         shell("apt-get", ["update"], { sudo: true });
         shell("apt-get", ["install", "-y", "curl", "git", "unzip", "jq", "avahi-daemon", "avahi-utils", "poppler-utils", "ffmpeg"], { sudo: true });
-        shell("apt-get", ["install", "-y", "tigervnc-standalone-server", "python3-websockify", "novnc", "xdg-utils", "chromium"], { sudo: true });
+        // xterm is the fallback terminal-emulator binary for the VNC-rendered
+        // Terminal surface (Task 627). Always installed to guarantee vnc.sh
+        // start-terminal has a binary to spawn on Bookworm Pis where
+        // gnome-terminal is not preinstalled (avoids pulling ~180MB of GNOME).
+        shell("apt-get", ["install", "-y", "tigervnc-standalone-server", "python3-websockify", "novnc", "xdg-utils", "chromium", "xterm"], { sudo: true });
         shell("apt-get", ["install", "-y", "hostapd", "dnsmasq"], { sudo: true });
         // tmux backs the admin terminal's persistent named session (Task 591).
         // ttyd is NOT in Debian Bookworm's apt repo (Task 602) — it ships as a

package/package.json

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

package/payload/platform/neo4j/schema.cypher

@@ -263,6 +263,13 @@ ON EACH [k.summary, k.content];
 // (Conversation)-[:BELONGS_TO]->(LocalBusiness).
 // Public conversations carry a visitorId (browser cookie) and
 // agentSlug for session resume across page reloads and server restarts.
+// Task 621 — carries a `summary` string denormalised from the first
+// user-role message (first 200 chars, set once, no overwrites) to
+// provide a stable human-identifiable label on the /graph canvas.
+// Conversations that never receive a user message (assistant-only
+// seed, etc.) leave `summary` NULL; the /graph client's pickShortLabel
+// falls back to `Conv <shortId>` so empty conversations stay
+// distinguishable from each other.
 // ----------------------------------------------------------
 
 CREATE CONSTRAINT conversation_id_unique IF NOT EXISTS
@@ -297,7 +304,13 @@ OPTIONS {
 
 // ----------------------------------------------------------
 // Message node — individual messages within a Conversation
-// Linked via (Message)-[:PART_OF]->(Conversation).
+// Linked via (Message)-[:PART_OF]->(Conversation) to the parent.
+// Linked via (Message)-[:NEXT]->(Message) to the next message in
+// insertion order (Task 621). The chain is linear — one outgoing
+// NEXT per message — so a Conversation with N messages has N-1
+// NEXT edges. Concurrent writes against the same Conversation
+// CAN fork the chain under Neo4j's READ_COMMITTED default; tracked
+// under Task 624.
 // Vector-indexed for semantic search over conversation history.
 // ----------------------------------------------------------
 
@@ -615,6 +628,26 @@ FOR (au:AdminUser) REQUIRE au.userId IS UNIQUE;
 CREATE INDEX graph_preference_account_user IF NOT EXISTS
 FOR (p:GraphPreference) ON (p.accountId, p.userId);
 
+// ----------------------------------------------------------
+// ReviewAlert — review-detector rule-match aggregation
+//
+// One alert per (accountId, ruleId); subsequent rule matches bump
+// lastMatchAt and cumulativeMatchCount via ON MATCH. Written by
+// platform/ui/app/lib/review-detector/writer.ts, read by the admin
+// chat's alert-surfacing tools. Listed in FILTER_EXCLUDED_LABELS
+// (graph-labels.ts, Task 626) so it never surfaces as a /graph filter
+// row, but registered in GRAPH_LABEL_COLOURS so neighbourhood-mode
+// drilldown / search hits can still render it.
+//
+// Composite MERGE key (accountId, ruleId) — no UNIQUE constraint for
+// the same reason as GraphPreference: the composite MERGE is
+// idempotent and a composite constraint would add schema surface
+// for no behavioural gain.
+// ----------------------------------------------------------
+
+CREATE INDEX review_alert_account_rule IF NOT EXISTS
+FOR (a:ReviewAlert) ON (a.accountId, a.ruleId);
+
 // ----------------------------------------------------------
 // ToolCall — durable audit trail for agent tool invocations
 //

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

@@ -84,9 +84,9 @@ 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 node types that actually exist in your graph (so you won't see chips for types you've never written). Active chips render a force-directed map, coloured by label (Person, Service, KnowledgeDocument, Task, …). Click a node to see its properties and explore its neighbourhood; click the **Back** control or empty canvas to return to your filter view with the same chips still selected. Type in the search box to highlight matches.
+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 node types that actually exist in your graph, one row per type, showing your per-type node count and sorted so the most-connected types sit at the top. Leaf types that only appear inside a parent (messages inside a conversation, sections inside a document) are never filter rows — you reach them by clicking the parent and exploring its neighbourhood. Infrastructural types (`ToolCall`, `WorkflowRun`, `WorkflowStep`, `ReviewAlert`) never appear as filter rows — the first three are execution plumbing, and `ReviewAlert` has its own dedicated surface in admin chat. Active rows render a force-directed map, coloured by label (Person, Service, KnowledgeDocument, Task, …). Click a node to see its properties and explore its neighbourhood; click the **Back** control or empty canvas to return to your filter view with the same rows still selected. 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. The **×** buttons on the search box and inside the filter menu clear the current search and the current selection respectively — clearing the filter selection does not touch your saved default.
 
-**Save a default view:** once you have the chips you want, click **Set default view** in the filter menu. Next time you open **Graph**, those chips are pre-selected and your data renders immediately. The default is per-admin, per-account — each admin on each account has their own.
+**Save a default view:** once you have the rows you want, click **Set default view** in the filter menu. Next time you open **Graph**, those rows are pre-selected and your data renders immediately. The default is per-admin, per-account — each admin on each account has their own.
 
 **Delete a node:** drag it to the trash icon top-right of the canvas. No confirmation — deletes are reversible for 30 days. To restore, toggle **Show trashed** inside the filter menu and click **Restore** on the node, or ask Maxy in chat ("restore the <label> I just deleted").
 

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

@@ -72,7 +72,7 @@ The Software Update window mounts the terminal lazily: neither the terminal, its
 
 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.
 
-The terminal also opens as a standalone header-menu surface. The burger menu in the admin chat includes a **Terminal** entry next to **Browser**; clicking it mounts a fullscreen overlay that attaches to the same `maxy-pty` tmux session. This surface is pure attach — no upgrade command is sent — so you can run arbitrary shell work without touching the Software Update flow. Closing the overlay (Escape or the `×` button) detaches from tmux; the session on the Pi keeps running, and re-opening re-attaches with full scrollback intact. Both surfaces can be open simultaneously and show the same session via tmux's native multi-attach. Authorisation is identical to the upgrade surface: the same `canAccessAdmin()` gate + same-origin check + public-host rejection the WebSocket proxy enforces for every client. If `ttyd` is unreachable, the overlay renders the same inline "Remote terminal not available" message with a Try again button; server-side you discriminate surfaces via `grep corrId=header-overlay ~/.maxy/logs/terminal.log` (the upgrade modal uses `corrId=upgrade-modal`).
+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 (gnome-terminal on desktops that ship it, xterm elsewhere) on the VNC virtual display `:99` via the same `/vnc-viewer.html` iframe that Browser uses. The header Terminal is isomorphic to the header Browser: one pipeline (launch endpoint → display spawn → 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) and to `vnc-boot.log` via `vncLog('ensure-terminal', ...)` (Node-side state machine), mirroring the Browser's `ensure-cdp` observability shape.
 
 ## AI Content Provenance
 

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

@@ -142,18 +142,36 @@ In `terminal.log`, look for `terminal-proxy-flow` lines — they're emitted ever
 
 **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.
 
-## Terminal menu item renders an empty rectangle
+## Header Terminal click shows an error alert
 
-**Symptom:** You opened the burger menu, clicked **Terminal**, and the fullscreen overlay mounted but the body area stayed black for more than a second or two — no prompt, no scrollback, just an empty rectangle where the shell should be.
+**Symptom:** You opened the burger menu and clicked **Terminal**, but instead of the overlay appearing you got an inline error like "Terminal failed to start" or "VNC failed to start".
 
-**What it means:** `ttyd` on `127.0.0.1:7681` is not accepting the WebSocket, so `RemoteTerminal` cannot attach to `maxy-pty`. If `maxy-ttyd.service` is unreachable for long enough, the overlay flips to an inline "Remote terminal not available" message with a **Try again** button — but before that trips you get the empty-rectangle window. The quickest check is the same one used for the Software Update path:
+**What it means:** `POST /api/admin/terminal/launch` returned a 502 — either the VNC stack on port 5900 is down or the terminal emulator could not be spawned on display `:99`. The header Terminal is decoupled from `ttyd`; this is a VNC-stack or display-spawn failure, not an upgrade-terminal problem.
+
+Step-by-step diagnosis:
 
 ```bash
-sudo systemctl --user status maxy-ttyd
-sudo tail -n 50 ~/.maxy/logs/terminal.log
+# 1. Check the terminal-launch log for the specific failure reason
+sudo tail -n 50 ~/.maxy/logs/terminal-launch.log
+
+# 2. Check the node-side state machine (ensure-terminal entries)
+sudo grep ensure-terminal ~/.maxy/logs/vnc-boot.log | tail -20
+
+# 3. Verify the VNC display itself is healthy
+sudo ~/maxy/platform/scripts/vnc.sh status   # should print "running"
+DISPLAY=:99 xdpyinfo >/dev/null 2>&1 && echo "display ok" || echo "display dead"
+
+# 4. Confirm a terminal binary is installed (xterm is the always-available fallback)
+which gnome-terminal; which xterm
 ```
 
-Filter the log to this surface specifically: `grep corrId=header-overlay ~/.maxy/logs/terminal.log` — the Software Update window uses `corrId=upgrade-modal`, so the discriminator lets you tell which client hit the problem. A healthy open looks like `proxy-open corrId=header-overlay` followed by `proxy-flow` heartbeats every 5s; an unreachable backend looks like `proxy-error side=upstream-connect err=ECONNREFUSED`. If `maxy-ttyd` is not running, restart it with `sudo systemctl --user restart maxy-ttyd`, close the overlay, and reopen it from the burger menu — `tmux new-session -A` is idempotent so your session and scrollback come back intact.
+Most common failures and fixes:
+
+- `[terminal-launch] failed err="no terminal emulator installed"` → run `sudo apt-get install -y xterm` (or re-run the installer, which installs xterm as a dependency).
+- `[terminal-launch] failed err="spawn detached but no terminal PID visible within 1s"` → X server on `:99` is wedged. `sudo systemctl --user restart maxy-ui` cycles the VNC stack via `vnc.sh start`.
+- `ensure-terminal action="escalate-vnc-restart"` followed by `degraded` → `Xtigervnc` itself is not coming up. Check `~/.maxy/logs/vnc-boot.log` for the tigervnc startup lines.
+
+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).
 
 ## Orphan Account Directory Archived to `.trash/`
 

package/payload/platform/scripts/vnc.sh

@@ -2,13 +2,18 @@
 # 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 | status
+# Usage: vnc.sh start | stop | start-chrome | start-chrome-native
+#                | start-terminal | start-terminal-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.
 #
 # Display modes (DISPLAY_MODE env var, set by installer --display flag):
 #   virtual (default) — Chromium runs on :99 (VNC virtual display)
@@ -33,13 +38,19 @@ 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
@@ -170,6 +181,143 @@ start_chrome() {
   start_chrome_on ":99" "vnc"
 }
 
+# ---------------------------------------------------------------------------
+# Terminal emulator lifecycle (Task 627) — isomorphic to Chromium's.
+# ---------------------------------------------------------------------------
+
+# Resolve the preferred terminal binary + its required flags. Prefers
+# gnome-terminal on desktops that ship it (Ubuntu), falls back to xterm
+# (Bookworm minimum). Prints "<bin>\t<flags>" on stdout (tab-separated), or
+# exits non-zero with a loud-fail log if neither is installed — matches the
+# operator invariant "no ttyd fallback, no silent substitution" from Task 627.
+#
+# gnome-terminal needs `--wait` because its /usr/bin/gnome-terminal entry is a
+# python D-Bus launcher that forks `/usr/bin/gnome-terminal.real` and would
+# otherwise exit seconds after dispatch — leaving our pgrep-based liveness
+# probe blind while the actual window (owned by gnome-terminal-server) is
+# still on screen. With --wait, both the python wrapper and .real stay alive
+# for the duration of the shell session. xterm is a single-process emulator
+# and needs no flag.
+resolve_terminal_bin() {
+  if [ -x /usr/bin/gnome-terminal ]; then
+    printf '%s\t%s\n' '/usr/bin/gnome-terminal' '--wait'
+    return 0
+  fi
+  if [ -x /usr/bin/xterm ]; then
+    printf '%s\t%s\n' '/usr/bin/xterm' ''
+    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
+}
+
+# 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, do not spawn another.
+  # Matches ensureCdp's "CDP up → return true" branch. Display-switch is
+  # the caller's responsibility (ensureTerminal in vnc.ts kills first).
+  if terminal_alive; then
+    local existing_pid
+    existing_pid="$(terminal_pid)"
+    tlog "already-running pid=${existing_pid} display=${target_display}"
+    log "Terminal already running pid=${existing_pid} (${label})"
+    return 0
+  fi
+
+  local resolved bin flags
+  if ! resolved="$(resolve_terminal_bin)"; then
+    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 pid
+    pid="$(terminal_pid)"
+    tlog "started pid=${pid} display=${target_display} cmd=\"${bin} ${flags}\" transport=${label}"
+    log "Terminal ready (${label}) pid=${pid}"
+    return 0
+  else
+    tlog "failed err=\"spawn detached but no terminal PID visible within 1s\" transport=${label} cmd=\"${bin} ${flags}\""
+    log "ERROR: terminal failed to appear in pgrep within 1s on ${target_display} (${label}) — investigate setsid -f detachment / --wait flag"
+    return 1
+  fi
+}
+
+start_terminal() {
+  start_terminal_on ":99" "vnc"
+}
+
+start_terminal_native() {
+  discover_native_session
+  start_terminal_on "${NATIVE_DISPLAY}" "native"
+}
+
 start_chrome_native() {
   discover_native_session
 
@@ -279,6 +427,30 @@ case "${1:-}" in
     start_chrome_native
     ;;
 
+  start-terminal)
+    start_terminal
+    ;;
+
+  start-terminal-native)
+    start_terminal_native
+    ;;
+
+  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
@@ -290,7 +462,7 @@ case "${1:-}" in
     ;;
 
   *)
-    echo "Usage: vnc.sh start | stop | start-chrome | start-chrome-native | status" >&2
+    echo "Usage: vnc.sh start | stop | start-chrome | start-chrome-native | start-terminal | start-terminal-native | kill-terminal | status-terminal | status" >&2
     exit 1
     ;;
 esac