@rubytech/create-maxy 1.0.679 → 1.0.681

package/dist/index.js

@@ -2,7 +2,8 @@
 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 } from "node:crypto";
+import { randomBytes, createHash } from "node:crypto";
+import { TTYD_VERSION, TTYD_SHA256_BY_ARCH, mapUnameToTtydArch, ttydDownloadUrl, } from "./pinned-binaries.js";
 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.
@@ -332,6 +333,7 @@ function pkgsMissing(pkgs) {
 function installAptGroup(label, pkgs) {
     const pairs = pkgs.map((original) => ({ original, resolved: resolveAptName(original) }));
     logFile(`  apt install (${label}): ${pairs.map((x) => x.resolved).join(" ")}`);
+    console.log("  [privileged] apt-get install");
     shell("apt-get", ["install", "-y", ...pairs.map((x) => x.resolved)], { sudo: true });
     const stillMissing = pairs.filter(({ resolved }) => {
         const r = spawnSync("dpkg", ["-s", resolved], { stdio: "pipe", timeout: 5_000 });
@@ -364,8 +366,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"];
     const WIFI_DEPS = ["hostapd", "dnsmasq"];
-    const ALL_APT_DEPS = [...BASE_DEPS, ...VNC_DEPS, ...WIFI_DEPS];
+    const ALL_APT_DEPS = [...BASE_DEPS, ...VNC_DEPS, ...TERMINAL_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
@@ -388,6 +394,7 @@ function installSystemDeps() {
         }
         console.log(`  Missing apt deps (${missing.length}): ${missing.join(", ")}`);
         console.log(`  Installing via sudo apt-get — sudo may prompt for your password...`);
+        console.log("  [privileged] apt-get update");
         shell("apt-get", ["update"], { sudo: true });
         installAptGroup("base utilities", BASE_DEPS);
         installAptGroup("VNC stack", VNC_DEPS);
@@ -402,9 +409,12 @@ function installSystemDeps() {
         // --hostname flag: set unconditionally, no detection, no preservation logic.
         console.log(`  Hostname: ${HOSTNAME_FLAG} (from --hostname flag)`);
         try {
+            console.log("  [privileged] hostnamectl set-hostname");
             shell("hostnamectl", ["set-hostname", HOSTNAME_FLAG], { sudo: true });
+            console.log("  [privileged] sed -i");
             shell("sed", ["-i", `s/127\\.0\\.1\\.1.*$/127.0.1.1\\t${HOSTNAME_FLAG}/`, "/etc/hosts"], { sudo: true });
             try {
+                console.log("  [privileged] sed -i");
                 shell("sed", ["-i", `s/^[#]*host-name=.*/host-name=${HOSTNAME_FLAG}/`, "/etc/avahi/avahi-daemon.conf"], { sudo: true });
                 console.log(`  Avahi host-name: ${HOSTNAME_FLAG} (updated avahi-daemon.conf)`);
             }
@@ -455,9 +465,12 @@ function installSystemDeps() {
                 console.log(`  Hostname: ${BRAND.hostname} (${reason})`);
                 hostnameSetAttempted = true;
                 try {
+                    console.log("  [privileged] hostnamectl set-hostname");
                     shell("hostnamectl", ["set-hostname", BRAND.hostname], { sudo: true });
+                    console.log("  [privileged] sed -i");
                     shell("sed", ["-i", `s/127\\.0\\.1\\.1.*$/127.0.1.1\\t${BRAND.hostname}/`, "/etc/hosts"], { sudo: true });
                     try {
+                        console.log("  [privileged] sed -i");
                         shell("sed", ["-i", `s/^[#]*host-name=.*/host-name=${BRAND.hostname}/`, "/etc/avahi/avahi-daemon.conf"], { sudo: true });
                         console.log(`  Avahi host-name: ${BRAND.hostname} (updated avahi-daemon.conf)`);
                     }
@@ -500,8 +513,11 @@ function installSystemDeps() {
     const avahiDestPath = `/etc/avahi/services/${BRAND.hostname}.service`;
     try {
         writeFileSync(avahiTmpPath, avahiService);
+        console.log("  [privileged] cp");
         shell("cp", [avahiTmpPath, avahiDestPath], { sudo: true });
+        console.log("  [privileged] systemctl enable");
         shell("systemctl", ["enable", "avahi-daemon"], { sudo: true });
+        console.log("  [privileged] systemctl restart");
         shell("systemctl", ["restart", "avahi-daemon"], { sudo: true });
     }
     catch { /* not critical */ }
@@ -532,6 +548,7 @@ function installSystemDeps() {
         if (existsSync("/usr/bin/nmcli") && !existsSync(nmConfFile)) {
             console.log("  Disabling WiFi power save...");
             writeFileSync(`/tmp/${BRAND.hostname}-no-powersave.conf`, "[connection]\nwifi.powersave = 2\n");
+            console.log("  [privileged] cp");
             shell("cp", [`/tmp/${BRAND.hostname}-no-powersave.conf`, nmConfFile], { sudo: true });
             spawnSync("sudo", ["systemctl", "restart", "NetworkManager"], { stdio: "pipe" });
         }
@@ -549,6 +566,7 @@ function installNodejs() {
         throw new Error("Automatic Node.js installation is only supported on Linux. Install Node.js 20+ manually.");
     }
     spawnSync("bash", ["-c", "curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -"], { stdio: "inherit" });
+    console.log("  [privileged] apt-get install");
     shell("apt-get", ["install", "-y", "nodejs"], { sudo: true });
 }
 function installClaudeCode() {
@@ -592,6 +610,7 @@ function installClaudeCode() {
         }
         else {
             console.log("  This may take 15–30 minutes on Raspberry Pi...");
+            console.log("  [privileged] npm install -g @anthropic-ai/claude-code@latest");
             shellRetry("npm", ["install", "-g", ...NPM_NET_FLAGS, "--loglevel", "verbose", "@anthropic-ai/claude-code@latest"], { sudo: true, timeout: 2_400_000 }, // 40 min — Pi downloads can take 25+ min
             3, 30);
         }
@@ -668,8 +687,10 @@ function resetNeo4jAuth(port = DEFAULT_NEO4J_PORT, dataDir = "/var/lib/neo4j") {
         });
     }
     else {
+        console.log("  [privileged] neo4j-admin dbms");
         shell("neo4j-admin", ["dbms", "set-initial-password", "--", password], { sudo: true });
     }
+    console.log("  [privileged] systemctl start");
     shell("systemctl", ["start", serviceName], { sudo: true });
     console.log("  Waiting for Neo4j to start...");
     for (let i = 0; i < 15; i++) {
@@ -797,11 +818,15 @@ function installNeo4j() {
     const has17 = policyResult.status === 0 && !policyOutput.includes("Candidate: (none)");
     const javaPackage = has17 ? "openjdk-17-jre-headless" : "openjdk-21-jre-headless";
     console.log(`  Installing Java (${javaPackage})...`);
+    console.log("  [privileged] apt-get install");
     shell("apt-get", ["install", "-y", javaPackage], { sudo: true });
     spawnSync("bash", ["-c", "curl -fsSL https://debian.neo4j.com/neotechnology.gpg.key | sudo gpg --yes --dearmor -o /usr/share/keyrings/neo4j.gpg 2>/dev/null"], { stdio: "inherit" });
     spawnSync("bash", ["-c", 'echo "deb [signed-by=/usr/share/keyrings/neo4j.gpg] https://debian.neo4j.com stable 5" | sudo tee /etc/apt/sources.list.d/neo4j.list'], { stdio: "inherit" });
+    console.log("  [privileged] apt-get update");
     shell("apt-get", ["update"], { sudo: true });
+    console.log("  [privileged] apt-get install");
     shell("apt-get", ["install", "-y", "neo4j"], { sudo: true });
+    console.log("  [privileged] sed -i");
     shell("sed", ["-i", "s/#server.default_listen_address=0.0.0.0/server.default_listen_address=127.0.0.1/", "/etc/neo4j/neo4j.conf"], { sudo: true });
     // Generate strong random password — stored in persistent location (~/{configDir}/)
     const password = randomBytes(24).toString("base64url");
@@ -812,8 +837,11 @@ function installNeo4j() {
     const configDir = resolve(INSTALL_DIR, "platform/config");
     mkdirSync(configDir, { recursive: true });
     writeFileSync(join(configDir, ".neo4j-password"), password, { mode: 0o600 });
+    console.log("  [privileged] neo4j-admin dbms");
     shell("neo4j-admin", ["dbms", "set-initial-password", "--", password], { sudo: true });
+    console.log("  [privileged] systemctl enable");
     shell("systemctl", ["enable", "neo4j"], { sudo: true });
+    console.log("  [privileged] systemctl start");
     shell("systemctl", ["start", "neo4j"], { sudo: true });
     console.log("  Neo4j started. Password stored securely.");
 }
@@ -851,11 +879,16 @@ function setupDedicatedNeo4j() {
         throw new Error("/etc/neo4j/neo4j.conf not found. Cannot create dedicated instance without base config.");
     }
     // 1. Copy base config
+    console.log("  [privileged] cp -r");
     shell("cp", ["-r", "/etc/neo4j", confDir], { sudo: true });
     // 2. Modify config for this instance: bolt port, HTTP port, data/log directories
+    console.log("  [privileged] sed -i");
     shell("sed", ["-i", `s/^#\\?server\\.bolt\\.listen_address=.*/server.bolt.listen_address=:${NEO4J_PORT}/`, `${confDir}/neo4j.conf`], { sudo: true });
+    console.log("  [privileged] sed -i");
     shell("sed", ["-i", `s/^#\\?server\\.http\\.listen_address=.*/server.http.listen_address=:${httpPort}/`, `${confDir}/neo4j.conf`], { sudo: true });
+    console.log("  [privileged] sed -i");
     shell("sed", ["-i", `s|^#\\?server\\.directories\\.data=.*|server.directories.data=${dataDir}/data|`, `${confDir}/neo4j.conf`], { sudo: true });
+    console.log("  [privileged] sed -i");
     shell("sed", ["-i", `s|^#\\?server\\.directories\\.logs=.*|server.directories.logs=${logDir}|`, `${confDir}/neo4j.conf`], { sudo: true });
     // Verify config was updated — sed silently no-ops if the key format changed
     const confContent = spawnSync("grep", [`server.bolt.listen_address=:${NEO4J_PORT}`, `${confDir}/neo4j.conf`], { stdio: "pipe" });
@@ -864,7 +897,9 @@ function setupDedicatedNeo4j() {
         logFile(`  WARNING: sed verification failed — bolt port ${NEO4J_PORT} not found in ${confDir}/neo4j.conf`);
     }
     // 3. Create data and log directories
+    console.log("  [privileged] mkdir -p");
     shell("mkdir", ["-p", `${dataDir}/data`, logDir], { sudo: true });
+    console.log("  [privileged] chown -R");
     shell("chown", ["-R", "neo4j:neo4j", dataDir, logDir, confDir], { sudo: true });
     // 4. Create systemd service
     const serviceContent = `[Unit]
@@ -885,6 +920,7 @@ WantedBy=multi-user.target
 `;
     const tmpServicePath = `/tmp/${serviceName}.service`;
     writeFileSync(tmpServicePath, serviceContent);
+    console.log("  [privileged] cp");
     shell("cp", [tmpServicePath, `/etc/systemd/system/${serviceName}.service`], { sudo: true });
     spawnSync("rm", ["-f", tmpServicePath]);
     // 5. Set initial password before first start
@@ -901,7 +937,9 @@ WantedBy=multi-user.target
     });
     // 6. Enable and start the dedicated service
     spawnSync("sudo", ["systemctl", "daemon-reload"], { stdio: "inherit" });
+    console.log("  [privileged] systemctl enable");
     shell("systemctl", ["enable", serviceName], { sudo: true });
+    console.log("  [privileged] systemctl start");
     shell("systemctl", ["start", serviceName], { sudo: true });
     // 7. Verify connectivity — poll until cypher-shell can connect
     console.log(`  Waiting for dedicated Neo4j instance on port ${NEO4J_PORT}...`);
@@ -1046,6 +1084,7 @@ function installCloudflared() {
     const arch = isArm64() ? "arm64" : "amd64";
     const debPath = "/tmp/cloudflared.deb";
     shellRetry("curl", ["-fSL", "--progress-bar", `https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-${arch}.deb`, "-o", debPath], { timeout: 120_000 }, 3, 10);
+    console.log("  [privileged] dpkg -i");
     shell("dpkg", ["-i", debPath], { sudo: true });
     spawnSync("rm", ["-f", debPath]);
 }
@@ -1063,19 +1102,24 @@ function installWhisperCpp() {
         return;
     }
     // Build dependencies — cmake is required since whisper.cpp migrated from plain make
+    console.log("  [privileged] apt-get install");
     shell("apt-get", ["install", "-y", "build-essential", "cmake"], { sudo: true });
     // Clone or update the repository
     if (!existsSync(WHISPER_DIR)) {
         console.log("  Cloning whisper.cpp...");
+        console.log("  [privileged] git clone");
         shell("git", ["clone", "--depth", "1", "https://github.com/ggerganov/whisper.cpp.git", WHISPER_DIR], { sudo: true });
     }
     // Compile via cmake (whisper.cpp's Makefile is a thin cmake wrapper)
     console.log("  Compiling whisper.cpp (this takes a few minutes on Pi)...");
+    console.log("  [privileged] cmake -B");
     shell("cmake", ["-B", "build"], { cwd: WHISPER_DIR, sudo: true, timeout: 120_000 });
+    console.log("  [privileged] cmake --build");
     shell("cmake", ["--build", "build", "--config", "Release", "-j2"], { cwd: WHISPER_DIR, sudo: true, timeout: 600_000 });
     // Download the base model (~150MB)
     if (!existsSync(WHISPER_MODEL)) {
         console.log("  Downloading ggml-base model (~150MB)...");
+        console.log("  [privileged] bash -c");
         shellRetry("bash", ["-c", `cd ${WHISPER_DIR} && bash models/download-ggml-model.sh base`], { sudo: true, timeout: 300_000 }, 3, 15);
     }
     console.log("  whisper.cpp installed successfully.");
@@ -1690,56 +1734,180 @@ function installCrons() {
         logFile(`  crontab write failed: ${write.stderr}`);
     }
 }
-// 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;
+// 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 homeDir = process.env.HOME ?? "/root";
-    const unitPath = resolve(homeDir, ".config/systemd/user/maxy-ttyd.service");
-    if (!existsSync(unitPath)) {
-        return;
+    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;
     }
-    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 });
+    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 {
-        unlinkSync(unitPath);
+        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: could not remove ${unitPath}: ${err instanceof Error ? err.message : String(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;
     }
-    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."
+    // 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)) {
+    if (!existsSync(tmuxConfDest)) {
+        const tmuxConfTemplate = resolve(INSTALL_DIR, "platform/templates/dotfiles/.tmux.conf");
         try {
-            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)");
+            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: could not inspect ~/.tmux.conf: ${err instanceof Error ? err.message : String(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");
 }
 function installService() {
     log("12", TOTAL, `Starting ${BRAND.productName}...`);
@@ -1754,6 +1922,7 @@ function installService() {
     try {
         const sysctlConf = "net.core.rmem_max=7340032\nnet.core.wmem_max=7340032\n";
         writeFileSync(sysctlTmpPath, sysctlConf);
+        console.log("  [privileged] cp");
         shell("cp", [sysctlTmpPath, sysctlDestPath], { sudo: true });
         spawnSync("rm", ["-f", sysctlTmpPath]);
         spawnSync("sudo", ["sysctl", "--system"], { stdio: "ignore", timeout: 10_000 });
@@ -1904,6 +2073,7 @@ WantedBy=multi-user.target
     try {
         const tmpPath = "/tmp/wifi-provision.service";
         writeFileSync(tmpPath, wifiProvisionService);
+        console.log("  [privileged] cp");
         shell("cp", [tmpPath, wifiProvisionPath], { sudo: true });
         spawnSync("rm", ["-f", tmpPath]);
         spawnSync("sudo", ["systemctl", "daemon-reload"], { stdio: "inherit" });
@@ -2317,7 +2487,7 @@ try {
     setupVncViewer();
     setupAccount();
     installTunnelScripts(); // ~/setup-tunnel.sh, ~/reset-tunnel.sh — the SKILL contract
-    installTerminalService(); // Task 645: tears down Task 591's orphan maxy-ttyd.service on upgrades
+    installTerminalService(); // Task 657: installs maxy-ttyd.service (ttyd + tmux) for byte-stream admin terminal
     installService();
     console.log("");
     console.log("================================================================");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.679",
+  "version": "1.0.681",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"

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

@@ -70,9 +70,11 @@ The logs will show which service failed to start and why. Common causes:
 
 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-ui.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.
+- `maxy-edge.service` — the always-on public listener on the configured port (default 19200). Reverse-proxies HTTP to `maxy-ui`, handles `/websockify` (VNC) and `/ttyd` (admin terminal) WebSocket upgrades locally. Does NOT restart during an upgrade — the browser WebSocket stays connected by construction.
+- `maxy-ttyd.service` — `ttyd` bound to `127.0.0.1:7681`, 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 `maxy-ui` and `maxy-edge`; outlives service restarts so scrollback is preserved.
 
-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.
+If the admin terminal fails to open, check `sudo tail -n 50 ~/.maxy/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 maxy-ttyd` + `journalctl --user -u maxy-ttyd`.
 
 ## Upgrading
 

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

@@ -95,6 +95,8 @@ If the initial Cloudflare login fails during setup, Maxy will fall back to askin
 
 ## Software Update click shows an error instead of opening the terminal
 
+> **Stale content — Task 657 replaced the VNC-terminal surface with byte-stream xterm.js over `/ttyd`.** The VNC launch-upgrade path described below no longer exists. First-line diagnostic for the new surface: `sudo systemctl --user status maxy-ttyd` plus `sudo grep 'ttyd-proxy' ~/.maxy/logs/edge-boot.log | tail -20`. Failure mode signals: `ttyd-ws-upgrade accepted` with no `ttyd-proxy-open` → `maxy-ttyd.service` is down; `ttyd-proxy-open` with no `ttyd-proxy-chunk dir=upstream→client` → ttyd/tmux is not attaching a PTY. Full rewrite tracked in Task 658. The section below is kept only as a historical reference for devices still on pre-Task-657 bundles.
+
 **Symptom:** You clicked **Upgrade** in the Software Update modal, but instead of the VNC terminal overlay appearing, the modal shows a red error row like:
 
 ```