@rubytech/create-realagent 1.0.685 → 1.0.687

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.
@@ -347,7 +346,7 @@ function installAptGroup(label, pkgs) {
 // ---------------------------------------------------------------------------
 // Installation steps
 // ---------------------------------------------------------------------------
-const TOTAL = "12";
+const TOTAL = "11";
 function installSystemDeps() {
     log("1", TOTAL, "System dependencies and network...");
     if (!isLinux()) {
@@ -366,12 +365,12 @@ function installSystemDeps() {
     // assertion in vnc.sh check_window_on_display, closing the silent-fail
     // 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"];
-    // Task 657: tmux powers the byte-stream admin terminal. ttyd attaches the
-    // shared `maxy-pty` tmux session, so scrollback survives WS reconnects and
-    // the same session is reused by the header overlay + upgrade modal.
-    const TERMINAL_DEPS = ["tmux"];
+    // Task 664 retired the ttyd/tmux admin terminal stack — upgrades run via
+    // the action runner (systemd-run --user transient units) and no longer
+    // need a shared tmux session. `tmux` was only required by the retired
+    // byte-stream terminal; removing it shrinks the apt footprint.
     const WIFI_DEPS = ["hostapd", "dnsmasq"];
-    const ALL_APT_DEPS = [...BASE_DEPS, ...VNC_DEPS, ...TERMINAL_DEPS, ...WIFI_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
@@ -1590,188 +1589,16 @@ function installCrons() {
         logFile(`  crontab write failed: ${write.stderr}`);
     }
 }
-// Task 657 restored the Task-591 ttyd/tmux pipeline after Task 645's
-// tear-down. Rationale: Task 643 collapsed the upgrade surface onto VNC, but
-// the RFB + X-focus path silently drops keystrokes at `[sudo] password for`.
-// The byte-stream surface (ttyd + tmux + xterm.js) is SSH-equivalent — the
-// operator's stated success case — and is now attached to `maxy-edge.service`
-// so the WS transport survives `systemctl --user restart maxy-ui` during an
-// in-browser upgrade (Task 647 invariant holds by construction).
-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;
-    }
-    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;
-    }
-    console.log(`  ttyd ${TTYD_VERSION} SHA256 verified (${actualDigest.slice(0, 12)}…)`);
-    try {
-        console.log(`  [privileged] install ttyd binary to ${TTYD_INSTALL_PATH}`);
-        shell("mv", [tmpPath, TTYD_INSTALL_PATH], { sudo: true });
-        console.log(`  [privileged] chmod +x ${TTYD_INSTALL_PATH}`);
-        shell("chmod", ["+x", TTYD_INSTALL_PATH], { sudo: true });
-    }
-    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");
-        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";
-    const tmuxConfDest = resolve(homeDir, ".tmux.conf");
-    if (!existsSync(tmuxConfDest)) {
-        const tmuxConfTemplate = resolve(INSTALL_DIR, "platform/templates/dotfiles/.tmux.conf");
-        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)`);
-            }
-        }
-        catch (err) {
-            console.error(`  WARNING: failed to write ~/.tmux.conf: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-    // Install and enable the per-brand ttyd --user unit (Task 662). The unit
-    // file name and the loopback port are both brand-scoped so two brands
-    // installed on the same device each run their own ttyd process without
-    // contending for either the filesystem path or the TCP port:
-    //   `${BRAND.hostname}-ttyd.service`  + 127.0.0.1:${BRAND.ttydPort}
-    const systemdUserDir = resolve(homeDir, ".config/systemd/user");
-    mkdirSync(systemdUserDir, { recursive: true });
-    const ttydUnitShort = `${BRAND.hostname}-ttyd`;
-    const ttydUnitName = `${ttydUnitShort}.service`;
-    // 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 ${ttydUnitName} install — ttyd binary not present. Admin terminal will be unavailable until remediated.`);
-        return;
-    }
-    const ttydUnitTemplate = resolve(INSTALL_DIR, "platform/templates/systemd/ttyd.service.template");
-    const ttydUnitDest = join(systemdUserDir, ttydUnitName);
-    try {
-        if (existsSync(ttydUnitTemplate)) {
-            const ttydServiceContent = readFileSync(ttydUnitTemplate, "utf-8")
-                .replace(/__TTYD_PORT__/g, String(TTYD_PORT));
-            writeFileSync(ttydUnitDest, ttydServiceContent);
-            logFile(`  ${ttydUnitName}: TTYD_PORT=${TTYD_PORT}`);
-        }
-        else {
-            console.error(`  WARNING: 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", ttydUnitShort], { stdio: "inherit" });
-    spawnSync("systemctl", ["--user", "restart", ttydUnitShort], { stdio: "inherit" });
-    console.log(`  ${ttydUnitName} enabled — admin terminal available on 127.0.0.1:${TTYD_PORT}`);
-}
+// Task 664 retired the ttyd/tmux/xterm admin terminal stack. Upgrades run
+// via the action runner — `systemd-run --user` transient units spawned by
+// POST /api/admin/actions/upgrade — whose lifetime is independent of
+// maxy-ui, achieving the Task 647 invariant structurally rather than via
+// a peer edge service proxying a ttyd process. The installer no longer
+// provisions the ttyd binary, writes a tmux conf, or installs a ttyd
+// systemd unit. The corresponding admin UI (RemoteTerminal, TerminalOverlay,
+// xterm.js) was deleted in the same task.
 function installService() {
-    log("12", TOTAL, `Starting ${BRAND.productName}...`);
+    log("11", TOTAL, `Starting ${BRAND.productName}...`);
     if (!isLinux()) {
         console.log("  Skipping systemd service (not Linux). Start manually with:");
         console.log(`  cd ${INSTALL_DIR}/server && MAXY_PLATFORM_ROOT=${INSTALL_DIR}/platform PORT=${PORT} HOSTNAME=0.0.0.0 KEEP_ALIVE_TIMEOUT=61000 node --require ./server-init.cjs server.js`);
@@ -1904,13 +1731,12 @@ WantedBy=default.target
             .replace(/__INSTALL_DIR__/g, INSTALL_DIR)
             .replace(/__EDGE_PORT__/g, String(PORT))
             .replace(/__MAXY_UI_PORT__/g, String(MAXY_UI_INTERNAL_PORT))
-            .replace(/__TTYD_PORT__/g, String(TTYD_PORT))
             .replace(/__PERSIST_DIR__/g, persistDir);
         writeFileSync(join(serviceDir, edgeUnitName), edgeServiceContent);
-        logFile(`  ${edgeUnitName}: EDGE_PORT=${PORT} MAXY_UI_PORT=${MAXY_UI_INTERNAL_PORT} TTYD_PORT=${TTYD_PORT}`);
+        logFile(`  ${edgeUnitName}: EDGE_PORT=${PORT} MAXY_UI_PORT=${MAXY_UI_INTERNAL_PORT}`);
     }
     else {
-        console.error(`  WARNING: edge.service.template missing at ${edgeTemplatePath} — remote terminal will disconnect during upgrade`);
+        console.error(`  WARNING: edge.service.template missing at ${edgeTemplatePath} — VNC transport unavailable`);
     }
     // 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
@@ -2328,27 +2154,11 @@ else {
 // Dedicated = port differs from the default shared instance
 const NEO4J_DEDICATED = NEO4J_PORT !== DEFAULT_NEO4J_PORT;
 // ---------------------------------------------------------------------------
-// TTYD port — per-brand loopback so two brands on the same device each run
-// their own ttyd unit on a distinct port (Task 662). Edge service proxies
-// /ttyd to this port via Environment=TTYD_PORT.
-//
-// Priority: --ttyd-port flag > BRAND.ttydPort > 7681. Same pattern as
-// NEO4J_PORT (Task 659).
-// ---------------------------------------------------------------------------
-const DEFAULT_TTYD_PORT = 7681;
-let TTYD_PORT = BRAND.ttydPort ?? DEFAULT_TTYD_PORT;
-let TTYD_PORT_SOURCE = BRAND.ttydPort ? "brand.json" : "default";
-const ttydPortIdx = _args.indexOf("--ttyd-port");
-if (ttydPortIdx !== -1) {
-    const raw = _args[ttydPortIdx + 1];
-    const parsed = raw ? parseInt(raw, 10) : NaN;
-    if (isNaN(parsed) || parsed < 1024 || parsed > 65535) {
-        console.error(`Setup failed: --ttyd-port requires a numeric value between 1024 and 65535 (got: ${raw ?? "nothing"})`);
-        process.exit(1);
-    }
-    TTYD_PORT = parsed;
-    TTYD_PORT_SOURCE = "--ttyd-port flag";
-}
+// Task 664 removed the per-brand ttyd port — the admin terminal stack
+// (ttyd, tmux, xterm.js) was retired in favour of the action runner that
+// spawns transient `systemd-run --user` units per upgrade or setup-tunnel
+// invocation. No TCP listener on the device needs to be reserved for an
+// interactive-shell surface any more.
 const PKG_VERSION = JSON.parse(readFileSync(resolve(import.meta.dirname, "../package.json"), "utf-8")).version;
 initLogging();
 console.log("================================================================");
@@ -2361,7 +2171,6 @@ if (HOSTNAME_FLAG)
 console.log(`  Display: ${DISPLAY_MODE} (${DISPLAY_MODE_SOURCE})`);
 console.log(`  Embed model: ${EMBED_MODEL} (${EMBED_DIMS} dims, ${EMBED_SOURCE})`);
 console.log(`  Neo4j: ${NEO4J_DEDICATED ? "dedicated" : "shared"} on bolt://localhost:${NEO4J_PORT} (${NEO4J_PORT_SOURCE})`);
-console.log(`  ttyd: 127.0.0.1:${TTYD_PORT} (${TTYD_PORT_SOURCE})`);
 console.log("");
 logDiagnostics("pre-flight");
 logFile(`  Neo4j instance: ${NEO4J_DEDICATED ? "dedicated" : "shared"} on bolt://localhost:${NEO4J_PORT}`);
@@ -2382,7 +2191,6 @@ try {
     setupVncViewer();
     setupAccount();
     installTunnelScripts(); // ~/setup-tunnel.sh, ~/reset-tunnel.sh — the SKILL contract
-    installTerminalService(); // Task 657: installs maxy-ttyd.service (ttyd + tmux) for byte-stream admin terminal
     installService();
     console.log("");
     console.log("================================================================");

package/dist/pinned-binaries.js

@@ -1,43 +1,12 @@
 // Pinned upstream binaries installed by the Linux provisioner.
 //
-// Some binaries we depend on are not available in Debian Bookworm's apt repo
-// (e.g. ttyd — entered Debian trixie and Ubuntu 22.04+ but NOT Bookworm, which
-// is the base of current Raspberry Pi OS). For those, we download the upstream
-// prebuilt static binary from GitHub releases, SHA256-verified, and place it
-// under /usr/local/bin. This module is the single source of truth for every
-// such dependency — version bumps are a one-file change.
-//
-// Verification rule: on SHA256 mismatch the installer aborts the download
-// step with a loud error and never writes the binary. No silent-install of
-// unverified bytes. See packages/create-maxy/src/index.ts → provisionTtydBinary.
-export const TTYD_VERSION = '1.7.7';
-// Asset file name as published on github.com/tsl0922/ttyd/releases.
-export const TTYD_ASSET_BY_ARCH = {
-    aarch64: 'ttyd.aarch64',
-    arm: 'ttyd.arm',
-    x86_64: 'ttyd.x86_64',
-};
-// SHA256 digest of each asset for TTYD_VERSION. Computed by downloading the
-// release asset directly from GitHub and running `sha256sum`. Bump together
-// with TTYD_VERSION — never update one without the other.
-export const TTYD_SHA256_BY_ARCH = {
-    aarch64: 'b38acadd89d1d396a0f5649aa52c539edbad07f4bc7348b27b4f4b7219dd4165',
-    arm: '05eac1223914f18c65898d72c8d14e76bbb5435f7762c6dc7f16f041994a8109',
-    x86_64: '8a217c968aba172e0dbf3f34447218dc015bc4d5e59bf51db2f2cd12b7be4f55',
-};
-// Map Linux kernel `uname -m` output to a TtydArch key. Returns null for
-// architectures we have not pinned a binary for — the caller must treat this
-// as a hard error (no silent fallback, no "try latest").
-export function mapUnameToTtydArch(uname) {
-    const trimmed = uname.trim();
-    if (trimmed === 'aarch64' || trimmed === 'arm64')
-        return 'aarch64';
-    if (trimmed === 'armv7l' || trimmed === 'armv6l' || trimmed === 'arm')
-        return 'arm';
-    if (trimmed === 'x86_64' || trimmed === 'amd64')
-        return 'x86_64';
-    return null;
-}
-export function ttydDownloadUrl(arch) {
-    return `https://github.com/tsl0922/ttyd/releases/download/${TTYD_VERSION}/${TTYD_ASSET_BY_ARCH[arch]}`;
-}
+// Task 664 removed the ttyd pin along with the embedded-terminal admin
+// stack. If a future installer step needs to download a pinned binary
+// (as ttyd did, because Debian Bookworm's apt does not carry it), the
+// conventions live here: version constant, SHA256-by-arch map, and a
+// `mapUnameToArch` helper plus a `downloadUrl` builder. SHA256 mismatch
+// must abort with a loud error and never write bytes — no silent
+// install of unverified content. This file is currently empty of
+// entries; it is kept as the canonical location for when the next
+// upstream-pinned binary is added.
+export {};

package/dist/uninstall.js

@@ -85,13 +85,14 @@ export function isMaxyInstalled() {
  *  present — its runtime still depends on those singletons.
  *
  *  Detection: any `.service` file in `~/.config/systemd/user/` whose name is
- *  not this brand's `BRAND.serviceName` and not this brand's own edge/ttyd
- *  unit (Task 662 — each brand owns its own per-brand edge + ttyd unit, so
- *  those files must not register as peer evidence).
+ *  not this brand's `BRAND.serviceName` and not this brand's own edge unit
+ *  (Task 662 — each brand owns its own per-brand edge unit, so that file
+ *  must not register as peer evidence). Task 664 retired the per-brand
+ *  ttyd unit, so it no longer needs an exclusion.
  *
- *  Legacy pre-662 shared `maxy-edge.service` / `maxy-ttyd.service` are
- *  intentionally counted as peer evidence on uninstall: on a dual-brand
- *  pre-662 device the shared unit belonged to whichever brand last ran the
+ *  Legacy pre-662 shared `maxy-edge.service` (and pre-664 `maxy-ttyd.service`)
+ *  are intentionally counted as peer evidence on uninstall: on a dual-brand
+ *  device the legacy shared unit belonged to whichever brand last ran the
  *  installer — treating it as peer evidence keeps the uninstaller from
  *  purging device-wide singletons the other brand still depends on. */
 function peerBrandPresent() {
@@ -99,9 +100,8 @@ function peerBrandPresent() {
     if (!existsSync(systemdUserDir))
         return false;
     const thisBrandEdge = `${BRAND.hostname}-edge.service`;
-    const thisBrandTtyd = `${BRAND.hostname}-ttyd.service`;
     try {
-        return readdirSync(systemdUserDir).some((f) => f.endsWith(".service") && f !== BRAND.serviceName && f !== thisBrandEdge && f !== thisBrandTtyd);
+        return readdirSync(systemdUserDir).some((f) => f.endsWith(".service") && f !== BRAND.serviceName && f !== thisBrandEdge);
     }
     catch {
         return false;
@@ -122,10 +122,12 @@ function stopServices() {
     }
     // Task 647: the edge service owns the public port and VNC stack. Stop it
     // after the main brand service so the edge's ExecStopPost (vnc.sh stop)
-    // runs cleanly. Task 662: the edge unit is per-brand (`<hostname>-edge`),
-    // plus the ttyd unit (`<hostname>-ttyd`) — both must be stopped.
+    // runs cleanly. Task 662: the edge unit is per-brand (`<hostname>-edge`).
+    // Task 664 retired the ttyd unit; pre-664 devices may still have
+    // `<hostname>-ttyd` — best-effort stop so the uninstall is clean on
+    // upgraded devices too.
     const edgeUnitShort = `${BRAND.hostname}-edge`;
-    const ttydUnitShort = `${BRAND.hostname}-ttyd`;
+    const legacyTtydUnitShort = `${BRAND.hostname}-ttyd`;
     try {
         spawnSync("systemctl", ["--user", "stop", edgeUnitShort], { stdio: "pipe", timeout: 15_000 });
         console.log(`  Stopped ${edgeUnitShort}`);
@@ -134,12 +136,10 @@ function stopServices() {
         console.log(`  ${edgeUnitShort} not running`);
     }
     try {
-        spawnSync("systemctl", ["--user", "stop", ttydUnitShort], { stdio: "pipe", timeout: 15_000 });
-        console.log(`  Stopped ${ttydUnitShort}`);
-    }
-    catch {
-        console.log(`  ${ttydUnitShort} not running`);
+        spawnSync("systemctl", ["--user", "stop", legacyTtydUnitShort], { stdio: "pipe", timeout: 15_000 });
+        console.log(`  Stopped ${legacyTtydUnitShort} (legacy pre-664 unit)`);
     }
+    catch { /* not present on post-664 installs */ }
     // Stop Neo4j — dedicated branded instance if this brand uses one, else shared.
     // Brand isolation (Task 659): never stop `neo4j.service` when this brand runs
     // a dedicated `neo4j-<hostname>.service` — stopping the shared instance would
@@ -571,14 +571,14 @@ function removeSystemdService() {
             console.log(`  Failed to remove service file: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    // Task 647 + 662: remove this brand's per-brand edge + ttyd units alongside
-    // the main brand unit. Peer brand's edge/ttyd units live at different
-    // filenames (`<peer-hostname>-edge.service`) and are never touched here.
-    // Legacy pre-662 shared units left on disk by a previous installer are
-    // cleaned up by the installer pre-hygiene loop, not here.
+    // Task 647 + 662: remove this brand's per-brand edge unit alongside the
+    // main brand unit. Task 664 retired the per-brand ttyd unit, but an
+    // upgraded device may still have `<hostname>-ttyd.service` on disk from
+    // a pre-664 install — cleanup both so the uninstall leaves nothing
+    // behind on either generation.
     const thisBrandEdge = `${BRAND.hostname}-edge`;
-    const thisBrandTtyd = `${BRAND.hostname}-ttyd`;
-    for (const unit of [thisBrandEdge, thisBrandTtyd]) {
+    const legacyBrandTtyd = `${BRAND.hostname}-ttyd`;
+    for (const unit of [thisBrandEdge, legacyBrandTtyd]) {
         try {
             spawnSync("systemctl", ["--user", "disable", unit], { stdio: "pipe" });
         }

package/package.json

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

package/payload/platform/plugins/cloudflare/scripts/setup-tunnel.sh

@@ -79,16 +79,19 @@ mkdir -p "${CFG_DIR}"
 if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   phase_line setup-tunnel step=oauth-login cert_path="${CFG_DIR}/cert.pem" display="${DISPLAY:-:99}"
 
-  # CDP precheck — fail loudly if Chromium DevTools is not answering.
+  # CDP precheck — if Chromium DevTools is answering, we'll drive the
+  # Authorize click for the operator. If it isn't (action runner on a
+  # device without VNC — Task 664), we fall back to the ActionLogPanel
+  # URL-to-button flow: extract the URL, emit it as `OAUTH_URL: <url>`,
+  # and wait for cert.pem to land from the operator's own browser click.
+  CDP_AVAILABLE=1
   if ! curl -sf --max-time 2 "http://127.0.0.1:9222/json/version" > /dev/null 2>&1; then
-    phase_line setup-tunnel step=oauth-login result=error reason=cdp-unreachable \
-      endpoint=http://127.0.0.1:9222 hint="run ~/vnc.sh restart"
-    echo "ERROR: Chromium CDP on 127.0.0.1:9222 is not reachable." >&2
-    echo "       The script needs CDP to drive the authorize URL on the VNC browser." >&2
-    echo "       Fix: run 'vnc.sh restart' to bring Chromium up on :99." >&2
-    exit 1
+    phase_line setup-tunnel step=oauth-login cdp=unavailable \
+      endpoint=http://127.0.0.1:9222 mode=operator-browser-fallback
+    CDP_AVAILABLE=0
+  else
+    phase_line setup-tunnel step=oauth-login cdp=ok
   fi
-  phase_line setup-tunnel step=oauth-login cdp=ok
 
   URL_FILE="$(mktemp -t maxy-setup-tunnel-url.XXXXXX)"
   LAST_LINE_FILE="$(mktemp -t maxy-setup-tunnel-last.XXXXXX)"
@@ -154,6 +157,22 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   AUTH_URL="$(cat "${URL_FILE}")"
   phase_line setup-tunnel step=browser-drive url_extracted=1
 
+  # Emit the URL on stdout in a shape ActionLogPanel's regex captures.
+  # Structured-looking enough to route to the "Authorise in Cloudflare"
+  # button on Task 664's admin surface without interfering with the
+  # existing cloudflared-line extraction (which scans the same URL on
+  # stderr from the line above). Emitted before CDP so the button is
+  # available even when CDP succeeds — same-URL clicks are idempotent.
+  printf 'OAUTH_URL: %s\n' "${AUTH_URL}"
+
+  # If CDP isn't available on this device, skip the auto-click branch
+  # and fall through to the cert.pem poll. The operator's own browser
+  # click (via ActionLogPanel's button) hits the same webhook; the
+  # callback writes ~/.cloudflared/cert.pem the moment consent lands,
+  # and the existing LOGIN_TIMEOUT loop below picks it up.
+  if [ "${CDP_AVAILABLE}" -eq 0 ]; then
+    phase_line setup-tunnel step=browser-drive mode=operator-click url="${AUTH_URL}"
+  else
   # Drive CDP. Same PUT /json/new?<url> contract as
   # platform/ui/app/lib/cdp-client.ts (which uses encodeURIComponent on
   # the URL). Without percent-encoding, CDP's URL parser splits on the
@@ -227,6 +246,7 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
     echo "       close the sign-in tab, and re-run setup — or run ~/reset-tunnel.sh first." >&2
     exit 1
   fi
+  fi  # end CDP-available branch (Task 664)
 
   # Wait for cert.pem to land — cloudflared writes to ~/.cloudflared/cert.pem
   # regardless of --origincert, so watch the canonical location. Task 588
@@ -235,7 +255,13 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   # 2-second heartbeat inside the loop is the observability contract for
   # this bounded wait — no form-spawned script is allowed a silent poll of
   # more than ~2 s per criterion 3 of Task 588.
-  LOGIN_TIMEOUT="${SETUP_TUNNEL_LOGIN_TIMEOUT:-20}"
+  # Task 664: operator-click path (no CDP) needs a human-paced window;
+  # CDP auto-click stays on the 20s round-trip budget.
+  if [ "${CDP_AVAILABLE}" -eq 0 ]; then
+    LOGIN_TIMEOUT="${SETUP_TUNNEL_LOGIN_TIMEOUT:-180}"
+  else
+    LOGIN_TIMEOUT="${SETUP_TUNNEL_LOGIN_TIMEOUT:-20}"
+  fi
   LOGIN_WAIT=0
   while [ ! -f "${HOME}/.cloudflared/cert.pem" ]; do
     if ! kill -0 "${CF_PIPELINE_PID}" 2>/dev/null; then

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

@@ -17,6 +17,7 @@ Load these when users ask about Maxy features or need guidance:
 - **Getting started** → `references/getting-started.md` — first run, what Maxy is, how to use it
 - **Plugins** → `references/plugins-guide.md` — what plugins are, how to install/remove them, the marketplace
 - **Memory** → `references/memory-guide.md` — how Maxy remembers things, what is stored, privacy
+- **Graph view** → `references/graph.md` — the admin `/graph` page: node/edge display, zoom-adaptive Conversation labels, filter chips, trashed nodes
 - **Contacts** → `references/contacts-guide.md` — adding, looking up, and managing contacts
 - **Telegram** → `references/telegram-guide.md` — Telegram setup, the bot, daily use
 - **Settings** → `references/settings.md` — output style, effort level, context mode, account preferences
@@ -38,6 +39,7 @@ Load these when performing admin tasks or diagnosing platform behaviour:
 - references/getting-started.md
 - references/plugins-guide.md
 - references/memory-guide.md
+- references/graph.md
 - references/contacts-guide.md
 - references/telegram-guide.md
 - references/settings.md

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

@@ -22,7 +22,7 @@ Ask the agent to set up Cloudflare. The agent first confirms the domain is alrea
 - **Proxy apex** — optional bare-domain hostname (e.g. `yourdomain.com`) that should also serve the public agent.
 - **Admin password** — the password used to gate remote access to the admin surface.
 
-When you submit, the `/api/admin/cloudflare/setup` endpoint runs — in strict order — `setRemotePassword`, `setup-tunnel.sh`, and alias-domain writes for every non-`public.*` public or apex hostname (so e.g. `chat.yourdomain.com` is classified as public by `isPublicHost()`). The script runs end-to-end:
+When you submit, the `/api/admin/cloudflare/setup` endpoint runs — in strict order — `setRemotePassword`, launches a `cloudflare-setup` action (Task 664: `systemd-run --user` transient unit wrapping `setup-tunnel.sh <brand> <port> <hostname...>`), and registers a post-exit handler to write alias-domains for every non-`public.*` public or apex hostname (so e.g. `chat.yourdomain.com` is classified as public by `isPublicHost()`). The script runs end-to-end:
 
 - `cloudflared tunnel login` — OAuth browser sign-in. The VNC browser opens the Cloudflare authorize page; pick the account that owns your domain, click Authorize. `cert.pem` lands.
 - Tunnel creation under the naming convention `{brand}-{hostname}` (e.g. `maxy-neo`). Stream log emits `step=tunnel-resolve action=reused|created` once the UUID is known so the admin agent can see which tunnel the later steps will write against.

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

@@ -68,21 +68,24 @@ The logs will show which service failed to start and why. Common causes:
 
 ## Systemd units on each device
 
-Each installed brand runs three per-brand `--user` systemd units (Task 662 — unit filenames are prefixed with the brand's `hostname` so two brands on the same device never share a unit file):
+Each installed brand runs two per-brand `--user` systemd units (Task 662 + Task 664 — unit filenames are prefixed with the brand's `hostname` so two brands on the same device never share a unit file):
 
-- `{hostname}.service` — the admin + public HTTP server on `127.0.0.1:19199`. Restarted by the upgrade flow; short downtime is expected during steps 8→12 of an upgrade.
-- `{hostname}-edge.service` — the always-on public listener on the configured port (default 19200). Reverse-proxies HTTP to the main brand service, handles `/websockify` (VNC) and `/ttyd` (admin terminal) WebSocket upgrades locally. Does NOT restart during an upgrade — the browser WebSocket stays connected by construction.
-- `{hostname}-ttyd.service` — `ttyd` bound to `127.0.0.1:{BRAND.ttydPort}` (7681 Maxy, 7682 Real Agent), running `tmux new-session -A -s maxy-pty`. Owns the byte-stream admin terminal rendered by xterm.js in the header overlay and the Software Update modal (Task 657). Independent of the main brand service and the edge; outlives service restarts so scrollback is preserved.
+- `{hostname}.service` — the admin + public HTTP server on `127.0.0.1:19199`. Restarted by the upgrade flow; short downtime is expected during steps 8→11 of an upgrade.
+- `{hostname}-edge.service` — the always-on public listener on the configured port (default 19200). Reverse-proxies HTTP to the main brand service and handles `/websockify` (VNC) WebSocket upgrades locally. Does NOT restart during an upgrade — the browser WebSocket stays connected by construction.
 
-If the admin terminal fails to open, check `sudo tail -n 50 ~/{configDir}/logs/edge-boot.log` — the `ttyd-ws-upgrade` / `ttyd-proxy-open` / `ttyd-proxy-close` lines carry a `corrId` that ties the full session lifecycle together. For unit health, `systemctl --user status {hostname}-ttyd` + `journalctl --user -u {hostname}-ttyd`.
+Upgrade and Cloudflare setup (Task 664) run as detached actions: `systemd-run --user` transient units per invocation with stdout+stderr persisted to `~/.maxy/logs/actions/<actionId>.log` and streamed to the UI via SSE. No boot-time service file exists for these.
 
-**Pre-Task-662 upgrade** — devices that ran an installer before Task 662 have legacy shared `maxy-edge.service` and `maxy-ttyd.service` units on disk, which will collide with the new per-brand units. Before re-running any installer on such a device:
+If an action looks stuck, read `~/.maxy/logs/actions/<actionId>.log` directly for the full output, or `journalctl --user --identifier=maxy-action-<actionId>` for systemd's record.
+
+**Pre-Task-662 / pre-Task-664 upgrade** — devices that ran an installer before Task 662 have legacy shared `maxy-edge.service` / `maxy-ttyd.service` units; devices that ran before Task 664 have per-brand `{hostname}-ttyd.service` units plus a pinned `/usr/local/bin/ttyd` binary. Neither is removed automatically — do this cleanup once per device before re-running any installer:
 
 ```bash
-systemctl --user stop maxy-edge maxy-ttyd 2>/dev/null || true
-systemctl --user disable maxy-edge maxy-ttyd 2>/dev/null || true
+systemctl --user stop maxy-edge maxy-ttyd realagent-ttyd 2>/dev/null || true
+systemctl --user disable maxy-edge maxy-ttyd realagent-ttyd 2>/dev/null || true
 rm -f ~/.config/systemd/user/maxy-edge.service \
-      ~/.config/systemd/user/maxy-ttyd.service
+      ~/.config/systemd/user/maxy-ttyd.service \
+      ~/.config/systemd/user/realagent-ttyd.service
+sudo rm -f /usr/local/bin/ttyd
 systemctl --user daemon-reload
 ```
 
@@ -90,7 +93,7 @@ systemctl --user daemon-reload
 
 A single Pi or laptop can host more than one brand (for example Maxy and Real Agent) side by side. Each brand runs as its own service on its own port, with its own install directory and its own data. Installing one brand does not touch the other.
 
-- **Separate:** each brand has its own install folder (`~/maxy/`, `~/realagent/`), its own config folder (`~/.maxy/`, `~/.realagent/`), its own web port, its own Cloudflare tunnel state, its own edge + ttyd systemd units (`maxy-edge.service` + `maxy-ttyd.service` vs `realagent-edge.service` + `realagent-ttyd.service`), its own ttyd loopback port (7681 vs 7682), and by default its own Neo4j database (Maxy on bolt port 7687, Real Agent on 7688).
+- **Separate:** each brand has its own install folder (`~/maxy/`, `~/realagent/`), its own config folder (`~/.maxy/`, `~/.realagent/`), its own web port, its own Cloudflare tunnel state, its own edge systemd unit (`maxy-edge.service` vs `realagent-edge.service`), and by default its own Neo4j database (Maxy on bolt port 7687, Real Agent on 7688). Action runner units are transient and per-invocation, not per-brand, so no naming conflict is possible.
 - **Shared:** both brands share the system Chromium/VNC stack, the Ollama model server, and the `cloudflared` command itself. Browser automation is serialised — one admin session at a time across both brands.
 
 To install a second brand on a device that already runs the first, just run the other installer. No flags needed for isolation: