@rubytech/create-realagent 1.0.684 → 1.0.686

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,183 +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 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"));
-        }
-        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");
-}
+// 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`);
@@ -1847,10 +1679,12 @@ function installService() {
     // non-default --port.
     const MAXY_UI_INTERNAL_PORT = PORT + 1;
     const neo4jServiceDep = NEO4J_DEDICATED ? `neo4j-${BRAND.hostname}.service` : "neo4j.service";
+    const edgeUnitShort = `${BRAND.hostname}-edge`;
+    const edgeUnitName = `${edgeUnitShort}.service`;
     const serviceFile = `[Unit]
 Description=${BRAND.productName} AI Assistant
-After=${neo4jServiceDep} maxy-edge.service
-Wants=maxy-edge.service
+After=${neo4jServiceDep} ${edgeUnitName}
+Wants=${edgeUnitName}
 
 [Service]
 Type=notify
@@ -1879,23 +1713,30 @@ 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");
+    // Task 647 — the edge service: always-on front door that owns the public
+    // port (PORT) and the VNC stack (Xtigervnc + websockify). Its lifecycle is
+    // independent of the main brand service, so an in-place upgrade triggered
+    // from the admin terminal can restart the main brand service without
+    // disconnecting the browser's remote terminal WebSocket.
+    //
+    // Task 662: the unit is per-brand so two brands on the same device each
+    // own their own edge listener on their own EDGE_PORT — installing brand B
+    // never rewrites brand A's unit or steals brand A's public port. Upgrades
+    // from pre-662 installs require the manual recovery paragraph in
+    // .docs/deployment.md before re-running this installer; auto-migration is
+    // intentionally scoped out.
+    const edgeTemplatePath = resolve(INSTALL_DIR, "platform/templates/systemd/edge.service.template");
     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}`);
+        writeFileSync(join(serviceDir, edgeUnitName), edgeServiceContent);
+        logFile(`  ${edgeUnitName}: 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`);
+        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
@@ -1952,17 +1793,17 @@ WantedBy=multi-user.target
     catch { /* not critical */ }
     // 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.
+    // Task 647 ordering: on upgrades, the old main brand service still holds
+    // the public port (PORT). Stop it FIRST so the edge can bind that socket;
+    // starting the edge first would race against the old main brand service
+    // 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", edgeUnitShort], { 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" });
+    // edge first: binds public port + starts VNC stack. Then main brand service.
+    spawnSync("systemctl", ["--user", "restart", edgeUnitShort], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "restart", unitName], { stdio: "inherit" });
     // Wait for the server to come up
     console.log("  Waiting for web server...");
@@ -2312,6 +2153,12 @@ else {
 }
 // Dedicated = port differs from the default shared instance
 const NEO4J_DEDICATED = NEO4J_PORT !== DEFAULT_NEO4J_PORT;
+// ---------------------------------------------------------------------------
+// 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("================================================================");
@@ -2344,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,14 +85,23 @@ 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`. This mirrors the install-time check
- *  at index.ts:489 which uses the same signal for apt/hostname behavior. */
+ *  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` (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() {
     const systemdUserDir = resolve(HOME, ".config/systemd/user");
     if (!existsSync(systemdUserDir))
         return false;
+    const thisBrandEdge = `${BRAND.hostname}-edge.service`;
     try {
-        return readdirSync(systemdUserDir).some((f) => f.endsWith(".service") && f !== BRAND.serviceName && !f.startsWith("maxy-edge") && !f.startsWith("maxy-ttyd"));
+        return readdirSync(systemdUserDir).some((f) => f.endsWith(".service") && f !== BRAND.serviceName && f !== thisBrandEdge);
     }
     catch {
         return false;
@@ -111,15 +120,26 @@ 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.
+    // 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`).
+    // 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 legacyTtydUnitShort = `${BRAND.hostname}-ttyd`;
     try {
-        spawnSync("systemctl", ["--user", "stop", "maxy-edge"], { stdio: "pipe", timeout: 15_000 });
-        console.log("  Stopped maxy-edge");
+        spawnSync("systemctl", ["--user", "stop", edgeUnitShort], { stdio: "pipe", timeout: 15_000 });
+        console.log(`  Stopped ${edgeUnitShort}`);
     }
     catch {
-        console.log("  maxy-edge not running");
+        console.log(`  ${edgeUnitShort} not running`);
+    }
+    try {
+        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
@@ -551,19 +571,27 @@ 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)) {
+    // 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 legacyBrandTtyd = `${BRAND.hostname}-ttyd`;
+    for (const unit of [thisBrandEdge, legacyBrandTtyd]) {
         try {
-            rmSync(edgeServiceFile);
-            console.log("  Removed maxy-edge.service");
+            spawnSync("systemctl", ["--user", "disable", unit], { stdio: "pipe" });
         }
-        catch (err) {
-            console.log(`  Failed to remove maxy-edge.service: ${err instanceof Error ? err.message : String(err)}`);
+        catch { /* ignore */ }
+        const unitFile = resolve(HOME, `.config/systemd/user/${unit}.service`);
+        if (existsSync(unitFile)) {
+            try {
+                rmSync(unitFile);
+                console.log(`  Removed ${unit}.service`);
+            }
+            catch (err) {
+                console.log(`  Failed to remove ${unit}.service: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     }
     // Reload daemon

package/package.json

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

package/payload/platform/config/brand.json

@@ -7,6 +7,7 @@
   "tagline": "Built for agents. By agents.",
   "domain": "realagent.network",
   "neo4jPort": 7688,
+  "ttydPort": 7682,
 
  "defaultColors": {
     "primary": "#7C8C72",

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.