@rubytech/create-realagent 1.0.676 → 1.0.678

package/dist/index.js

@@ -2,8 +2,7 @@
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync, cpSync, readFileSync, rmSync, readdirSync, appendFileSync, openSync, closeSync, chmodSync, symlinkSync, unlinkSync, lstatSync, readlinkSync, accessSync, constants as fsConstants } from "node:fs";
 import { resolve, join, dirname } from "node:path";
-import { randomBytes, createHash } from "node:crypto";
-import { TTYD_VERSION, TTYD_SHA256_BY_ARCH, mapUnameToTtydArch, ttydDownloadUrl, } from "./pinned-binaries.js";
+import { randomBytes } from "node:crypto";
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive all brand-specific installation values.
 // The bundler stamps brand.json into the payload at build time.
@@ -366,11 +365,7 @@ function installSystemDeps() {
     // class where PID is alive but no window is mapped on the target display.
     const VNC_DEPS = ["tigervnc-standalone-server", "python3-websockify", "novnc", "xdg-utils", "chromium", "xterm", "xdotool"];
     const WIFI_DEPS = ["hostapd", "dnsmasq"];
-    // 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
-    // pinned upstream binary installed by provisionTtydBinary() in step 11.
-    const TERMINAL_DEPS = ["tmux"];
-    const ALL_APT_DEPS = [...BASE_DEPS, ...VNC_DEPS, ...WIFI_DEPS, ...TERMINAL_DEPS];
+    const ALL_APT_DEPS = [...BASE_DEPS, ...VNC_DEPS, ...WIFI_DEPS];
     // Task 634 — verify the "deps are present" assumption with `dpkg -s` instead
     // of asserting it (feedback_loud_failures.md). The previous silent-skip
     // branch was benign until Task 632 added xdotool (the first new apt dep
@@ -397,7 +392,6 @@ function installSystemDeps() {
         installAptGroup("base utilities", BASE_DEPS);
         installAptGroup("VNC stack", VNC_DEPS);
         installAptGroup("WiFi AP", WIFI_DEPS);
-        installAptGroup("terminal", TERMINAL_DEPS);
     }
     // Hostname resolution — four sources, in priority order:
     //   1. --hostname flag (unconditional — the caller is the authority)
@@ -1674,171 +1668,56 @@ function installCrons() {
         logFile(`  crontab write failed: ${write.stderr}`);
     }
 }
-const TTYD_INSTALL_PATH = "/usr/local/bin/ttyd";
-function sha256File(path) {
-    const hash = createHash("sha256");
-    hash.update(readFileSync(path));
-    return hash.digest("hex");
-}
-// Provision the upstream ttyd binary into /usr/local/bin/ttyd. Degrades with
-// a loud warning and a copy-pasteable remediation command on any failure —
-// never throws. Contract: the caller (installTerminalService) uses the
-// presence of TTYD_INSTALL_PATH after return to decide whether to enable the
-// maxy-ttyd.service systemd unit. ttyd is NOT in Debian Bookworm apt, so we
-// own the full download / verify / install flow here.
-function provisionTtydBinary() {
-    const unameRaw = spawnSync("uname", ["-m"], { encoding: "utf-8", stdio: "pipe", timeout: 5_000 });
-    const uname = (unameRaw.stdout || "").trim();
-    const arch = mapUnameToTtydArch(uname);
-    if (arch === null) {
-        console.error(`  WARNING: ttyd — unsupported architecture 'uname -m'='${uname}'. Admin terminal will be unavailable.`);
-        console.error(`  Remediate: install ttyd ${TTYD_VERSION} manually for your platform and place it at ${TTYD_INSTALL_PATH}, then 'sudo chmod +x ${TTYD_INSTALL_PATH}'.`);
-        return false;
-    }
-    const pinnedDigest = TTYD_SHA256_BY_ARCH[arch];
-    const url = ttydDownloadUrl(arch);
-    const remediation = `curl -L -o /tmp/ttyd.${arch} '${url}' && sudo mv /tmp/ttyd.${arch} ${TTYD_INSTALL_PATH} && sudo chmod +x ${TTYD_INSTALL_PATH}`;
-    // Idempotency: existing binary with matching pinned digest → skip download.
-    if (existsSync(TTYD_INSTALL_PATH)) {
-        try {
-            const existingDigest = sha256File(TTYD_INSTALL_PATH);
-            if (existingDigest === pinnedDigest) {
-                console.log(`  ttyd ${TTYD_VERSION} already installed at ${TTYD_INSTALL_PATH} (SHA256 match — skipping download)`);
-                return true;
-            }
-            console.log(`  ttyd at ${TTYD_INSTALL_PATH} has different digest — replacing with pinned ${TTYD_VERSION}`);
-        }
-        catch (err) {
-            console.error(`  WARNING: could not read existing ${TTYD_INSTALL_PATH}: ${err instanceof Error ? err.message : String(err)} — will overwrite`);
-        }
-    }
-    if (!canSudo()) {
-        console.error(`  WARNING: ttyd — sudo unavailable non-interactively, cannot write ${TTYD_INSTALL_PATH}. Admin terminal will be unavailable.`);
-        console.error(`  Remediate: ${remediation}`);
-        return false;
-    }
-    const tmpPath = `/tmp/ttyd.${arch}`;
-    try {
-        console.log(`  Downloading ttyd ${TTYD_VERSION} for ${arch} from ${url}`);
-        shellRetry("curl", ["-fL", "--retry", "3", "--retry-delay", "5", "-o", tmpPath, url], { timeout: 60_000 });
-    }
-    catch (err) {
-        console.error(`  WARNING: ttyd download failed: ${err instanceof Error ? err.message : String(err)}. Admin terminal will be unavailable.`);
-        console.error(`  Remediate: ${remediation}`);
-        try {
-            unlinkSync(tmpPath);
-        }
-        catch { /* nothing to clean */ }
-        return false;
-    }
-    let actualDigest;
-    try {
-        actualDigest = sha256File(tmpPath);
-    }
-    catch (err) {
-        console.error(`  WARNING: ttyd — could not read downloaded file ${tmpPath}: ${err instanceof Error ? err.message : String(err)}. Admin terminal will be unavailable.`);
-        try {
-            unlinkSync(tmpPath);
-        }
-        catch { /* nothing to clean */ }
-        return false;
+// Task 645 — idempotent tear-down of the Task 591 ttyd/tmux pipeline. Task 643
+// collapsed the admin upgrade and header-Terminal surfaces onto the existing
+// VNC terminal path; the parallel ttyd+xterm.js pipeline became orphan code.
+// Fresh devices never provision it. Devices carrying the Task 591 install
+// get their maxy-ttyd.service stopped, disabled, and removed on the first
+// post-645 installer run. Subsequent runs are silent no-ops — the absence
+// of the unit file short-circuits before any systemctl call is reached.
+function installTerminalService() {
+    log("11", TOTAL, "Removing legacy admin terminal service (maxy-ttyd)...");
+    if (!isLinux()) {
+        return;
     }
-    if (actualDigest !== pinnedDigest) {
-        console.error(`  WARNING: ttyd SHA256 mismatch — refusing to install unverified binary.`);
-        console.error(`    expected: ${pinnedDigest}`);
-        console.error(`    actual:   ${actualDigest}`);
-        console.error(`  Admin terminal will be unavailable. A later installer version may pin a newer digest.`);
-        try {
-            unlinkSync(tmpPath);
-        }
-        catch { /* nothing to clean */ }
-        return false;
+    const homeDir = process.env.HOME ?? "/root";
+    const unitPath = resolve(homeDir, ".config/systemd/user/maxy-ttyd.service");
+    if (!existsSync(unitPath)) {
+        return;
     }
-    console.log(`  ttyd ${TTYD_VERSION} SHA256 verified (${actualDigest.slice(0, 12)}…)`);
+    console.error("  [installer] maxy-ttyd: stopping and removing stale service (Task 645 orphan cleanup)");
+    // Stop and disable are best-effort — systemctl returns non-zero on a unit
+    // that's already inactive or never enabled, which is fine. stdio: "pipe"
+    // keeps the operator terminal clean; diagnostics go to the installer log
+    // via spawnSync's return if anyone needs them.
+    spawnSync("systemctl", ["--user", "stop", "maxy-ttyd"], { stdio: "pipe", timeout: 10_000 });
+    spawnSync("systemctl", ["--user", "disable", "maxy-ttyd"], { stdio: "pipe", timeout: 10_000 });
     try {
-        shell("mv", [tmpPath, TTYD_INSTALL_PATH], { sudo: true });
-        shell("chmod", ["+x", TTYD_INSTALL_PATH], { sudo: true });
+        unlinkSync(unitPath);
     }
     catch (err) {
-        console.error(`  WARNING: ttyd — could not install to ${TTYD_INSTALL_PATH}: ${err instanceof Error ? err.message : String(err)}. Admin terminal will be unavailable.`);
-        console.error(`  Remediate: ${remediation}`);
-        try {
-            unlinkSync(tmpPath);
-        }
-        catch { /* already moved or cleaned */ }
-        return false;
-    }
-    console.log(`  ttyd ${TTYD_VERSION} installed at ${TTYD_INSTALL_PATH}`);
-    return true;
-}
-function installTerminalService() {
-    log("11", TOTAL, "Installing admin terminal service (ttyd + tmux)...");
-    if (!isLinux()) {
-        console.log("  Skipping admin terminal service (not Linux). On macOS start manually:");
-        console.log("    brew install ttyd tmux && ttyd -p 7681 -i 127.0.0.1 -W tmux new-session -A -s maxy-pty");
+        console.error(`  WARNING: could not remove ${unitPath}: ${err instanceof Error ? err.message : String(err)}`);
         return;
     }
-    // ttyd is provisioned from upstream GitHub releases (pinned + SHA256-verified)
-    // because Debian Bookworm's apt does NOT carry a ttyd package (Task 602).
-    // A failure here is loud but non-fatal — the rest of the install completes
-    // and the admin UI degrades to "terminal unavailable" per Task 603.
-    const ttydReady = provisionTtydBinary();
-    // Default ~/.tmux.conf — only written if the operator doesn't already have
-    // one. `history-limit 50000` is load-bearing: a closed-tab + reopen during
-    // an upgrade must show every line the operator missed in scrollback.
-    const homeDir = process.env.HOME ?? "/root";
+    spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "pipe", timeout: 10_000 });
+    // ~/.tmux.conf cleanup: only remove if the contents match what the installer
+    // seeded (exact template or exact fallback). Anything else = operator-owned,
+    // leave untouched. Matches the Task 645 brief: "if the installer owned it,
+    // it's been removed; if the operator owns it, untouched."
     const tmuxConfDest = resolve(homeDir, ".tmux.conf");
-    if (!existsSync(tmuxConfDest)) {
-        const tmuxConfTemplate = resolve(INSTALL_DIR, "platform/templates/dotfiles/.tmux.conf");
+    if (existsSync(tmuxConfDest)) {
         try {
-            if (existsSync(tmuxConfTemplate)) {
-                writeFileSync(tmuxConfDest, readFileSync(tmuxConfTemplate, "utf-8"));
-                console.log(`  Wrote default ~/.tmux.conf (history-limit 50000)`);
-            }
-            else {
-                // Fallback if the template was not in the payload for any reason —
-                // preserves the load-bearing scrollback-size guarantee.
-                writeFileSync(tmuxConfDest, "set -g history-limit 50000\n");
-                console.log(`  Wrote default ~/.tmux.conf (fallback — template missing)`);
+            const contents = readFileSync(tmuxConfDest, "utf-8");
+            const seededFallback = "set -g history-limit 50000\n";
+            if (contents === seededFallback) {
+                unlinkSync(tmuxConfDest);
+                console.log("  Removed installer-seeded ~/.tmux.conf (orphan after Task 645)");
             }
         }
         catch (err) {
-            console.error(`  WARNING: failed to write ~/.tmux.conf: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-    // Install and enable the maxy-ttyd.service --user unit. Independent of
-    // BRAND.serviceName — a single device runs one admin terminal regardless of
-    // brand, because the unit binds to 127.0.0.1:7681 which only one process can
-    // hold anyway. On a multi-brand device, the first brand's install writes the
-    // unit and every subsequent install is a no-op (idempotent overwrite).
-    const systemdUserDir = resolve(homeDir, ".config/systemd/user");
-    mkdirSync(systemdUserDir, { recursive: true });
-    // Skip systemd-unit install if the ttyd binary is not in place — enabling
-    // a unit whose ExecStart points at a missing file just churns systemd with
-    // restart failures.
-    if (!ttydReady) {
-        console.error("  Skipping maxy-ttyd.service install — ttyd binary not present. Admin terminal will be unavailable until remediated.");
-        return;
-    }
-    const ttydUnitTemplate = resolve(INSTALL_DIR, "platform/templates/systemd/maxy-ttyd.service");
-    const ttydUnitDest = join(systemdUserDir, "maxy-ttyd.service");
-    try {
-        if (existsSync(ttydUnitTemplate)) {
-            writeFileSync(ttydUnitDest, readFileSync(ttydUnitTemplate, "utf-8"));
+            console.error(`  WARNING: could not inspect ~/.tmux.conf: ${err instanceof Error ? err.message : String(err)}`);
         }
-        else {
-            console.error(`  WARNING: maxy-ttyd.service template missing at ${ttydUnitTemplate} — admin terminal will not work`);
-            return;
-        }
-    }
-    catch (err) {
-        console.error(`  WARNING: failed to write ${ttydUnitDest}: ${err instanceof Error ? err.message : String(err)}`);
-        return;
     }
-    spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "inherit" });
-    spawnSync("systemctl", ["--user", "enable", "maxy-ttyd"], { stdio: "inherit" });
-    spawnSync("systemctl", ["--user", "restart", "maxy-ttyd"], { stdio: "inherit" });
-    console.log("  maxy-ttyd.service enabled — admin terminal available on 127.0.0.1:7681");
 }
 function installService() {
     log("12", TOTAL, `Starting ${BRAND.productName}...`);
@@ -1914,27 +1793,32 @@ function installService() {
     // Propagate to child processes — seed-neo4j.sh reads both variables.
     process.env.EMBED_DIMENSIONS = String(EMBED_DIMS);
     process.env.NEO4J_URI = `bolt://localhost:${NEO4J_PORT}`;
+    // Task 647: maxy-ui runs on an internal-only port so a restart does not
+    // drop the public TCP socket. maxy-edge.service owns the public port and
+    // the VNC stack; maxy-ui sits behind it on 127.0.0.1:MAXY_UI_INTERNAL_PORT.
+    // PORT + 1 (derived) avoids a fixed-port collision if the operator chose a
+    // non-default --port.
+    const MAXY_UI_INTERNAL_PORT = PORT + 1;
     const neo4jServiceDep = NEO4J_DEDICATED ? `neo4j-${BRAND.hostname}.service` : "neo4j.service";
     const serviceFile = `[Unit]
 Description=${BRAND.productName} AI Assistant
-After=${neo4jServiceDep}
+After=${neo4jServiceDep} maxy-edge.service
+Wants=maxy-edge.service
 
 [Service]
 Type=notify
 NotifyAccess=all
 WorkingDirectory=${INSTALL_DIR}/server
-ExecStartPre=/bin/bash ${INSTALL_DIR}/platform/scripts/vnc.sh start
 ExecStartPre=-/bin/bash ${INSTALL_DIR}/platform/scripts/resume-tunnel.sh
 ExecStart=/usr/bin/node --require ./server-init.cjs server.js
-ExecStopPost=/bin/bash ${INSTALL_DIR}/platform/scripts/vnc.sh stop
 Restart=on-failure
 RestartSec=5
 WatchdogSec=30
 TimeoutStartSec=60
 TimeoutStopSec=10
 Environment=NODE_ENV=production
-Environment=PORT=${PORT}
-Environment=HOSTNAME=0.0.0.0
+Environment=PORT=${MAXY_UI_INTERNAL_PORT}
+Environment=HOSTNAME=127.0.0.1
 Environment=KEEP_ALIVE_TIMEOUT=61000
 Environment=DISPLAY=:99
 Environment=PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium
@@ -1948,6 +1832,24 @@ StandardError=append:${persistDir}/logs/server.log
 WantedBy=default.target
 `;
     writeFileSync(join(serviceDir, BRAND.serviceName), serviceFile);
+    // Task 647 — maxy-edge.service: the always-on front door that owns the
+    // public port (PORT) and the VNC stack (Xtigervnc + websockify). Its
+    // lifecycle is independent of maxy-ui, so an in-place upgrade triggered
+    // from the admin terminal can restart maxy-ui without disconnecting the
+    // browser's remote terminal WebSocket.
+    const edgeTemplatePath = resolve(INSTALL_DIR, "platform/templates/systemd/maxy-edge.service");
+    if (existsSync(edgeTemplatePath)) {
+        const edgeServiceContent = readFileSync(edgeTemplatePath, "utf-8")
+            .replace(/__INSTALL_DIR__/g, INSTALL_DIR)
+            .replace(/__EDGE_PORT__/g, String(PORT))
+            .replace(/__MAXY_UI_PORT__/g, String(MAXY_UI_INTERNAL_PORT))
+            .replace(/__PERSIST_DIR__/g, persistDir);
+        writeFileSync(join(serviceDir, "maxy-edge.service"), edgeServiceContent);
+        logFile(`  maxy-edge.service: EDGE_PORT=${PORT} MAXY_UI_PORT=${MAXY_UI_INTERNAL_PORT}`);
+    }
+    else {
+        console.error(`  WARNING: maxy-edge.service template missing at ${edgeTemplatePath} — remote terminal will disconnect during upgrade`);
+    }
     // Task 560: the unit declares Environment=PATH=%h/.local/bin:... so the graph
     // MCP shim's spawn("uvx", ...) resolves against uv's install location. Without
     // this line, the service inherits the default systemd-user PATH — which
@@ -2000,10 +1902,19 @@ WantedBy=multi-user.target
         spawnSync("sudo", ["loginctl", "enable-linger", currentUser], { stdio: "inherit" });
     }
     catch { /* not critical */ }
-    // Reload and (re)start
+    // Reload and (re)start.
+    //
+    // Task 647 ordering: on upgrades, the old maxy-ui still holds the public
+    // port (PORT). Stop it FIRST so maxy-edge can bind that socket; starting
+    // maxy-edge first would race against the old maxy-ui and fail with EADDRINUSE.
+    // Fresh installs: the stop is a no-op.
     const unitName = BRAND.serviceName.replace(".service", "");
+    spawnSync("systemctl", ["--user", "stop", unitName], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "enable", "maxy-edge"], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "enable", unitName], { stdio: "inherit" });
+    // maxy-edge first: binds public port + starts VNC stack. Then maxy-ui.
+    spawnSync("systemctl", ["--user", "restart", "maxy-edge"], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "restart", unitName], { stdio: "inherit" });
     // Wait for the server to come up
     console.log("  Waiting for web server...");
@@ -2383,7 +2294,7 @@ try {
     setupVncViewer();
     setupAccount();
     installTunnelScripts(); // ~/setup-tunnel.sh, ~/reset-tunnel.sh — the SKILL contract
-    installTerminalService(); // Task 591: ttyd + tmux systemd --user unit (sibling of maxy-ui)
+    installTerminalService(); // Task 645: tears down Task 591's orphan maxy-ttyd.service on upgrades
     installService();
     console.log("");
     console.log("================================================================");

package/dist/uninstall.js

@@ -92,6 +92,15 @@ function stopServices() {
     catch {
         console.log(`  ${BRAND.serviceName} not running`);
     }
+    // Task 647: maxy-edge owns the public port and VNC stack. Stop it after
+    // maxy-ui so the edge's ExecStopPost (vnc.sh stop) runs cleanly.
+    try {
+        spawnSync("systemctl", ["--user", "stop", "maxy-edge"], { stdio: "pipe", timeout: 15_000 });
+        console.log("  Stopped maxy-edge");
+    }
+    catch {
+        console.log("  maxy-edge not running");
+    }
     // Stop Neo4j
     try {
         spawnSync("sudo", ["systemctl", "stop", "neo4j"], { stdio: "pipe", timeout: 15_000 });
@@ -462,6 +471,21 @@ function removeSystemdService() {
             console.log(`  Failed to remove service file: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // Task 647: remove maxy-edge.service alongside maxy-ui.
+    try {
+        spawnSync("systemctl", ["--user", "disable", "maxy-edge"], { stdio: "pipe" });
+    }
+    catch { /* ignore */ }
+    const edgeServiceFile = resolve(HOME, ".config/systemd/user/maxy-edge.service");
+    if (existsSync(edgeServiceFile)) {
+        try {
+            rmSync(edgeServiceFile);
+            console.log("  Removed maxy-edge.service");
+        }
+        catch (err) {
+            console.log(`  Failed to remove maxy-edge.service: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     // Reload daemon
     try {
         spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "pipe" });

package/package.json

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

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

@@ -68,12 +68,11 @@ The logs will show which service failed to start and why. Common causes:
 
 ## Systemd units on each device
 
-Each Maxy device runs two independent `--user` systemd units:
+Each Maxy device runs one `--user` systemd unit:
 
 - `maxy-ui.service` — the admin + public HTTP server (default port 19200). Restarted by the upgrade flow; short downtime is expected during steps 8→12 of an upgrade.
-- `maxy-ttyd.service` — a persistent PTY over WebSocket on `127.0.0.1:7681` attached to a tmux session named `maxy-pty`. Independent of `maxy-ui` — restarting the UI does not interrupt shell work, which is exactly the property the upgrade flow relies on to survive its own admin-server restart. The `ttyd` binary is installed at `/usr/local/bin/ttyd` from a pinned upstream GitHub release (SHA256-verified by the installer). It is NOT an apt package — Raspberry Pi OS (Bookworm-based) does not ship `ttyd` in apt.
 
-If the Software Update window's terminal goes blank and does not reconnect, `sudo systemctl --user status maxy-ttyd` is the first thing to check. Restarting the unit (`sudo systemctl --user restart maxy-ttyd`) is safe: the tmux session survives because `tmux new-session -A -s maxy-pty` is idempotent.
+The admin terminal (header Terminal button and Software Update window) runs inside the VNC framebuffer — a `gnome-terminal`/`xterm` process spawned on display `:99` or the operator's native session and rendered in the admin UI via a noVNC iframe. The terminal is ephemeral and does not have its own systemd unit. If the Software Update window fails to open or the terminal doesn't appear, check `sudo tail -n 50 ~/.maxy/logs/terminal-launch.log` — the VNC stack and spawn pipeline are the only components involved.
 
 ## Upgrading
 

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

@@ -311,6 +311,10 @@ Separate from the knowledge retrieval pipeline, `conversation-search` provides s
 
 This tool is read-only and available to both public and admin agents.
 
+### When conversations are created
+
+`:Conversation` nodes on webchat (admin login, "New conversation" in the burger, a new public visitor) are created lazily. Opening the chat or logging in does not write anything to the graph — Maxy only records the conversation once the user sends a second message. This keeps `conversation-search` and the Conversations modal free of one-turn abandoned threads. WhatsApp and Telegram take the opposite posture: a first inbound DM is a committed interaction, so the graph node is created eagerly on message one. See `.docs/web-chat.md` "Deferred conversation persistence (Task 650)" for the full contract.
+
 ---
 
 ## Context Assembly — How Retrieved Knowledge Reaches the Agent

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

@@ -52,7 +52,7 @@ The memory graph is stored on your Pi. It never leaves your network.
 
 ## The Web Interface
 
-The web app runs on your Pi on port 19200. It provides:
+The web app runs on your Pi on port 19200. A small always-on front door (`maxy-edge`) owns that port and the remote terminal transport — so when the Software Update command restarts the app server, the browser-side terminal keeps streaming bytes exactly like an SSH session would. It provides:
 
 - **Admin chat** (at `/`) — your primary interface, PIN-protected
 - **Public chat** (at `/{agent-name}`) — visitor-facing agents, each with their own URL. On public hostnames, the root path serves the default agent.

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

@@ -124,7 +124,7 @@ DISPLAY=:99 xdpyinfo >/dev/null 2>&1 && echo "display :99 ok" || echo "display d
 **Common upgrade-specific failures:**
 
 - `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="spawn detached but no terminal PID visible within 1s" ... reason=upgrade` → X server on `:99` is wedged. Since Task 647 the VNC stack is owned by `maxy-edge`, so the recovery is `sudo systemctl --user restart maxy-edge` (cycles `vnc.sh start` via that unit's ExecStartPre). 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.
@@ -158,7 +158,7 @@ If the `cmd=` field does not contain `-e bash -c`, re-run the installer — the
 
 **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:** `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.
+**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`. This is a VNC-stack or display-spawn failure.
 
 Step-by-step diagnosis:
 

package/payload/platform/scripts/vnc.sh

@@ -212,9 +212,8 @@ start_chrome() {
 #      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 — matches the operator invariant
-# "no ttyd fallback, no silent substitution" from Task 627. gnome-terminal
-# retains `--wait` (see Task 627 pgrep-visibility fix). xterm takes no flag.
+# 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
@@ -494,17 +493,39 @@ start_terminal_upgrade_on() {
       ;;
   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
+  # 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
-    DISPLAY="${target_display}" setsid -f "$bin" "$dispatch_flag" bash -c "$bash_wrapper" >> "$TERMINAL_LOG" 2>&1 || true
+    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

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

@@ -0,0 +1,33 @@
+[Unit]
+Description=Maxy Edge (public port + VNC transport — independent of maxy-ui)
+# No ordering dependency on maxy-ui: the edge is the long-running front door.
+# maxy-ui.service declares Wants/After this unit so maxy-ui only starts once
+# the edge is listening, but this unit has no such reciprocal dependency.
+
+[Service]
+Type=simple
+# ExecStartPre owns the VNC stack so an `npx -y @rubytech/create-maxy@latest`
+# run from the admin terminal can restart maxy-ui without taking Xtigervnc,
+# websockify, or the upgrade shell down with it. Task 647.
+ExecStartPre=/bin/bash __INSTALL_DIR__/platform/scripts/vnc.sh start
+ExecStart=/usr/bin/node __INSTALL_DIR__/server/maxy-edge.js
+ExecStopPost=/bin/bash __INSTALL_DIR__/platform/scripts/vnc.sh stop
+Restart=on-failure
+RestartSec=5
+TimeoutStartSec=60
+TimeoutStopSec=10
+Environment=NODE_ENV=production
+Environment=EDGE_PORT=__EDGE_PORT__
+Environment=EDGE_HOSTNAME=0.0.0.0
+Environment=MAXY_UI_HOST=127.0.0.1
+Environment=MAXY_UI_PORT=__MAXY_UI_PORT__
+Environment=WEBSOCKIFY_HOST=127.0.0.1
+Environment=WEBSOCKIFY_PORT=6080
+Environment=DISPLAY=:99
+Environment=MAXY_PLATFORM_ROOT=__INSTALL_DIR__/platform
+Environment=PATH=%h/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+StandardOutput=append:__PERSIST_DIR__/logs/edge.log
+StandardError=append:__PERSIST_DIR__/logs/edge.log
+
+[Install]
+WantedBy=default.target

package/payload/server/maxy-edge.js

@@ -401,6 +401,8 @@ function forwardUpgrade(req, clientSocket, head) {
 var server = createServer((req, res) => {
   forwardHttp(req, res);
 });
+server.keepAliveTimeout = parseInt(process.env.KEEP_ALIVE_TIMEOUT ?? "61000", 10);
+server.headersTimeout = server.keepAliveTimeout + 1e3;
 attachVncWsProxy(server, {
   isPublicHost,
   upstreamHost: WEBSOCKIFY_HOST,