@rubytech/create-maxy 1.0.686 → 1.0.688

package/dist/__tests__/port-canonicalisation.test.js

@@ -0,0 +1,193 @@
+// Task 666 — acceptance gate for the port writer + drift-recovery flow.
+//
+// Three invariants this test protects:
+//   (a) PORT stays public across install → upgrade on a fresh fs fixture.
+//       Without this, each upgrade re-inherits the internal port as if it
+//       were public — the exact regression this task fixes.
+//   (b) Drift-recovery logs fire EXACTLY once when a pre-task maxy.service
+//       with a drifted PORT meets a post-task installer. A second upgrade
+//       on the same device must be silent.
+//   (c) MAXY_UI_INTERNAL_PORT is PORT + 1 in every written unit file, so
+//       maxy-ui binds the internal port while the tunnel still hits edge.
+//
+// Runs via Node's built-in test runner; no vitest dependency. Compiles to
+// dist/__tests__/port-canonicalisation.test.js alongside the rest of the
+// package so `node --test dist/__tests__/*.test.js` picks it up after build.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveInstallPort, resolveInstallPortFromFs, buildMaxyUnitFile, } from "../port-resolution.js";
+function makeUnitFile(port, internal) {
+    return buildMaxyUnitFile({
+        productName: "Maxy",
+        brandHostname: "maxy",
+        neo4jDedicated: false,
+        installDir: "/home/me/maxy",
+        persistDir: "/home/me/.maxy",
+        port,
+        maxyUiInternalPort: internal,
+    });
+}
+function makeEdgeFile(edgePort) {
+    return `[Unit]\nDescription=Edge\n\n[Service]\nEnvironment=EDGE_PORT=${edgePort}\nEnvironment=MAXY_UI_PORT=${edgePort + 1}\n`;
+}
+// ---------------------------------------------------------------------------
+// (a) Fresh install writes PORT=public + MAXY_UI_INTERNAL_PORT=public+1 —
+// and a subsequent upgrade reads the SAME public value back. No drift.
+// ---------------------------------------------------------------------------
+test("fresh install then upgrade keeps PORT public (no drift)", () => {
+    const PUBLIC = 19200;
+    const INTERNAL = PUBLIC + 1;
+    // Fresh install: no existing service file, no .env → default.
+    const first = resolveInstallPort({
+        envContent: null,
+        maxyServiceContent: null,
+        edgeServiceContent: null,
+    });
+    assert.equal(first.port, PUBLIC);
+    assert.equal(first.source, "default");
+    assert.equal(first.driftLogs.length, 0);
+    // Installer writes the unit files with PORT=public, MAXY_UI_INTERNAL_PORT=+1.
+    const maxyUnit = makeUnitFile(first.port, first.port + 1);
+    const edgeUnit = makeEdgeFile(first.port);
+    // Upgrade reads them back. Same public value, no drift.
+    const second = resolveInstallPort({
+        envContent: null,
+        maxyServiceContent: maxyUnit,
+        edgeServiceContent: edgeUnit,
+    });
+    assert.equal(second.port, PUBLIC, "upgrade must not drift the public port");
+    assert.equal(second.source, "running service");
+    assert.equal(second.driftLogs.length, 0, "no drift expected on clean device");
+    // And one more upgrade for good measure — still silent.
+    const third = resolveInstallPort({
+        envContent: null,
+        maxyServiceContent: maxyUnit,
+        edgeServiceContent: edgeUnit,
+    });
+    assert.equal(third.port, PUBLIC);
+    assert.equal(third.driftLogs.length, 0);
+    // Unit file literal invariants (c): PORT is the public, INTERNAL is +1.
+    assert.match(maxyUnit, /^Environment=PORT=19200$/m);
+    assert.match(maxyUnit, /^Environment=MAXY_UI_INTERNAL_PORT=19201$/m);
+});
+// ---------------------------------------------------------------------------
+// (b) Drifted device: pre-task maxy.service has the INTERNAL port (19201) in
+// the PORT slot, edge has the canonical public (19200). Recovery logs once,
+// pins at edge, and the next pass on the rewritten files is silent.
+// ---------------------------------------------------------------------------
+test("drifted device recovers in one pass, subsequent upgrade is silent", () => {
+    const TRUE_PUBLIC = 19200;
+    // Pre-task unit: Environment=PORT=<internal>. Edge correctly carries public.
+    const driftedMaxy = makeUnitFile(TRUE_PUBLIC + 1, TRUE_PUBLIC + 2); // drifted
+    const edgeAtTruth = makeEdgeFile(TRUE_PUBLIC);
+    const recovery = resolveInstallPort({
+        envContent: null,
+        maxyServiceContent: driftedMaxy,
+        edgeServiceContent: edgeAtTruth,
+    });
+    assert.equal(recovery.port, TRUE_PUBLIC, "edge wins over drifted maxy");
+    assert.equal(recovery.source, "edge-recovery");
+    assert.equal(recovery.driftLogs.length, 1, "exactly one drift line");
+    assert.match(recovery.driftLogs[0], /\[port-recovery\] detected drift maxy=19201 edge=19200 — pinning at 19200/);
+    // After recovery, the installer writes a corrected maxy.service.
+    const rewritten = makeUnitFile(recovery.port, recovery.port + 1);
+    // Next upgrade on the same device: both files agree, no log line.
+    const silent = resolveInstallPort({
+        envContent: null,
+        maxyServiceContent: rewritten,
+        edgeServiceContent: edgeAtTruth,
+    });
+    assert.equal(silent.port, TRUE_PUBLIC);
+    assert.equal(silent.source, "running service");
+    assert.equal(silent.driftLogs.length, 0, "post-recovery upgrade must be silent");
+});
+// ---------------------------------------------------------------------------
+// --port flag short-circuits every source, including drift recovery (the
+// operator is asserting a port explicitly).
+// ---------------------------------------------------------------------------
+test("--port flag short-circuits drift recovery", () => {
+    const driftedMaxy = makeUnitFile(20001, 20002);
+    const edge = makeEdgeFile(19200);
+    const result = resolveInstallPort({
+        portFlag: 31000,
+        envContent: null,
+        maxyServiceContent: driftedMaxy,
+        edgeServiceContent: edge,
+    });
+    assert.equal(result.port, 31000);
+    assert.equal(result.source, "--port flag");
+    assert.equal(result.driftLogs.length, 0);
+});
+// ---------------------------------------------------------------------------
+// Legacy pre-647 device (no edge unit): reader uses maxy.service's PORT value,
+// no drift log emitted.
+// ---------------------------------------------------------------------------
+test("pre-647 device without edge unit reads maxy PORT, no drift log", () => {
+    const legacyMaxy = `[Service]\nEnvironment=PORT=19200\n`;
+    const result = resolveInstallPort({
+        envContent: null,
+        maxyServiceContent: legacyMaxy,
+        edgeServiceContent: null,
+    });
+    assert.equal(result.port, 19200);
+    assert.equal(result.source, "running service");
+    assert.equal(result.driftLogs.length, 0);
+});
+// ---------------------------------------------------------------------------
+// .env override takes priority over the service file; drift recovery still
+// runs against whatever was computed.
+// ---------------------------------------------------------------------------
+test(".env override wins over service file; drift recovery still runs", () => {
+    const env = "PORT=19500\nEMBED_MODEL=nomic\n";
+    const maxy = makeUnitFile(19200, 19201);
+    const edge = makeEdgeFile(19500);
+    // .env says 19500, maxy.service says 19200, edge says 19500. Reader
+    // picks .env (19500), edge confirms (19500) — no drift.
+    const resolved = resolveInstallPort({
+        envContent: env,
+        maxyServiceContent: maxy,
+        edgeServiceContent: edge,
+    });
+    assert.equal(resolved.port, 19500);
+    assert.equal(resolved.source, ".env override");
+    assert.equal(resolved.driftLogs.length, 0);
+    // Now the .env says 19202 (drifted), edge says 19500 — drift recovery wins.
+    const driftedEnv = "PORT=19202\nEMBED_MODEL=nomic\n";
+    const recovered = resolveInstallPort({
+        envContent: driftedEnv,
+        maxyServiceContent: maxy,
+        edgeServiceContent: edge,
+    });
+    assert.equal(recovered.port, 19500);
+    assert.equal(recovered.source, "edge-recovery");
+    assert.equal(recovered.driftLogs.length, 1);
+});
+// ---------------------------------------------------------------------------
+// fs wrapper end-to-end: real tmpdir fixture, verifies the file-reading path.
+// ---------------------------------------------------------------------------
+test("fs wrapper reads real fixture files end-to-end", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "maxy-port-test-"));
+    try {
+        const persistDir = join(tmp, ".maxy");
+        const serviceDir = join(tmp, ".config", "systemd", "user");
+        mkdirSync(persistDir, { recursive: true });
+        mkdirSync(serviceDir, { recursive: true });
+        writeFileSync(join(serviceDir, "maxy.service"), makeUnitFile(19300, 19301));
+        writeFileSync(join(serviceDir, "maxy-edge.service"), makeEdgeFile(19300));
+        const result = resolveInstallPortFromFs({
+            persistDir,
+            serviceDir,
+            brandServiceFileName: "maxy.service",
+            brandEdgeServiceFileName: "maxy-edge.service",
+        });
+        assert.equal(result.port, 19300);
+        assert.equal(result.source, "running service");
+        assert.equal(result.driftLogs.length, 0);
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+});

package/dist/index.js

@@ -3,6 +3,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 } from "node:crypto";
+import { resolveInstallPortFromFs, buildMaxyUnitFile } from "./port-resolution.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.
@@ -1677,41 +1678,26 @@ function installService() {
     // the VNC stack; maxy-ui sits behind it on 127.0.0.1:MAXY_UI_INTERNAL_PORT.
     // PORT + 1 (derived) avoids a fixed-port collision if the operator chose a
     // non-default --port.
+    //
+    // Task 666 — PORT in maxy.service's Environment block is the PUBLIC port,
+    // not the internal one. Previously we wrote `Environment=PORT=<internal>`,
+    // which collided with the install-time reader further down, which
+    // correctly treats Environment=PORT= as public. The overload caused +1
+    // drift per upgrade: each run read the internal value, treated it as
+    // public, wrote internal = old_internal + 1. maxy-ui now binds
+    // MAXY_UI_INTERNAL_PORT (with a fallback to PORT for mixed-state installs).
     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} ${edgeUnitName}
-Wants=${edgeUnitName}
-
-[Service]
-Type=notify
-NotifyAccess=all
-WorkingDirectory=${INSTALL_DIR}/server
-ExecStartPre=-/bin/bash ${INSTALL_DIR}/platform/scripts/resume-tunnel.sh
-ExecStart=/usr/bin/node --require ./server-init.cjs server.js
-Restart=on-failure
-RestartSec=5
-WatchdogSec=30
-TimeoutStartSec=60
-TimeoutStopSec=10
-Environment=NODE_ENV=production
-Environment=PORT=${MAXY_UI_INTERNAL_PORT}
-Environment=HOSTNAME=127.0.0.1
-Environment=KEEP_ALIVE_TIMEOUT=61000
-Environment=DISPLAY=:99
-Environment=PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium
-Environment=MAXY_PLATFORM_ROOT=${INSTALL_DIR}/platform
-Environment=PATH=%h/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
-EnvironmentFile=-${persistDir}/.env
-StandardOutput=append:${persistDir}/logs/server.log
-StandardError=append:${persistDir}/logs/server.log
-
-[Install]
-WantedBy=default.target
-`;
+    const serviceFile = buildMaxyUnitFile({
+        productName: BRAND.productName,
+        brandHostname: BRAND.hostname,
+        neo4jDedicated: NEO4J_DEDICATED,
+        installDir: INSTALL_DIR,
+        persistDir,
+        port: PORT,
+        maxyUiInternalPort: MAXY_UI_INTERNAL_PORT,
+    });
     writeFileSync(join(serviceDir, BRAND.serviceName), serviceFile);
     // Task 647 — the edge service: always-on front door that owns the public
     // port (PORT) and the VNC stack (Xtigervnc + websockify). Its lifecycle is
@@ -1905,9 +1891,12 @@ if (_args.includes("--uninstall")) {
 // Priority: --port flag > .env override > existing service file > default 19200.
 // systemd applies EnvironmentFile=-~/.{brand}/.env AFTER Environment=PORT,
 // so .env is the final runtime truth and must be checked first on upgrade.
+//
+// Task 666 — this block also performs one-shot port-drift recovery against
+// maxy-edge.service's Environment=EDGE_PORT=. See port-resolution.ts for the
+// pure logic; unit tests live at __tests__/port-canonicalisation.test.mjs.
 // ---------------------------------------------------------------------------
-let PORT = 19200;
-let PORT_SOURCE = "default";
+let portFlag;
 const portIdx = _args.indexOf("--port");
 if (portIdx !== -1) {
     const raw = _args[portIdx + 1];
@@ -1917,47 +1906,19 @@ if (portIdx !== -1) {
         console.error(`Error: --port requires a numeric value between 1024 and 65535 (got: ${raw ?? "nothing"}).`);
         process.exit(1);
     }
-    PORT = parsed;
-    PORT_SOURCE = "--port flag";
-}
-else {
-    // Upgrade detection: check .env first (runtime override), then service file (install-time)
-    const persistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
-    const envPath = join(persistDir, ".env");
-    try {
-        if (existsSync(envPath)) {
-            const envContent = readFileSync(envPath, "utf-8");
-            const envMatch = envContent.match(/^PORT=(\d+)/m);
-            if (envMatch) {
-                const envPort = parseInt(envMatch[1], 10);
-                if (envPort >= 1024 && envPort <= 65535) {
-                    PORT = envPort;
-                    PORT_SOURCE = ".env override";
-                }
-            }
-        }
-    }
-    catch { /* non-critical */ }
-    // Fall back to the service file if .env didn't set PORT
-    if (PORT_SOURCE === "default") {
-        const serviceDir = resolve(process.env.HOME ?? "/root", ".config/systemd/user");
-        const servicePath = join(serviceDir, BRAND.serviceName);
-        try {
-            if (existsSync(servicePath)) {
-                const svcContent = readFileSync(servicePath, "utf-8");
-                const match = svcContent.match(/^Environment=PORT=(\d+)/m);
-                if (match) {
-                    const existing = parseInt(match[1], 10);
-                    if (existing >= 1024 && existing <= 65535) {
-                        PORT = existing;
-                        PORT_SOURCE = "running service";
-                    }
-                }
-            }
-        }
-        catch { /* non-critical — fall through to default */ }
-    }
+    portFlag = parsed;
 }
+const _portResolution = resolveInstallPortFromFs({
+    portFlag,
+    persistDir: resolve(process.env.HOME ?? "/root", BRAND.configDir),
+    serviceDir: resolve(process.env.HOME ?? "/root", ".config/systemd/user"),
+    brandServiceFileName: BRAND.serviceName,
+    brandEdgeServiceFileName: `${BRAND.hostname}-edge.service`,
+});
+let PORT = _portResolution.port;
+let PORT_SOURCE = _portResolution.source;
+for (const line of _portResolution.driftLogs)
+    console.log(line);
 // ---------------------------------------------------------------------------
 // Hostname — install-time flag, not solely a brand attribute.
 //

package/dist/port-resolution.js

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const PORT_RE = /^PORT=(\d+)/m;
+const ENV_PORT_RE = /^Environment=PORT=(\d+)/m;
+const ENV_EDGE_PORT_RE = /^Environment=EDGE_PORT=(\d+)/m;
+function parseValid(raw) {
+    if (!raw)
+        return null;
+    const n = parseInt(raw, 10);
+    if (Number.isNaN(n) || n < 1024 || n > 65535)
+        return null;
+    return n;
+}
+export function resolveInstallPort(opts) {
+    const defaultPort = opts.defaultPort ?? 19200;
+    // Flag beats everything. Caller is responsible for validation prior.
+    if (typeof opts.portFlag === "number") {
+        return { port: opts.portFlag, source: "--port flag", driftLogs: [] };
+    }
+    let port = defaultPort;
+    let source = "default";
+    const envPort = opts.envContent !== null ? parseValid(opts.envContent.match(PORT_RE)?.[1]) : null;
+    if (envPort !== null) {
+        port = envPort;
+        source = ".env override";
+    }
+    if (source === "default") {
+        const svcPort = opts.maxyServiceContent !== null
+            ? parseValid(opts.maxyServiceContent.match(ENV_PORT_RE)?.[1])
+            : null;
+        if (svcPort !== null) {
+            port = svcPort;
+            source = "running service";
+        }
+    }
+    // Task 666 — one-shot drift recovery. Pre-task `maxy.service` unit files
+    // carried the INTERNAL port in the `Environment=PORT=` slot, so the
+    // reader above just inherited drift. `maxy-edge.service`'s EDGE_PORT is
+    // authoritative for the tunnel (always has been since Task 647), so we
+    // trust it over the maxy.service value when they disagree — exactly
+    // once per device, logged loudly.
+    const driftLogs = [];
+    const edgePort = opts.edgeServiceContent !== null
+        ? parseValid(opts.edgeServiceContent.match(ENV_EDGE_PORT_RE)?.[1])
+        : null;
+    if (edgePort !== null && edgePort !== port) {
+        driftLogs.push(`  [port-recovery] detected drift maxy=${port} edge=${edgePort} — pinning at ${edgePort}`);
+        port = edgePort;
+        source = "edge-recovery";
+    }
+    return { port, source, driftLogs };
+}
+export function resolveInstallPortFromFs(opts) {
+    const readIfExists = (path) => {
+        try {
+            if (!existsSync(path))
+                return null;
+            return readFileSync(path, "utf-8");
+        }
+        catch {
+            return null;
+        }
+    };
+    return resolveInstallPort({
+        portFlag: opts.portFlag,
+        envContent: readIfExists(join(opts.persistDir, ".env")),
+        maxyServiceContent: readIfExists(join(opts.serviceDir, opts.brandServiceFileName)),
+        edgeServiceContent: readIfExists(join(opts.serviceDir, opts.brandEdgeServiceFileName)),
+        defaultPort: opts.defaultPort,
+    });
+}
+export function buildMaxyUnitFile(o) {
+    const neo4jServiceDep = o.neo4jDedicated
+        ? `neo4j-${o.brandHostname}.service`
+        : "neo4j.service";
+    const edgeUnitName = `${o.brandHostname}-edge.service`;
+    return `[Unit]
+Description=${o.productName} AI Assistant
+After=${neo4jServiceDep} ${edgeUnitName}
+Wants=${edgeUnitName}
+
+[Service]
+Type=notify
+NotifyAccess=all
+WorkingDirectory=${o.installDir}/server
+ExecStartPre=-/bin/bash ${o.installDir}/platform/scripts/resume-tunnel.sh
+ExecStart=/usr/bin/node --require ./server-init.cjs server.js
+Restart=on-failure
+RestartSec=5
+WatchdogSec=30
+TimeoutStartSec=60
+TimeoutStopSec=10
+Environment=NODE_ENV=production
+Environment=PORT=${o.port}
+Environment=MAXY_UI_INTERNAL_PORT=${o.maxyUiInternalPort}
+Environment=HOSTNAME=127.0.0.1
+Environment=KEEP_ALIVE_TIMEOUT=61000
+Environment=DISPLAY=:99
+Environment=PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium
+Environment=MAXY_PLATFORM_ROOT=${o.installDir}/platform
+Environment=PATH=%h/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
+EnvironmentFile=-${o.persistDir}/.env
+StandardOutput=append:${o.persistDir}/logs/server.log
+StandardError=append:${o.persistDir}/logs/server.log
+
+[Install]
+WantedBy=default.target
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.686",
+  "version": "1.0.688",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"
@@ -9,7 +9,8 @@
   "scripts": {
     "build": "tsc",
     "bundle": "node scripts/bundle.js",
-    "prepublishOnly": "node ../../platform/ui/scripts/check-route-wiring.mjs && npm run build && chmod +x dist/index.js && npm run bundle && node ../../platform/ui/scripts/check-bundle-node-imports.mjs --dir=./payload/server/public/assets"
+    "test": "npm run build && node --test dist/__tests__/port-canonicalisation.test.js",
+    "prepublishOnly": "node ../../platform/ui/scripts/check-route-wiring.mjs && node ../../platform/ui/scripts/check-edge-admin-routes.mjs && npm run build && chmod +x dist/index.js && npm run bundle && node ../../platform/ui/scripts/check-bundle-node-imports.mjs --dir=./payload/server/public/assets"
   },
   "files": [
     "dist",

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

@@ -70,8 +70,10 @@ The logs will show which service failed to start and why. Common causes:
 
 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→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.
+- `{hostname}.service` — the admin + public HTTP server on `127.0.0.1:19201` (public port + 1). Restarted by the upgrade flow; short downtime is expected during steps 8→11 of an upgrade. Task 666: the unit carries two port env vars — `PORT=<public>` (canonical public port, read by the upgrade detector) and `MAXY_UI_INTERNAL_PORT=<public+1>` (the port maxy-ui actually binds).
+- `{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. Task 666: also hosts `/api/admin/actions/*` and `/api/admin/version*` — the Software Update modal's own routes — so the log stream survives the brand service's restart window. Does NOT restart during an upgrade — the browser WebSocket stays connected by construction.
+
+**Port-drift recovery (Task 666).** Devices upgraded between Tasks 647 and 666 may have drifted +1 on every upgrade because the pre-Task-666 installer wrote `Environment=PORT=<internal>` into `{hostname}.service` and the upgrade reader correctly treated `PORT=` as public. The first post-Task-666 install detects this (comparing maxy's PORT against the edge's EDGE_PORT) and emits a one-shot loud log: `[port-recovery] detected drift maxy=<X> edge=<Y> — pinning at <Y>`. Subsequent upgrades are silent. If your Cloudflare tunnel was pointing at a drifted port, the ingress `config.yml` still needs a one-time manual fix: `sed -i 's|localhost:<old>|localhost:<current>|' ~/.{configDir}/cloudflared/config.yml && cloudflared tunnel ingress validate`. Maxy never rewrites cloudflared config programmatically.
 
 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.
 

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

@@ -52,7 +52,7 @@ The memory graph is stored on your Pi. It never leaves your network.
 
 ## The Web Interface
 
-The web app runs on your Pi on port 19200. A small always-on front door (`maxy-edge`) owns that port and the remote terminal transport — so when the Software Update command restarts the app server, the browser-side terminal keeps streaming bytes exactly like an SSH session would. Login cookies are HMAC-signed with a shared key on disk, so both processes recognise the same session without any coordination and you do not have to log in again after an update. It provides:
+The web app runs on your Pi on port 19200. A small always-on front door (`maxy-edge`) owns that port and the remote terminal transport — so when the Software Update command restarts the app server, the browser-side terminal keeps streaming bytes exactly like an SSH session would. The edge also hosts the update flow's own routes (the sudo prompt, the action launcher, the SSE progress stream, the installed-version poll), so the Software Update modal's log panel does not go blank during the app-server restart window — it keeps receiving lines, heartbeats, and the final exit event unbroken. Login cookies are HMAC-signed with a shared key on disk, so both processes recognise the same session without any coordination and you do not have to log in again after an update. It provides:
 
 - **Admin chat** (at `/`) — your primary interface, PIN-protected
 - **Public chat** (at `/{agent-name}`) — visitor-facing agents, each with their own URL. On public hostnames, the root path serves the default agent.

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

@@ -95,7 +95,9 @@ If the initial Cloudflare login fails during setup, Maxy will fall back to askin
 
 ## Action runner — upgrade or Cloudflare setup appears stuck
 
-Task 664 replaced the ttyd/xterm admin terminal with a detached action runner. Upgrades and Cloudflare setup now run under transient `systemd-run --user` units whose stdout+stderr land in a persisted per-action log, streamed to the browser via SSE.
+Task 664 replaced the ttyd/xterm admin terminal with a detached action runner. Upgrades and Cloudflare setup now run under transient `systemd-run --user` units whose stdout+stderr land in a persisted per-action log, streamed to the browser via SSE. Task 666 moved the four routes that serve the modal (`/api/admin/actions/*`, `/api/admin/version`) onto `maxy-edge.service`, so the log panel's stream survives a mid-run restart of `maxy.service` without reconnecting.
+
+**"Connection lost — reconnecting…" banner appears during an upgrade.** On post-Task-666 bundles this should never appear while the upgrade is in flight — the routes live on the always-on edge. If you see the banner during steps 8→11 of an upgrade on a current bundle, it is a **regression**, not expected behaviour: the routes have drifted back onto `maxy.service` or the edge's Hono dispatcher is not intercepting them. Check `~/.maxy/logs/edge.log` for `[edge-admin]` entries during the window; absence means the edge never received the request. The prebuild gate `platform/ui/scripts/check-edge-admin-routes.mjs` exists specifically to catch this drift before it ships.
 
 **Heartbeat stalled** (log panel header shows rising `silent Ns` amber badge).