@rubytech/create-maxy-code 0.1.0

package/dist/index.js

@@ -0,0 +1,3325 @@
+#!/usr/bin/env node
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync, cpSync, readFileSync, rmSync, readdirSync, appendFileSync, openSync, closeSync, chmodSync, symlinkSync, unlinkSync, lstatSync, statSync, readlinkSync, realpathSync, accessSync, constants as fsConstants } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { resolveInstallPortFromFs, buildMaxyUnitFile, buildClaudeSessionManagerUnitFile } from "./port-resolution.js";
+import { parseOsRelease, isUbuntuLike as isUbuntuLikePure, parseAptCacheCandidate, decideAptResolution, } from "./apt-resolve.js";
+import { findPeerBrandOnDefaultNeo4jPort } from "./peer-brand-detect.js";
+import { requireSupportedPlatform } from "./platform-detect.js";
+import { renderPlist } from "./launchd-plist.js";
+import { installAllBrewPackages } from "./brew-install.js";
+import { parseSwVers, isSupportedMacosVersion } from "./macos-version.js";
+import { decideChromiumAction, isSnapConfinedPath } from "./snap-chromium.js";
+import { classifyPortHolder } from "./preflight-port-classifier.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.
+const BRAND_PATH = join(PAYLOAD_DIR, "platform", "config", "brand.json");
+if (!existsSync(BRAND_PATH)) {
+    console.error("Setup failed: brand.json not found in payload (package may be corrupted)");
+    console.error("FATAL: brand.json not found in payload. Package may be corrupted.");
+    process.exit(1);
+}
+let BRAND;
+try {
+    BRAND = JSON.parse(readFileSync(BRAND_PATH, "utf-8"));
+}
+catch (err) {
+    console.error(`Setup failed: failed to parse brand.json: ${err.message}`);
+    console.error(`FATAL: Failed to parse brand.json: ${err.message}`);
+    process.exit(1);
+}
+const INSTALL_DIR = resolve(process.env.HOME ?? "/root", BRAND.installDir);
+const LOG_DIR = resolve(process.env.HOME ?? "/root", BRAND.configDir, "logs");
+const LOG_FILE = join(LOG_DIR, `install-${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+/** Known brand hostnames in the Maxy ecosystem. Each brand ships a main unit
+ *  (`<hostname>.service`) and a per-brand edge unit (`<hostname>-edge.service`,
+ *  Task 662). Peer-brand detection matches only these filenames — stale units,
+ *  gnome-keyring disable markers, and unrelated user services are not peer
+ *  evidence. When a third brand is added under `brands/`, append its hostname
+ *  here AND in the matching constant in `uninstall.ts` (intentional duplication
+ *  per `uninstall.ts:` "Shell helpers (duplicated from index.ts ...)" policy). */
+const KNOWN_BRAND_HOSTNAMES = ["maxy", "realagent", "maxy-2", "maxy-3", "maxy-4"];
+// The device's actual hostname — may differ from BRAND.hostname if the user customized it.
+// Updated by installSystemDeps() after hostname setup; used for user-facing URLs.
+let DEVICE_HOSTNAME = BRAND.hostname;
+// Task 929 — absolute path to the non-snap Chromium binary chosen during
+// installSystemDeps(). Defaults to /usr/bin/chromium so non-Linux installs
+// (which never call ensureNonSnapChromium) and the systemd unit's
+// PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH still see a sensible value. On Linux,
+// installSystemDeps() always overwrites this — either /usr/bin/chromium (Pi
+// Bookworm: real .deb) or /usr/bin/google-chrome-stable (Ubuntu Noble laptop:
+// snap-confined chromium replaced). Read by writeChromiumBinaryPathFile()
+// and threaded into buildMaxyUnitFile() so the chromium-binary.path config
+// file, the systemd unit's PLAYWRIGHT env var, and vnc.sh's runtime resolver
+// all agree on one absolute path.
+let RESOLVED_CHROMIUM_BIN = "/usr/bin/chromium";
+// npm flags tuned for Raspberry Pi — reduce parallelism, increase patience
+const NPM_NET_FLAGS = [
+    "--fetch-retries=5",
+    "--fetch-retry-mintimeout=30000",
+    "--fetch-retry-maxtimeout=120000",
+    "--maxsockets=3",
+];
+// ---------------------------------------------------------------------------
+// Logging — timestamped to console AND persistent log file
+// ---------------------------------------------------------------------------
+function initLogging() {
+    mkdirSync(LOG_DIR, { recursive: true });
+    appendFileSync(LOG_FILE, [
+        "",
+        "=".repeat(64),
+        `  ${BRAND.productName} Install Log — ${new Date().toISOString()}`,
+        `  Node ${process.version} | ${process.platform} ${process.arch}`,
+        "=".repeat(64),
+        "",
+    ].join("\n") + "\n");
+}
+function logFile(msg) {
+    try {
+        appendFileSync(LOG_FILE, `[${new Date().toISOString()}] ${msg}\n`);
+    }
+    catch { /* fs full */ }
+}
+// Mirror all console output into the log file
+const _log = console.log;
+const _err = console.error;
+console.log = (...args) => { _log(...args); logFile(args.map(String).join(" ")); };
+console.error = (...args) => { _err(...args); logFile(`[ERROR] ${args.map(String).join(" ")}`); };
+// ---------------------------------------------------------------------------
+// Diagnostics — system state snapshot for post-mortem analysis
+// ---------------------------------------------------------------------------
+function logDiagnostics(label) {
+    logFile(`\n--- Diagnostics: ${label} ---`);
+    if (!isLinux()) {
+        logFile("  (not Linux — limited diagnostics)");
+        return;
+    }
+    const run = (cmd, args) => {
+        const r = spawnSync(cmd, args, { encoding: "utf-8", stdio: "pipe", timeout: 10_000 });
+        return (r.stdout || r.stderr || "").trim();
+    };
+    logFile(`Disk:\n${run("df", ["-h", "/", "/tmp"])}`);
+    logFile(`Memory:\n${run("free", ["-h"])}`);
+    logFile(`Uptime: ${run("uptime", [])}`);
+    for (const host of ["registry.npmjs.org", "github.com"]) {
+        const dns = spawnSync("host", ["-W", "5", host], { encoding: "utf-8", stdio: "pipe", timeout: 10_000 });
+        logFile(`DNS ${host}: ${dns.status === 0 ? "OK" : "FAIL"} — ${(dns.stdout || dns.stderr || "").trim().split("\n")[0]}`);
+    }
+    const curl = spawnSync("curl", [
+        "-sf", "-o", "/dev/null",
+        "-w", "HTTP %{http_code} in %{time_total}s (dns: %{time_namelookup}s, connect: %{time_connect}s)",
+        "--connect-timeout", "10",
+        "https://registry.npmjs.org/",
+    ], { encoding: "utf-8", stdio: "pipe", timeout: 15_000 });
+    logFile(`Registry HTTP: ${curl.stdout?.trim() || `FAIL — ${curl.stderr?.trim()}`}`);
+    logFile(`--- End Diagnostics ---\n`);
+}
+/** Append the most recent npm debug log into our install log for post-mortem. */
+function captureNpmDebugLog() {
+    const logsDir = resolve(process.env.HOME ?? "/root", ".npm/_logs");
+    if (!existsSync(logsDir))
+        return;
+    try {
+        const files = readdirSync(logsDir).filter(f => f.endsWith("-debug-0.log")).sort().reverse();
+        if (files[0]) {
+            const content = readFileSync(join(logsDir, files[0]), "utf-8");
+            logFile(`\n--- npm debug log: ${files[0]} (last 200 lines) ---`);
+            const lines = content.split("\n");
+            logFile(lines.slice(Math.max(0, lines.length - 200)).join("\n"));
+            logFile(`--- end npm debug log ---\n`);
+        }
+    }
+    catch { /* ignore */ }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function log(step, total, message) {
+    console.log(`[${step}/${total}] ${message}`);
+}
+function shell(command, args, options) {
+    const cmd = options?.sudo ? "sudo" : command;
+    const cmdArgs = options?.sudo ? [command, ...args] : args;
+    const start = Date.now();
+    // Redaction (Task 744): callers handling secrets pass redact: true so the
+    // wrapper records the command name only, not the secret-bearing args. The
+    // child process still receives the real args via spawnSync below; only the
+    // install log line is sanitised. The grep-able audit shape stays:
+    //   > sudo neo4j-admin dbms set-initial-password [REDACTED]
+    const loggedArgs = options?.redact
+        ? `${cmdArgs.slice(0, options?.sudo ? 4 : 3).join(" ")} [REDACTED]`
+        : cmdArgs.join(" ");
+    logFile(`> ${cmd} ${loggedArgs}${options?.cwd ? ` [cwd: ${options.cwd}]` : ""}`);
+    const result = spawnSync(cmd, cmdArgs, {
+        stdio: "inherit",
+        timeout: options?.timeout ?? 300_000,
+        cwd: options?.cwd,
+        env: options?.env,
+    });
+    const dur = ((Date.now() - start) / 1000).toFixed(1);
+    // bestEffort (Task 787): tear-down ops on units/state that may or may not
+    // exist (stop/disable a system service we may never have started, reset-failed
+    // a freshly-created unit) log the non-zero exit but do not throw. Reserved
+    // for the "may not exist" pattern only — never use for ops that must succeed.
+    if (result.signal) {
+        logFile(`  KILLED (${result.signal}) after ${dur}s`);
+        if (options?.bestEffort)
+            return;
+        throw new Error(`Command killed (${result.signal}) after ${dur}s: ${cmd} ${cmdArgs.join(" ")}`);
+    }
+    if (result.status !== 0) {
+        logFile(`  ${options?.bestEffort ? "best-effort non-zero" : "FAILED"} (exit ${result.status}) after ${dur}s`);
+        if (options?.bestEffort)
+            return;
+        throw new Error(`Command failed (exit ${result.status}) after ${dur}s: ${cmd} ${cmdArgs.join(" ")}`);
+    }
+    logFile(`  OK in ${dur}s`);
+}
+/** Wait until DNS resolves for a host. Returns true if recovered. */
+function waitForDns(host, maxSec = 60) {
+    for (let elapsed = 0; elapsed < maxSec; elapsed += 5) {
+        const r = spawnSync("host", ["-W", "3", host], { stdio: "pipe", timeout: 5_000 });
+        if (r.status === 0) {
+            logFile(`  DNS ${host}: recovered after ${elapsed}s`);
+            return true;
+        }
+        console.log(`  DNS ${host} not resolving — waiting (${elapsed}s/${maxSec}s)...`);
+        spawnSync("sleep", ["5"]);
+    }
+    return false;
+}
+/** Retry a shell command with exponential backoff. Runs network diagnostics between attempts. */
+function shellRetry(command, args, options, maxAttempts = 3, backoffSec = 20) {
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            shell(command, args, options);
+            return;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logFile(`  Attempt ${attempt}/${maxAttempts} error: ${msg}`);
+            if (attempt === maxAttempts) {
+                console.error(`  All ${maxAttempts} attempts failed.`);
+                logDiagnostics(`final failure — ${command}`);
+                if (command === "npm")
+                    captureNpmDebugLog();
+                throw err;
+            }
+            const wait = backoffSec * attempt;
+            console.log(`  Attempt ${attempt}/${maxAttempts} failed. Retrying in ${wait}s...`);
+            // On network errors, diagnose and wait for DNS recovery before retrying
+            if (/ETIMEDOUT|EAI_AGAIN|ECONNRESET|ENOTFOUND|ENETUNREACH/.test(msg)) {
+                console.log("  Network error — running diagnostics...");
+                logDiagnostics(`network failure — attempt ${attempt}`);
+                waitForDns("registry.npmjs.org");
+            }
+            if (command === "npm")
+                captureNpmDebugLog();
+            spawnSync("sleep", [String(wait)]);
+        }
+    }
+}
+function commandExists(cmd) {
+    try {
+        execFileSync("which", [cmd], { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function nodeVersion() {
+    try {
+        const v = execFileSync("node", ["-v"], { encoding: "utf-8" }).trim();
+        return parseInt(v.replace("v", "").split(".")[0], 10);
+    }
+    catch {
+        return 0;
+    }
+}
+function isLinux() {
+    return process.platform === "linux";
+}
+function isArm64() {
+    return process.arch === "arm64";
+}
+/** Check whether non-interactive sudo is available (passwordless or cached credentials). */
+function canSudo() {
+    const result = spawnSync("sudo", ["-n", "true"], { stdio: "pipe", timeout: 5_000 });
+    return result.status === 0;
+}
+// Task 634 — verified-not-asserted apt-dep reconciliation.
+// Task 637 — resolve package-name aliases before probing dpkg, so the
+// post-install check no longer false-negatives when apt resolves a virtual
+// name (e.g. Noble's `chromium` → `chromium-browser`).
+// UBUNTU_ALIASES, parseOsRelease, isUbuntuLike, and decideAptResolution moved
+// to ./apt-resolve.ts (Task 638). The pure logic lives there so a unit test
+// can hit every branch without spawning real apt/dpkg or reading
+// /etc/os-release. The thin wrappers below feed real spawn + fs results into
+// that pure decision.
+function readOsRelease() {
+    try {
+        return parseOsRelease(readFileSync("/etc/os-release", "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Summarise `apt-cache policy` output for diagnostics — one token per package. */
+function aptCachePolicySummary(pkg) {
+    const r = spawnSync("apt-cache", ["policy", pkg], { stdio: "pipe", encoding: "utf-8", timeout: 5_000 });
+    if (r.status !== 0)
+        return "policy-spawn-failed";
+    const cand = parseAptCacheCandidate(r.stdout ?? "");
+    if (cand === null)
+        return "no-candidate-line";
+    return cand === "(none)" ? "candidate-none" : `candidate=${cand}`;
+}
+/**
+ * Task 637 — map an apt-level package name to the concrete name dpkg will
+ * record after install. Resolution order:
+ *   1. `dpkg -s pkg` exits 0 → name is concrete and installed; return pkg.
+ *   2. `apt-cache policy pkg` reports a real Candidate → concrete-but-missing;
+ *      return pkg (apt-get install + post-check will use the same name).
+ *   3. `apt-cache policy pkg` reports `Candidate: (none)` and `pkg` is in
+ *      UBUNTU_ALIASES on an Ubuntu-like host → return the alias. Log the
+ *      resolution so the install log answers "what did apt resolve this to?".
+ *   4. Otherwise return pkg unchanged — the post-check will throw loudly,
+ *      preserving Task 634's fail-loud contract for genuinely missing packages.
+ */
+function resolveAptName(pkg) {
+    const dpkg = spawnSync("dpkg", ["-s", pkg], { stdio: "pipe", timeout: 5_000 });
+    const dpkgInstalled = dpkg.status === 0;
+    // Short-circuit: when dpkg already records the name as installed, skip the
+    // apt-cache + os-release work — `decideAptResolution` returns pkg unchanged
+    // anyway and the extra spawn would burn ~10 ms per already-installed
+    // package across every `pkgsMissing` pass.
+    if (dpkgInstalled)
+        return pkg;
+    const policy = spawnSync("apt-cache", ["policy", pkg], {
+        stdio: "pipe", encoding: "utf-8", timeout: 5_000,
+    });
+    const aptCandidate = policy.status === 0
+        ? parseAptCacheCandidate(policy.stdout ?? "")
+        : null;
+    const os = readOsRelease();
+    const decision = decideAptResolution({
+        pkg,
+        dpkgInstalled,
+        aptCandidate,
+        ubuntuLike: isUbuntuLikePure(os),
+        distro: `${os.ID ?? "unknown"}-${os.VERSION_CODENAME ?? "unknown"}`,
+    });
+    if (decision.log)
+        logFile(decision.log);
+    return decision.resolved;
+}
+/** Probe runtime binary presence on PATH (independent of dpkg-recorded state). */
+function commandVPath(pkg) {
+    const r = spawnSync("which", [pkg], { stdio: "pipe", encoding: "utf-8", timeout: 5_000 });
+    return r.status === 0 ? (r.stdout ?? "").trim() || "missing" : "missing";
+}
+/** Probe snap-recorded state for a name (snap lives outside dpkg). */
+function snapStatus(pkg) {
+    const r = spawnSync("snap", ["list", pkg], { stdio: "pipe", encoding: "utf-8", timeout: 5_000 });
+    if (r.status !== 0)
+        return "none";
+    const line = (r.stdout ?? "").split("\n").find((l) => l.startsWith(pkg));
+    return line ? line.split(/\s+/).slice(0, 2).join(" ") : "none";
+}
+/**
+ * Returns the subset of `pkgs` that are not currently installed, after
+ * alias resolution. Uses `dpkg -s <resolved>` per package (exit 0 = installed,
+ * any non-zero = missing) so we never parse dpkg's prose output for control
+ * flow (feedback_no_stdout_parsing_for_control_flow.md). The operator-facing
+ * name stays the original `pkg` — the resolution is logged but not renamed
+ * in the returned list, so diagnostics match what the installer declared.
+ */
+function pkgsMissing(pkgs) {
+    return pkgs.filter((p) => {
+        const resolved = resolveAptName(p);
+        const r = spawnSync("dpkg", ["-s", resolved], { stdio: "pipe", timeout: 5_000 });
+        return r.status !== 0;
+    });
+}
+/**
+ * Install a logical group of apt packages, then verify each one landed in
+ * dpkg's installed state. The post-install `dpkg -s` probe catches the
+ * partial-failure class where `apt-get install` returns 0 but a package did
+ * not actually install — silent regressions that would otherwise only
+ * surface at runtime when the binary is missing.
+ *
+ * Resolves each package through `resolveAptName` before both the install
+ * command and the post-check, so alias packages (Task 637) pass through
+ * cleanly on distros where the apt-level name differs from the dpkg-recorded
+ * name (e.g. Noble's chromium → chromium-browser). Resolution is computed
+ * once per package and reused across install, post-check, and error
+ * diagnostics — three spawnSync chains per package, not nine on failure.
+ */
+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 });
+        return r.status !== 0;
+    });
+    if (stillMissing.length > 0) {
+        const diag = stillMissing.map(({ original, resolved }) => `${original} (resolved-name=${resolved}, apt-cache-policy=${aptCachePolicySummary(original)}, command-v=${commandVPath(original)}, snap-status=${snapStatus(resolved)})`).join("; ");
+        throw new Error(`apt-get install (${label}) returned 0 but packages are still not installed per dpkg -s: ${diag}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Installation steps
+// ---------------------------------------------------------------------------
+const TOTAL = "11";
+/**
+ * Task 840 — set macOS hostname via scutil. Three sequential `sudo scutil
+ * --set` calls (HostName, LocalHostName, ComputerName) — `hostnamectl` is
+ * Linux-only and `--hostname <h>` silently no-ops on darwin. All-or-nothing
+ * rollback within the 3-call batch: if any call fails, we restore the
+ * pre-batch values for the keys we already changed and re-throw. Full
+ * system-state rollback (avahi, /etc/hosts) is out of scope per the brief.
+ */
+function setMacosHostnameViaScutil(hostname) {
+    const keys = ["HostName", "LocalHostName", "ComputerName"];
+    // Capture pre-batch values for rollback. Empty string is a legitimate
+    // scutil --get value (the key was never set) — preserve that as "" so
+    // rollback writes empty back rather than failing.
+    const previous = {};
+    for (const k of keys) {
+        const r = spawnSync("scutil", ["--get", k], { encoding: "utf-8", stdio: "pipe", timeout: 5_000 });
+        previous[k] = (r.stdout ?? "").trim();
+    }
+    const applied = [];
+    for (const k of keys) {
+        const r = spawnSync("sudo", ["scutil", "--set", k, hostname], { encoding: "utf-8", stdio: "inherit", timeout: 30_000 });
+        if (r.status !== 0) {
+            // Roll back any keys we already changed within this batch.
+            for (const done of applied) {
+                spawnSync("sudo", ["scutil", "--set", done, previous[done] ?? ""], { stdio: "inherit", timeout: 30_000 });
+            }
+            const stderr = r.stderr ? `: ${r.stderr.toString().trim()}` : "";
+            console.error(`  [scutil] ${k} failed${stderr}`);
+            throw new Error(`scutil --set ${k} ${hostname} exited ${r.status}`);
+        }
+        applied.push(k);
+    }
+    console.log(`  [scutil] HostName=${hostname} LocalHostName=${hostname} ComputerName=${hostname} set ok`);
+}
+/**
+ * Task 929 — detect snap-confined Chromium on Linux and install Google Chrome
+ * stable as the non-snap replacement. Runs after `installAptGroup("VNC stack")`
+ * inside `installSystemDeps`. Resolution rules live in `snap-chromium.ts`
+ * (pure decision); this wrapper does the spawnSync + apt-repo writes + post-
+ * install gate. Skipped on darwin (Maxy uses Playwright-managed Chromium per
+ * brew-install.ts) — RESOLVED_CHROMIUM_BIN keeps its `/usr/bin/chromium`
+ * default which is unused on darwin (no systemd unit).
+ *
+ * Detection: `command -v chromium` + `realpath`; an extra probe for
+ * `google-chrome-stable` covers re-run installs where a previous run already
+ * landed Chrome. Snap detection is the literal `snap` segment in the realpath
+ * (see isSnapConfinedPath in snap-chromium.ts) — covers the three real-world
+ * shapes (`/snap/bin/chromium`, `/snap/<rev>/usr/...`, `/usr/bin/snap` which
+ * is the snap launcher binary that `readlink -f` terminates at on Noble).
+ *
+ * Replacement: Google's signed apt repo (cryptographic verification via
+ * `signed-by=` GPG key) — the canonical pinned-deterministic source for
+ * Chrome stable. Pinning a specific Chrome version would require an out-of-
+ * band SHA-bump cadence and contradicts the apt-repo trust model.
+ *
+ * Post-install gate: spawn the resolved binary headless against a throwaway
+ * profile dir under persistDir, assert exit 0. The AppArmor denial that
+ * triggered Task 929 was on SingletonLock writes which `--headless=new` still
+ * attempts, so the headless probe fires the same EACCES path that production
+ * VNC headed launches do — closing the post-fix-sibling-audit-skipped gap.
+ */
+function ensureNonSnapChromium() {
+    if (process.platform !== "linux") {
+        logFile(`  ensureNonSnapChromium skipped: platform=${process.platform}`);
+        return;
+    }
+    const which = (cmd) => {
+        const r = spawnSync("command", ["-v", cmd], { stdio: "pipe", encoding: "utf-8", shell: "/bin/bash", timeout: 5_000 });
+        if (r.status !== 0)
+            return null;
+        const out = (r.stdout ?? "").trim();
+        return out || null;
+    };
+    const realpath = (path) => {
+        if (!path)
+            return null;
+        try {
+            return realpathSync(path);
+        }
+        catch {
+            return null;
+        }
+    };
+    const whichChromium = which("chromium");
+    const whichGoogleChrome = which("google-chrome-stable");
+    const decision = decideChromiumAction({
+        platform: "linux",
+        whichChromium,
+        realpathChromium: realpath(whichChromium),
+        whichGoogleChrome,
+        realpathGoogleChrome: realpath(whichGoogleChrome),
+    });
+    logFile(`  [snap-chromium] decision: ${decision.action} reason="${decision.reason}"`);
+    if (decision.action === "fail") {
+        throw new Error(`ensureNonSnapChromium: ${decision.reason}. apt install of \`chromium\` ran in installAptGroup(VNC stack) above; if its post-check passed but no chromium binary is on PATH, the system PATH is misconfigured.`);
+    }
+    if (decision.action === "install-google-chrome") {
+        console.log("  Detected snap-confined Chromium — installing Google Chrome stable...");
+        logFile(`  [snap-chromium] installing google-chrome-stable from Google's signed apt repo`);
+        // Fetch + dearmor the signing key, write to /etc/apt/trusted.gpg.d/. Pipe
+        // composition runs through bash -c so the curl|gpg pipeline is one
+        // privileged command rather than two separate sudo escalations.
+        console.log("  [privileged] curl + gpg --dearmor (Google Chrome signing key)");
+        shell("bash", ["-c",
+            "set -euo pipefail; " +
+                "curl -fsSL https://dl.google.com/linux/linux_signing_key.pub | " +
+                "gpg --dearmor --yes -o /etc/apt/trusted.gpg.d/google-chrome.gpg",
+        ], { sudo: true });
+        // Add the apt source list with `signed-by=` scoping so the key only
+        // verifies google-chrome-* packages, not arbitrary repo overrides. arch
+        // pinned to amd64 — Google does not ship arm64 Chrome for Linux.
+        console.log("  [privileged] tee /etc/apt/sources.list.d/google-chrome.list");
+        shell("bash", ["-c",
+            "echo 'deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/google-chrome.gpg] " +
+                "http://dl.google.com/linux/chrome/deb/ stable main' " +
+                "> /etc/apt/sources.list.d/google-chrome.list",
+        ], { sudo: true });
+        console.log("  [privileged] apt-get update");
+        shell("apt-get", ["update"], { sudo: true });
+        installAptGroup("Google Chrome stable", ["google-chrome-stable"]);
+        // Re-resolve after install to capture the now-installed absolute path.
+        const postInstallWhich = which("google-chrome-stable");
+        if (!postInstallWhich) {
+            throw new Error("ensureNonSnapChromium: apt install of google-chrome-stable returned 0 and dpkg -s passed, but `command -v google-chrome-stable` is empty — PATH is broken.");
+        }
+        RESOLVED_CHROMIUM_BIN = postInstallWhich;
+    }
+    else {
+        // action === "use" — decision.resolvedPath is the existing non-snap binary
+        // (chromium or google-chrome-stable already installed).
+        if (!decision.resolvedPath) {
+            throw new Error(`ensureNonSnapChromium: action=use returned without resolvedPath — bug in snap-chromium.ts (input: chromium=${whichChromium} google-chrome=${whichGoogleChrome})`);
+        }
+        RESOLVED_CHROMIUM_BIN = decision.resolvedPath;
+    }
+    // Defensive: never persist a snap-confined path. If realpath of the resolved
+    // binary still lands under /snap/ (e.g. apt landed a snap package by mistake
+    // on a misconfigured device), throw before writeChromiumBinaryPathFile sees
+    // it — the runtime gate in vnc.sh would refuse anyway, but failing here
+    // surfaces the contract breach with the install context still in scope.
+    const finalRealpath = realpath(RESOLVED_CHROMIUM_BIN);
+    if (isSnapConfinedPath(finalRealpath)) {
+        throw new Error(`ensureNonSnapChromium: resolved Chromium binary ${RESOLVED_CHROMIUM_BIN} realpaths to ${finalRealpath} which is under /snap/ — refusing to persist.`);
+    }
+    console.log(`  Chromium binary: ${RESOLVED_CHROMIUM_BIN} (realpath=${finalRealpath ?? "?"})`);
+    logFile(`  [snap-chromium] resolved bin=${RESOLVED_CHROMIUM_BIN} realpath=${finalRealpath ?? "null"}`);
+    runChromiumPostInstallGate(RESOLVED_CHROMIUM_BIN);
+}
+/**
+ * Task 929 post-install gate. Spawns the resolved Chromium binary headless
+ * against a throwaway profile dir under persistDir (`~/.{brand}/chromium-
+ * gate-profile/`). The AppArmor denial that triggered the task was on
+ * SingletonLock writes which `--headless=new` still attempts, so this probe
+ * fires the same EACCES path the headed VNC stack would. Cleans up the gate
+ * profile afterward — the live profile (`chromium-profile/`) is owned by
+ * vnc.sh's start_chrome and not touched here.
+ */
+function runChromiumPostInstallGate(chromiumBin) {
+    const persistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+    const gateProfileDir = join(persistDir, "chromium-gate-profile");
+    mkdirSync(gateProfileDir, { recursive: true });
+    console.log(`  Verifying ${chromiumBin} can write to ${gateProfileDir} (Task 929 post-install gate)...`);
+    const r = spawnSync(chromiumBin, [
+        `--user-data-dir=${gateProfileDir}`,
+        "--headless=new",
+        "--disable-gpu",
+        "--no-sandbox",
+        "--disable-dev-shm-usage",
+        "--dump-dom",
+        "about:blank",
+    ], { stdio: "pipe", encoding: "utf-8", timeout: 30_000 });
+    // Cleanup before throwing on failure so successive runs start clean.
+    try {
+        rmSync(gateProfileDir, { recursive: true, force: true });
+    }
+    catch { /* best-effort */ }
+    if (r.status !== 0) {
+        const stderr = (r.stderr ?? "").slice(-2000);
+        const eaccesHit = /Permission denied/i.test(stderr) || /EACCES/i.test(stderr);
+        const taskRef = eaccesHit
+            ? "Task 929: chromium-profile not writable (likely AppArmor denial on snap-confined binary). "
+            : "";
+        throw new Error(`${taskRef}Chromium post-install gate failed: ${chromiumBin} exited ${r.status} signal=${r.signal ?? "none"}. stderr:\n${stderr}`);
+    }
+    console.log("  Chromium post-install gate passed.");
+    logFile(`  [snap-chromium] post-install gate ok: ${chromiumBin} exit=0`);
+}
+/**
+ * Task 929 — write the resolved Chromium absolute path to
+ * `<INSTALL_DIR>/platform/config/chromium-binary.path` so vnc.sh,
+ * writeChromiumWrapper, and setup-tunnel.sh all read the same value. Called
+ * after deployPayload so the platform/config/ directory exists. Idempotent:
+ * re-running the installer with the same RESOLVED_CHROMIUM_BIN is a no-op
+ * write (writeFileSync overwrites in place).
+ */
+function writeChromiumBinaryPathFile() {
+    if (process.platform !== "linux") {
+        logFile(`  writeChromiumBinaryPathFile skipped: platform=${process.platform}`);
+        return;
+    }
+    const configDir = resolve(INSTALL_DIR, "platform/config");
+    mkdirSync(configDir, { recursive: true });
+    const target = join(configDir, "chromium-binary.path");
+    writeFileSync(target, RESOLVED_CHROMIUM_BIN + "\n", { mode: 0o644 });
+    console.log(`  Wrote ${target} → ${RESOLVED_CHROMIUM_BIN}`);
+    logFile(`  [snap-chromium] wrote ${target} contents=${RESOLVED_CHROMIUM_BIN}`);
+}
+function installSystemDeps() {
+    log("1", TOTAL, "System dependencies and network...");
+    const platform = requireSupportedPlatform(process.platform);
+    if (platform === "darwin") {
+        // Task 840 — darwin hostname via scutil when --hostname is supplied,
+        // otherwise preserve the existing system hostname.
+        if (HOSTNAME_FLAG) {
+            console.log(`  Hostname: ${HOSTNAME_FLAG} (from --hostname flag)`);
+            try {
+                setMacosHostnameViaScutil(HOSTNAME_FLAG);
+                DEVICE_HOSTNAME = HOSTNAME_FLAG;
+            }
+            catch (err) {
+                console.error(`  WARNING: Failed to set hostname to '${HOSTNAME_FLAG}': ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else {
+            try {
+                DEVICE_HOSTNAME = execFileSync("hostname", [], { encoding: "utf-8" }).trim();
+                console.log(`  Hostname: ${DEVICE_HOSTNAME} (preserved — no --hostname flag on darwin)`);
+            }
+            catch { /* fallback to brand — set at declaration */ }
+        }
+        // Task 839 — macOS has no apt analogue for the VNC/WiFi-AP stacks
+        // (kiosk display + hostapd/dnsmasq are Pi-specific per Task 836's
+        // out-of-scope note). mDNS is provided by the OS, so avahi-* drop out.
+        // Translate the remaining apt names through decideBrewResolution and
+        // let installAllBrewPackages handle the install + verify pattern.
+        const DARWIN_BASE_DEPS = ["curl", "git", "unzip", "jq", "poppler", "ffmpeg"];
+        installAllBrewPackages(DARWIN_BASE_DEPS, logFile);
+        return;
+    }
+    const BASE_DEPS = ["curl", "git", "unzip", "jq", "avahi-daemon", "avahi-utils", "poppler-utils", "ffmpeg", "bind9-dnsutils"];
+    // xterm is the *preferred* terminal-emulator binary for the VNC-rendered
+    // Terminal surface (Task 632 — gnome-terminal is a D-Bus launcher that
+    // delegates window creation to the session's gnome-terminal-server,
+    // opening windows on the wrong display; xterm has no IPC layer and
+    // honours DISPLAY directly). Kept in the apt list unconditionally so
+    // vnc.sh's resolve_terminal_bin has a display-safe binary on every
+    // supported distro (Ubuntu 24.04 noble/universe, Debian 12 bookworm/main
+    // verified). xdotool (Task 632) backs the post-spawn display-membership
+    // 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 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, ...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
+    // since the skip path became load-bearing on user-password-sudo devices).
+    const missing = pkgsMissing(ALL_APT_DEPS);
+    if (missing.length === 0) {
+        logFile(`  all system deps present per dpkg -s (${ALL_APT_DEPS.length} packages) — skipping apt install`);
+        console.log(`  All ${ALL_APT_DEPS.length} system deps already installed — skipping apt install.`);
+    }
+    else {
+        const canEscalate = canSudo() || process.stdout.isTTY === true;
+        if (!canEscalate) {
+            const repair = `sudo apt-get install -y ${missing.join(" ")}`;
+            console.error(`  MISSING ${missing.length} system deps per dpkg -s: ${missing.join(" ")}`);
+            console.error(`  Non-interactive sudo is unavailable; cannot prompt for password from a non-TTY shell.`);
+            console.error(`  Re-run this installer from an interactive shell, or repair manually:`);
+            console.error(`    ${repair}`);
+            logFile(`  FAIL: missing apt deps without interactive sudo: ${missing.join(",")}`);
+            throw new Error(`installSystemDeps: missing packages (${missing.join(", ")}) and sudo is unavailable non-interactively — repair with: ${repair}`);
+        }
+        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);
+        installAptGroup("WiFi AP", WIFI_DEPS);
+    }
+    // Task 929 — replace snap-confined Chromium with Google Chrome stable on
+    // Linux laptops (Ubuntu Noble) where `/usr/bin/chromium` realpaths to the
+    // snap launcher. The snap AppArmor profile denies writes to hidden top-level
+    // paths under $HOME, so any write to `~/.{brand}/chromium-profile/SingletonLock`
+    // hits EACCES and Chromium never starts the CDP listener. Always sets
+    // RESOLVED_CHROMIUM_BIN even on Pi Bookworm (where the path is unchanged),
+    // so deployPayload's writeChromiumBinaryPathFile and installService's
+    // buildMaxyUnitFile both have a real absolute path to thread through.
+    ensureNonSnapChromium();
+    // Hostname resolution — four sources, in priority order:
+    //   1. --hostname flag (unconditional — the caller is the authority)
+    //   2. OS detection on same-brand upgrade (service exists → keep whatever is currently set)
+    //   3. OS preservation on multi-brand device (another brand's service detected → keep hostname)
+    //   4. BRAND.hostname on fresh install (brand default)
+    if (HOSTNAME_FLAG) {
+        // --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)`);
+            }
+            catch { /* avahi-daemon.conf may not exist — non-critical */ }
+            // Restart avahi-daemon so the new hostname takes effect immediately
+            // and any stale "maxytest-2" auto-renamed records from a previous
+            // boot's hostname-conflict cycle are withdrawn. Without this,
+            // avahi-resolve -n <hostname>.local times out from the device itself
+            // because the daemon is still advertising the previous identity.
+            try {
+                console.log("  [privileged] systemctl restart avahi-daemon");
+                shell("systemctl", ["restart", "avahi-daemon"], { sudo: true });
+            }
+            catch (err) {
+                console.error(`  WARNING: avahi-daemon restart failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        catch (err) {
+            console.error(`  WARNING: Failed to set hostname to '${HOSTNAME_FLAG}': ${err instanceof Error ? err.message : String(err)}`);
+        }
+        DEVICE_HOSTNAME = HOSTNAME_FLAG;
+    }
+    else {
+        // No flag — fall back to detection (upgrade) or brand default (fresh install).
+        // Check for this brand's service (same-brand upgrade) and any other brand's service
+        // (multi-brand device). On a multi-brand device, hostname is a device-level concern
+        // set by the user or the first installer — subsequent brands must not overwrite it.
+        const systemdUserDir = resolve(process.env.HOME ?? "/root", ".config/systemd/user");
+        const serviceExists = existsSync(join(systemdUserDir, BRAND.serviceName));
+        // Task 690: narrow peer detection to KNOWN_BRAND_HOSTNAMES. The previous
+        // predicate ("any *.service that isn't ours") matched stray user units
+        // such as a `gnome-keyring-daemon.service -> /dev/null` disable marker,
+        // silently flipping single-brand fresh installs into the "preserve hostname"
+        // branch. Mirrors Task 683's `peerBrandPresent` allowlist in `uninstall.ts`.
+        let otherBrandService = false;
+        if (!serviceExists) {
+            const peerUnits = KNOWN_BRAND_HOSTNAMES
+                .filter((h) => h !== BRAND.hostname)
+                .flatMap((h) => [`${h}.service`, `${h}-edge.service`]);
+            try {
+                const files = new Set(readdirSync(systemdUserDir));
+                otherBrandService = peerUnits.some((unit) => files.has(unit));
+            }
+            catch { /* directory may not exist on a fresh device — not an error */ }
+        }
+        // "raspberrypi" is the Pi factory default — it means "never configured,"
+        // not "the admin chose this hostname."  Treat it the same as a fresh install.
+        const FACTORY_HOSTNAMES = ["raspberrypi", "localhost"];
+        let hostnameSetAttempted = false;
+        try {
+            const currentHostname = execFileSync("hostname", [], { encoding: "utf-8" }).trim();
+            const isFactory = FACTORY_HOSTNAMES.includes(currentHostname);
+            if (currentHostname === BRAND.hostname) {
+                console.log(`  Hostname: ${currentHostname} (detected from OS)`);
+            }
+            else if (serviceExists && !isFactory) {
+                // Upgrade: admin-chosen hostname — preserve it.
+                console.log(`  Hostname: ${currentHostname} (detected from OS — differs from brand '${BRAND.hostname}')`);
+            }
+            else if (otherBrandService && !isFactory) {
+                // Multi-brand: another brand set the hostname — preserve it.
+                console.log(`  Hostname preserved: ${currentHostname} (another brand service detected)`);
+            }
+            else {
+                // Fresh install, OR a factory default that was never changed.
+                const reason = isFactory && serviceExists
+                    ? `factory default '${currentHostname}' was never changed`
+                    : `brand default — fresh install, was '${currentHostname}'`;
+                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)`);
+                    }
+                    catch { /* avahi-daemon.conf may not exist — non-critical */ }
+                }
+                catch (err) {
+                    console.error(`  WARNING: Could not set hostname to '${BRAND.hostname}': ${err instanceof Error ? err.message : String(err)}`);
+                    console.error(`  After install, run: sudo hostnamectl set-hostname ${BRAND.hostname}`);
+                }
+            }
+        }
+        catch (err) {
+            console.error(`  WARNING: Could not detect hostname: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Read the actual hostname after any changes — used for user-facing URLs.
+        try {
+            DEVICE_HOSTNAME = execFileSync("hostname", [], { encoding: "utf-8" }).trim();
+        }
+        catch { /* fallback to brand — set at declaration */ }
+        // If we attempted to set the hostname but it didn't take, use the brand
+        // hostname for the completion URL.  The user needs the URL that will work
+        // after a reboot or manual hostname fix — not the stale factory default.
+        if (hostnameSetAttempted && DEVICE_HOSTNAME !== BRAND.hostname) {
+            console.error(`  WARNING: Hostname is still '${DEVICE_HOSTNAME}' — using '${BRAND.hostname}' for the completion URL.`);
+            DEVICE_HOSTNAME = BRAND.hostname;
+        }
+    }
+    // Avahi service file for LAN discovery
+    const avahiService = `<?xml version="1.0" standalone='no'?>
+<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
+<service-group>
+  <name replace-wildcards="yes">${BRAND.productName} on %h</name>
+  <service>
+    <type>_http._tcp</type>
+    <port>${PORT}</port>
+    <txt-record>role=${BRAND.hostname}</txt-record>
+  </service>
+</service-group>`;
+    const avahiTmpPath = `/tmp/${BRAND.hostname}-avahi.service`;
+    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 */ }
+    // Hostname collision detection: check if another device already claims this hostname.
+    // Avahi appends -2 on collision, which causes the agent to construct URLs to the wrong device.
+    try {
+        const resolveResult = spawnSync("avahi-resolve", ["-n", `${BRAND.hostname}.local`], {
+            encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (resolveResult.status === 0 && resolveResult.stdout.trim()) {
+            const resolvedIp = resolveResult.stdout.trim().split(/\s+/)[1];
+            // Get this device's IP addresses to compare
+            const hostnameResult = spawnSync("hostname", ["-I"], { encoding: "utf-8", timeout: 3000 });
+            const localIps = hostnameResult.stdout?.trim().split(/\s+/) ?? [];
+            if (resolvedIp && !localIps.includes(resolvedIp)) {
+                console.log(`  WARNING: ${BRAND.hostname}.local already resolves to ${resolvedIp} — this device may get ${BRAND.hostname}-2.local`);
+                logFile(`  WARNING: hostname collision detected — ${BRAND.hostname}.local resolves to ${resolvedIp}, local IPs: ${localIps.join(", ")}`);
+            }
+        }
+    }
+    catch { /* non-critical — avahi-resolve may not be ready yet */ }
+    // Disable WiFi power management — the Pi's WiFi driver aggressively sleeps
+    // the radio between transmissions, causing dropped DNS/mDNS packets and
+    // intermittent connection resets on LAN.
+    try {
+        const nmConfDir = "/etc/NetworkManager/conf.d";
+        const nmConfFile = join(nmConfDir, `${BRAND.hostname}-no-powersave.conf`);
+        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" });
+        }
+    }
+    catch { /* not critical — wired connections unaffected */ }
+    console.log(`  Device reachable at http://${DEVICE_HOSTNAME}.local:${PORT}`);
+}
+function installNodejs() {
+    if (commandExists("node") && nodeVersion() >= 20) {
+        log("2", TOTAL, `Node.js v${nodeVersion()} already installed.`);
+        return;
+    }
+    log("2", TOTAL, "Installing Node.js...");
+    const platform = requireSupportedPlatform(process.platform);
+    if (platform === "darwin") {
+        // Pass the apt-side `nodejs` name; decideBrewResolution maps it to
+        // `node@22` per DARWIN_ALIASES so the cellar formula matches Maxy's
+        // pinned-binaries floor (Task 836).
+        installAllBrewPackages(["nodejs"], logFile);
+        return;
+    }
+    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() {
+    let needsInstall = true;
+    if (commandExists("claude")) {
+        try {
+            // `claude --version` prints "2.1.114 (Claude Code)" — extract the semver so
+            // the equality check against `npm view` (which returns bare "2.1.114") works.
+            const rawVersion = execFileSync("claude", ["--version"], { encoding: "utf-8", timeout: 10_000 }).trim();
+            const installed = rawVersion.match(/^(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/)?.[1] ?? rawVersion;
+            let latest = null;
+            try {
+                latest = execFileSync("npm", ["view", "@anthropic-ai/claude-code", "version"], { encoding: "utf-8", timeout: 30_000 }).trim();
+            }
+            catch {
+                logFile("  Could not check latest version — will attempt install anyway");
+            }
+            if (latest && installed === latest) {
+                log("3", TOTAL, `Claude Code v${installed} already up to date.`);
+                needsInstall = false;
+            }
+            else {
+                log("3", TOTAL, `Upgrading Claude Code (${installed}${latest ? ` → ${latest}` : ""})...`);
+            }
+        }
+        catch {
+            log("3", TOTAL, "Claude Code found but version check failed. Reinstalling...");
+        }
+    }
+    else {
+        log("3", TOTAL, "Installing Claude Code...");
+    }
+    if (needsInstall) {
+        // `npm install -g` needs write access to the global prefix, which on Linux is
+        // root-owned by default — so we run it under sudo. When sudo requires a password
+        // and the installer is running non-interactively (e.g. systemd-run --scope on
+        // upgrade), sudo fails instantly. Skip the upgrade in that case; the running
+        // installation is assumed adequate. Matches the apt-get skip in step 1.
+        if (isLinux() && !canSudo()) {
+            console.log("  Skipping Claude Code upgrade (sudo unavailable non-interactively — keeping installed version)");
+        }
+        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);
+        }
+    }
+    console.log("  Registering Claude plugin marketplaces...");
+    const marketplaceList = spawnSync("claude", ["plugin", "marketplace", "list"], { stdio: "pipe", encoding: "utf-8" });
+    if (marketplaceList.stderr)
+        process.stderr.write(marketplaceList.stderr);
+    const listed = marketplaceList.stdout ?? "";
+    // Task 976: register three Anthropic marketplaces uniformly with
+    // [plugin-marketplace] observability. Each slug is grep-checked against
+    // `marketplace list` for idempotence; failures log exit + first stderr
+    // line but do not abort the installer (one marketplace's outage must not
+    // block the others).
+    // `slug` is the GitHub repo path passed to `marketplace add`. `marketplaceName`
+    // is the marketplace's declared `name` from its .claude-plugin/marketplace.json —
+    // what `marketplace list` prints and what `<plugin>@<marketplace>` resolves on
+    // install. For FSI the two diverge: repo `anthropics/financial-services`,
+    // marketplace name `claude-for-financial-services`. The idempotence check
+    // greps the declared name to avoid substring false-positives.
+    const MARKETPLACES = [
+        { slug: "anthropics/claude-plugins-official", marketplaceName: "claude-plugins-official" },
+        { slug: "anthropics/knowledge-work-plugins", marketplaceName: "knowledge-work-plugins" },
+        { slug: "anthropics/financial-services", marketplaceName: "claude-for-financial-services" },
+    ];
+    for (const { slug, marketplaceName } of MARKETPLACES) {
+        if (listed.includes(marketplaceName)) {
+            logFile(`[plugin-marketplace] added ${slug} idempotent=true`);
+            continue;
+        }
+        const add = spawnSync("claude", ["plugin", "marketplace", "add", slug], { stdio: "pipe", encoding: "utf-8", timeout: 60_000 });
+        if (add.status === 0) {
+            logFile(`[plugin-marketplace] added ${slug} idempotent=false`);
+        }
+        else {
+            const stderrShort = (add.stderr ?? "").split("\n")[0]?.slice(0, 200) ?? "";
+            logFile(`[plugin-marketplace] ERROR add ${slug} exit=${add.status} stderr=${JSON.stringify(stderrShort)}`);
+        }
+    }
+    console.log("  Configuring git to use HTTPS for GitHub (plugin install support)...");
+    shell("git", ["config", "--global", "url.https://github.com/.insteadOf", "git@github.com:"]);
+    // Remove the Playwright plugin if previously installed. The programmatic MCP
+    // server in claude-agent.ts (with --cdp-endpoint) is the single correct path.
+    // The plugin creates a shadow server that intermittently handles tool calls
+    // without --cdp-endpoint, causing Chrome launch failures on ARM64.
+    const pluginList = spawnSync("claude", ["plugin", "list"], { stdio: "pipe", encoding: "utf-8" });
+    if (pluginList.stdout?.includes("playwright")) {
+        console.log("  Removing Playwright plugin (replaced by programmatic CDP server)...");
+        spawnSync("claude", ["plugin", "uninstall", "playwright"], { stdio: "inherit" });
+    }
+    // Ensure @playwright/mcp and all its dependencies (including playwright-core)
+    // are cached. Wipe any stale npx cache for it first — killed installs on Pi
+    // leave corrupt temp dirs that block subsequent npm operations.
+    console.log("  Pre-caching Playwright MCP server...");
+    const npxDir = resolve(process.env.HOME ?? "/root", ".npm/_npx");
+    const findResult = spawnSync("find", [npxDir, "-path", "*/@playwright/mcp/package.json", "-print", "-quit"], {
+        encoding: "utf-8", stdio: "pipe",
+    });
+    const existingCache = findResult.stdout?.trim();
+    if (existingCache) {
+        // Nuke the entire npx cache entry to avoid ENOTEMPTY errors
+        const cacheEntry = resolve(existingCache, "../../..");
+        spawnSync("rm", ["-rf", cacheEntry], { stdio: "pipe" });
+    }
+    // Fresh install — npx creates a clean cache with all deps
+    const npxResult = spawnSync("npx", ["-y", "@playwright/mcp@latest", "--version"], {
+        stdio: "pipe",
+        timeout: 180000,
+        encoding: "utf-8",
+    });
+    // Verify playwright-core landed
+    const verifyResult = spawnSync("find", [npxDir, "-path", "*/playwright-core/package.json", "-print", "-quit"], {
+        encoding: "utf-8", stdio: "pipe",
+    });
+    if (verifyResult.stdout?.trim()) {
+        console.log("  Playwright MCP server cached with all dependencies.");
+    }
+    else {
+        console.log(`  Warning: Playwright MCP cache may be incomplete (browser automation may not work).${npxResult.stderr ? ` npx stderr: ${npxResult.stderr.slice(0, 200)}` : ""}`);
+    }
+}
+function resetNeo4jAuth(port = DEFAULT_NEO4J_PORT, dataDir = "/var/lib/neo4j") {
+    const password = randomBytes(24).toString("base64url");
+    const dedicated = port !== DEFAULT_NEO4J_PORT;
+    const serviceName = dedicated ? `neo4j-${BRAND.hostname}` : "neo4j";
+    console.log(`  Resetting Neo4j auth with fresh password (${serviceName})...`);
+    spawnSync("sudo", ["systemctl", "stop", serviceName], { stdio: "inherit" });
+    // Clear the system database (stores auth/roles) and dbms auth config.
+    // The neo4j user database (graph data) is preserved.
+    // set-initial-password only works before the system DB's first start,
+    // so we must delete it to make Neo4j treat the next start as initial.
+    spawnSync("sudo", ["rm", "-rf",
+        `${dataDir}/data/dbms`,
+        `${dataDir}/data/databases/system`,
+        `${dataDir}/data/transactions/system`,
+    ], { stdio: "inherit" });
+    if (dedicated) {
+        const confDir = `/etc/neo4j-${BRAND.hostname}`;
+        // sudo env VAR=val passes the variable through sudo's env_reset
+        spawnSync("sudo", ["env", `NEO4J_CONF=${confDir}`, "neo4j-admin", "dbms", "set-initial-password", "--", password], {
+            stdio: "inherit",
+        });
+    }
+    else {
+        console.log("  [privileged] neo4j-admin dbms");
+        shell("neo4j-admin", ["dbms", "set-initial-password", "--", password], { sudo: true, redact: 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++) {
+        const check = spawnSync("cypher-shell", [
+            "-u", "neo4j", "-p", password,
+            "-a", `bolt://localhost:${port}`,
+            "RETURN 1",
+        ], { stdio: "pipe", timeout: 5000 });
+        if (check.status === 0)
+            break;
+        spawnSync("sleep", ["2"]);
+    }
+    return password;
+}
+/**
+ * Task 744 — scrub plaintext neo4j passwords from pre-fix install-*.log files.
+ * Calls platform/scripts/redact-install-logs.sh against the installer's LOG_DIR.
+ * The script is idempotent; re-running on clean logs is a no-op. Failures here
+ * are non-fatal — credential redaction is best-effort cleanup, not a blocker
+ * for installation.
+ */
+function redactInstallLogs() {
+    const script = resolve(INSTALL_DIR, "platform/scripts/redact-install-logs.sh");
+    if (!existsSync(script)) {
+        logFile("[redact-install-logs] script not found at " + script + " — skipping");
+        return;
+    }
+    const r = spawnSync("bash", [script, "--dir", LOG_DIR], {
+        stdio: "pipe",
+        encoding: "utf-8",
+        timeout: 30_000,
+    });
+    if (r.stdout)
+        logFile(r.stdout.trim());
+    if (r.status !== 0 && r.stderr)
+        logFile("[redact-install-logs] WARN " + r.stderr.trim());
+}
+/** Check Neo4j has a working password. Called AFTER deploy so config is in place. */
+function ensureNeo4jPassword() {
+    const passwordFile = join(INSTALL_DIR, "platform/config/.neo4j-password");
+    const configDir = resolve(INSTALL_DIR, "platform/config");
+    mkdirSync(configDir, { recursive: true });
+    const persistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+    const persistentPasswordFile = join(persistDir, ".neo4j-password");
+    // Dedicated instances have their own auth database — password checks and resets
+    // must target the dedicated port and data directory, not the shared instance.
+    const dataDir = NEO4J_DEDICATED ? `/var/lib/neo4j-${BRAND.hostname}` : "/var/lib/neo4j";
+    // 1. Same-brand check: if our own password file exists and works, done (upgrade path).
+    if (existsSync(passwordFile)) {
+        const existingPassword = readFileSync(passwordFile, "utf-8").trim();
+        if (neo4jPasswordWorks(existingPassword, NEO4J_PORT)) {
+            logFile(`  Neo4j password: already configured (port ${NEO4J_PORT})`);
+            return;
+        }
+        if (NEO4J_DEDICATED) {
+            console.log("  Stored password doesn't match dedicated Neo4j instance.");
+        }
+        else {
+            console.log("  Stored password doesn't match Neo4j. Resetting auth.");
+        }
+    }
+    // 2. Fresh install or recovery: no working same-brand password. Generate and set a new one.
+    //    Brand isolation (Task 659): never read another brand's .neo4j-password.
+    if (!existsSync(passwordFile)) {
+        console.log("  No Neo4j password file found. Setting initial password...");
+    }
+    // Reset auth and set a new password. Graph data is preserved —
+    // only the auth config ({dataDir}/data/dbms/) is cleared.
+    const hasData = existsSync(`${dataDir}/data/databases/neo4j`);
+    if (hasData) {
+        console.log("  Neo4j has existing data. Resetting auth only (data preserved)...");
+        logFile(`  Neo4j auth reset — clearing dbms auth in ${dataDir}, preserving databases + transactions`);
+    }
+    const password = resetNeo4jAuth(NEO4J_PORT, dataDir);
+    writeFileSync(passwordFile, password, { mode: 0o600 });
+    mkdirSync(persistDir, { recursive: true });
+    writeFileSync(persistentPasswordFile, password, { mode: 0o600 });
+    logFile("  Neo4j password: generated new");
+}
+/** Test a Neo4j password against the running instance on the given port. */
+function neo4jPasswordWorks(password, port = DEFAULT_NEO4J_PORT) {
+    const check = spawnSync("cypher-shell", [
+        "-u", "neo4j", "-p", password,
+        "-a", `bolt://localhost:${port}`,
+        "RETURN 1",
+    ], { stdio: "pipe", timeout: 10000 });
+    return check.status === 0;
+}
+function installNeo4j() {
+    if (commandExists("neo4j")) {
+        log("4", TOTAL, "Neo4j already installed.");
+        return;
+    }
+    log("4", TOTAL, "Installing Neo4j Community Edition 5...");
+    const platform = requireSupportedPlatform(process.platform);
+    if (platform === "darwin") {
+        // Homebrew's neo4j formula declares openjdk as a runtime dependency, so
+        // Java is pulled in transitively — no separate openjdk install step.
+        // Process supervision (launchd LaunchAgent) is owned by Task 838; this
+        // step ends after `brew install neo4j` + initial-password seeding so the
+        // payload deploy step finds the shared password file.
+        installAllBrewPackages(["neo4j"], logFile);
+        // Generate strong random password — stored in persistent location (~/{configDir}/)
+        const password = randomBytes(24).toString("base64url");
+        const persistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+        mkdirSync(persistDir, { recursive: true });
+        writeFileSync(join(persistDir, ".neo4j-password"), password, { mode: 0o600 });
+        const configDir = resolve(INSTALL_DIR, "platform/config");
+        mkdirSync(configDir, { recursive: true });
+        writeFileSync(join(configDir, ".neo4j-password"), password, { mode: 0o600 });
+        // Persist Neo4j data under ~/.maxy/neo4j-data/ per the task brief, so a
+        // brew uninstall (which removes the cellar) does not destroy the graph.
+        const neo4jDataDir = resolve(process.env.HOME ?? "/root", BRAND.configDir, "neo4j-data");
+        mkdirSync(neo4jDataDir, { recursive: true });
+        shell("neo4j-admin", ["dbms", "set-initial-password", "--", password], { redact: true });
+        console.log("  Neo4j installed via Homebrew. Password stored securely.");
+        return;
+    }
+    // Neo4j 5.x supports Java 17 and 21. Debian Bookworm ships 17, Trixie ships 21.
+    // apt-cache policy shows "Candidate: (none)" when no installable version exists.
+    const policyResult = spawnSync("apt-cache", ["policy", "openjdk-17-jre-headless"], { stdio: "pipe" });
+    const policyOutput = policyResult.stdout?.toString() ?? "";
+    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");
+    const persistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+    mkdirSync(persistDir, { recursive: true });
+    writeFileSync(join(persistDir, ".neo4j-password"), password, { mode: 0o600 });
+    // Also write to install dir (will be there when deploy step runs)
+    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, redact: 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.");
+}
+/**
+ * Task 800 — does any peer brand on this host pin `NEO4J_URI=bolt://localhost:<default>`
+ * in its `.env`? If yes, the apt-installed `neo4j.service` is its database and the
+ * dedicated-unit installer must NOT stop+disable it. Returns the first matching
+ * peer's hostname, or `null` when no peer pins the default port.
+ *
+ * Wraps the pure decision in `peer-brand-detect.ts` with the fs reads of
+ * `~/.<peer>/.env`. Bias on read errors: if `.env` exists but is unreadable
+ * (permissions, transient I/O), the wrapper treats that peer as a *potential*
+ * dependency and short-circuits to the kept-active path. Disabling the system
+ * unit on faulty evidence would silently kill the peer's database (the exact
+ * failure Task 800 prevents); a conservatively-skipped disable is recoverable
+ * because the dedicated-unit bind check at the end of `setupDedicatedNeo4j`
+ * fails loud if the system unit is actually free.
+ */
+function peerBrandUsingSystemUnit() {
+    const home = process.env.HOME ?? "/root";
+    const peerEnvContents = [];
+    for (const hostname of KNOWN_BRAND_HOSTNAMES) {
+        if (hostname === BRAND.hostname) {
+            peerEnvContents.push([hostname, null]);
+            continue;
+        }
+        const envPath = resolve(home, `.${hostname}`, ".env");
+        if (!existsSync(envPath)) {
+            peerEnvContents.push([hostname, null]);
+            continue;
+        }
+        try {
+            peerEnvContents.push([hostname, readFileSync(envPath, "utf-8")]);
+        }
+        catch (err) {
+            console.error(`  WARNING: unable to read peer brand .env at ${envPath} — treating as potential dependency to avoid data loss: ${err instanceof Error ? err.message : String(err)}`);
+            return hostname;
+        }
+    }
+    return findPeerBrandOnDefaultNeo4jPort({
+        currentBrandHostname: BRAND.hostname,
+        defaultNeo4jPort: DEFAULT_NEO4J_PORT,
+        peerEnvContents,
+    });
+}
+/**
+ * Create a dedicated Neo4j instance for this brand when NEO4J_DEDICATED is true.
+ * Produces: separate config dir, data dir, log dir, systemd service, and password.
+ * On upgrade (config already exists), skips conf creation — but always runs the
+ * Task 787 state-remediation block (stop/disable system unit, reset-failed
+ * dedicated, start, verify) so a half-installed Pi recovers in-place without
+ * manual systemctl. ensureNeo4jPassword() handles password verification on the
+ * recovery path.
+ *
+ * Task 800: on multi-brand hosts where a peer brand still depends on the apt
+ * `neo4j.service` (port 7687), the stop+disable step is skipped — disabling
+ * the system unit would kill the peer's database.
+ */
+function setupDedicatedNeo4j() {
+    if (!NEO4J_DEDICATED)
+        return;
+    const brandSuffix = BRAND.hostname; // e.g., "realagent"
+    const confDir = `/etc/neo4j-${brandSuffix}`;
+    const dataDir = `/var/lib/neo4j-${brandSuffix}`;
+    const logDir = `/var/log/neo4j-${brandSuffix}`;
+    const serviceName = `neo4j-${brandSuffix}`;
+    const httpPort = NEO4J_PORT - 213; // Preserve standard 7687/7474 offset
+    // Per-brand state (sed, mkdir, chown, unit-write) is idempotent and runs on
+    // every install. Only the base-config copy and initial-password rotation are
+    // gated to first install — Task 787 established that state remediation must
+    // run every install; Task 979 extended the same principle to the conf and
+    // unit emission so a half-installed host (broken unit missing NEO4J_HOME)
+    // recovers on retry without an out-of-band manual reset.
+    const confExists = spawnSync("test", ["-f", `${confDir}/neo4j.conf`], { stdio: "pipe" }).status === 0;
+    if (confExists) {
+        console.log(`  Dedicated Neo4j instance for ${BRAND.productName} already configured at ${confDir} — re-applying per-brand state`);
+        logFile(`  Neo4j dedicated: existing config at ${confDir}, re-applying sed/mkdir/chown/unit on every install`);
+    }
+    else {
+        console.log(`  Setting up dedicated Neo4j instance for ${BRAND.productName} on bolt://localhost:${NEO4J_PORT}...`);
+        // Pre-check: neo4j user must exist (created by the apt package)
+        const neo4jUserCheck = spawnSync("id", ["neo4j"], { stdio: "pipe" });
+        if (neo4jUserCheck.status !== 0) {
+            throw new Error("Neo4j system user 'neo4j' not found. Is Neo4j installed via apt?");
+        }
+        // Pre-check: source config must exist
+        if (!existsSync("/etc/neo4j/neo4j.conf")) {
+            throw new Error("/etc/neo4j/neo4j.conf not found. Cannot create dedicated instance without base config.");
+        }
+        // Copy base config (first install only — sed runs unconditionally below)
+        console.log("  [privileged] cp -r");
+        shell("cp", ["-r", "/etc/neo4j", confDir], { sudo: true });
+    }
+    // Idempotent per-brand state — runs on every install (Task 979).
+    // sed `s|^#?key=.*|key=value|` no-ops when the file already has the target
+    // value; mkdir -p, chown -R, and unit-write are idempotent by definition.
+    // NEO4J_HOME=${dataDir} makes server.directories.run resolve per-brand to
+    // ${dataDir}/run, so the launcher's pre-flight does not collide with the
+    // system unit's /var/lib/neo4j/run/neo4j.pid (Task 979 root cause). Plugins
+    // and import are sed-overridden because the apt base conf pins them to
+    // absolute /var/lib/neo4j/plugins and /var/lib/neo4j/import (shared).
+    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 });
+    console.log("  [privileged] sed -i");
+    shell("sed", ["-i", `s|^#\\?server\\.directories\\.plugins=.*|server.directories.plugins=${dataDir}/plugins|`, `${confDir}/neo4j.conf`], { sudo: true });
+    console.log("  [privileged] sed -i");
+    shell("sed", ["-i", `s|^#\\?server\\.directories\\.import=.*|server.directories.import=${dataDir}/import|`, `${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" });
+    if (confContent.status !== 0) {
+        console.error(`  WARNING: neo4j.conf may not have been updated correctly — bolt port ${NEO4J_PORT} not found in config`);
+        logFile(`  WARNING: sed verification failed — bolt port ${NEO4J_PORT} not found in ${confDir}/neo4j.conf`);
+    }
+    console.log("  [privileged] mkdir -p");
+    shell("mkdir", ["-p", `${dataDir}/data`, `${dataDir}/plugins`, `${dataDir}/import`, logDir], { sudo: true });
+    console.log("  [privileged] chown -R");
+    shell("chown", ["-R", "neo4j:neo4j", dataDir, logDir, confDir], { sudo: true });
+    const serviceContent = `[Unit]
+Description=Neo4j Graph Database (${BRAND.productName})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/bin/neo4j console
+Restart=on-failure
+User=neo4j
+Group=neo4j
+Environment="NEO4J_CONF=${confDir}" "NEO4J_HOME=${dataDir}"
+LimitNOFILE=60000
+
+[Install]
+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]);
+    logFile(`  [neo4j] dedicated unit env: NEO4J_CONF=${confDir} NEO4J_HOME=${dataDir}`);
+    if (!confExists) {
+        // Set initial password before first start (first install only — rotation
+        // on retry would brick an existing DB whose password is already stored).
+        const password = randomBytes(24).toString("base64url");
+        const persistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+        mkdirSync(persistDir, { recursive: true });
+        writeFileSync(join(persistDir, ".neo4j-password"), password, { mode: 0o600 });
+        const configDir = resolve(INSTALL_DIR, "platform/config");
+        mkdirSync(configDir, { recursive: true });
+        writeFileSync(join(configDir, ".neo4j-password"), password, { mode: 0o600 });
+        // sudo env VAR=val passes NEO4J_CONF through sudo's env_reset policy
+        spawnSync("sudo", ["env", `NEO4J_CONF=${confDir}`, "neo4j-admin", "dbms", "set-initial-password", "--", password], {
+            stdio: "inherit",
+        });
+    }
+    // ============================================================================
+    // Task 787 — unified state remediation + start + verify.
+    //
+    // Runs on both fresh and recovery paths. The dedicated unit and the apt
+    // package's system unit both exec /usr/bin/neo4j console without overriding
+    // NEO4J_HOME, so server.directories.run resolves to /var/lib/neo4j/run for
+    // both — the launcher refuses with "Neo4j is already running (pid:N)" if
+    // the system unit holds the PID file. Stopping the system unit first frees
+    // the run-state; disabling prevents it returning at next boot. reset-failed
+    // clears any prior start-limit-hit from a half-installed Pi.
+    // ============================================================================
+    spawnSync("sudo", ["systemctl", "daemon-reload"], { stdio: "inherit" });
+    console.log("  [privileged] systemctl enable");
+    shell("systemctl", ["enable", serviceName], { sudo: true });
+    // Task 800: skip stop+disable when a peer brand on this host still depends
+    // on the apt `neo4j.service` (port 7687). Disabling it would kill the peer's
+    // database — Task 797 reproducer on Neo's laptop. The kept-active path is
+    // mutually exclusive with the disable path: exactly one log line per install.
+    const peerOnSystemUnit = peerBrandUsingSystemUnit();
+    if (peerOnSystemUnit !== null) {
+        const keptActiveMsg = `  [neo4j] system unit kept active — peer brand ${peerOnSystemUnit} depends on port ${DEFAULT_NEO4J_PORT}`;
+        console.log(keptActiveMsg);
+        logFile(keptActiveMsg);
+    }
+    else {
+        console.log(`  [neo4j] disabling system unit (brand-dedicated active on port ${NEO4J_PORT})`);
+        logFile(`  [neo4j] disabling system unit (brand-dedicated active on port ${NEO4J_PORT})`);
+        shell("systemctl", ["stop", "neo4j"], { sudo: true });
+        shell("systemctl", ["disable", "neo4j"], { sudo: true });
+    }
+    console.log(`  [neo4j] reset-failed ${serviceName} before start`);
+    logFile(`  [neo4j] reset-failed ${serviceName} before start`);
+    shell("systemctl", ["reset-failed", serviceName], { sudo: true, bestEffort: true });
+    console.log("  [privileged] systemctl start");
+    shell("systemctl", ["start", serviceName], { sudo: true });
+    // Verify the dedicated unit bound its port. Password verification is
+    // ensureNeo4jPassword()'s job (called next in the install pipeline) — that
+    // function tests the stored password against this port and resets auth if
+    // the password no longer matches the running instance.
+    console.log(`  Waiting for dedicated Neo4j instance on port ${NEO4J_PORT}...`);
+    let listening = false;
+    const portMatch = new RegExp(`:${NEO4J_PORT}\\b`);
+    for (let i = 0; i < 15; i++) {
+        const portCheck = spawnSync("ss", ["-tln"], { stdio: "pipe", timeout: 5000 });
+        if (portMatch.test(portCheck.stdout?.toString() ?? "")) {
+            listening = true;
+            break;
+        }
+        spawnSync("sleep", ["2"]);
+    }
+    if (!listening) {
+        // Loud failure — no silent fallback to the system instance (Task 787).
+        const portCheck = spawnSync("ss", ["-tlnp"], { stdio: "pipe", timeout: 5000 });
+        const portLines = (portCheck.stdout?.toString() ?? "").split("\n").filter((l) => l.includes(String(NEO4J_PORT)));
+        const diagnostic = portLines.length > 0 ? portLines.join("; ") : "nothing listening on port";
+        const journal = spawnSync("journalctl", ["-u", serviceName, "--since", "5 min ago"], { stdio: "pipe", timeout: 5000 });
+        const journalTail = (journal.stdout?.toString() ?? "").split("\n").slice(-20).join("\n");
+        logFile(`  Neo4j dedicated: failed to bind port ${NEO4J_PORT} — ${diagnostic}`);
+        throw new Error(`Dedicated Neo4j instance ${serviceName} did not bind bolt://localhost:${NEO4J_PORT} within 30s.\n` +
+            `Port ${NEO4J_PORT}: ${diagnostic}\n` +
+            `journalctl -u ${serviceName} --since "5 min ago" | tail -20:\n${journalTail}`);
+    }
+    logFile(`  Neo4j dedicated: config=${confDir} data=${dataDir} service=${serviceName} bolt=:${NEO4J_PORT} http=:${httpPort}`);
+    console.log(`  Dedicated Neo4j instance ready on bolt://localhost:${NEO4J_PORT}`);
+}
+function ensureOllamaServing() {
+    const check = () => spawnSync("curl", ["-sf", "http://localhost:11434/api/tags"], {
+        stdio: "pipe", timeout: 5_000,
+    });
+    if (check().status === 0)
+        return;
+    // Log which ollama binary we're using and its version
+    const which = spawnSync("which", ["ollama"], { stdio: "pipe" });
+    const ollamaPath = which.stdout?.toString().trim() || "not found";
+    logFile(`  Ollama binary: ${ollamaPath}`);
+    const version = spawnSync("ollama", ["--version"], { stdio: "pipe", timeout: 5_000 });
+    logFile(`  Ollama version: ${version.stdout?.toString().trim() || version.stderr?.toString().trim() || `exit ${version.status}`}`);
+    // Check if systemd service exists
+    const svcCheck = spawnSync("systemctl", ["cat", "ollama"], { stdio: "pipe", timeout: 5_000 });
+    logFile(`  Ollama systemd service: ${svcCheck.status === 0 ? "exists" : "not found"}`);
+    // Check if port 11434 is already in use by something else
+    const portCheck = spawnSync("ss", ["-tlnp"], { stdio: "pipe", timeout: 5_000 });
+    const portLines = portCheck.stdout?.toString().split("\n").filter((l) => l.includes("11434")) || [];
+    if (portLines.length > 0)
+        logFile(`  Port 11434 in use: ${portLines.join("; ")}`);
+    console.log("  Starting Ollama server...");
+    logFile("  Ollama server not responding — starting ollama serve");
+    // Capture ollama serve output to a log file for diagnostics
+    const ollamaLog = join(LOG_DIR, "ollama-serve.log");
+    const logFd = openSync(ollamaLog, "a");
+    const child = spawn("ollama", ["serve"], {
+        stdio: ["ignore", logFd, logFd], detached: true,
+    });
+    child.unref();
+    closeSync(logFd);
+    logFile(`  Spawned ollama serve (PID ${child.pid}), log: ${ollamaLog}`);
+    for (let elapsed = 0; elapsed < 30; elapsed += 3) {
+        spawnSync("sleep", ["3"]);
+        // Check if process is still alive
+        const alive = child.pid && spawnSync("kill", ["-0", String(child.pid)], { stdio: "pipe" }).status === 0;
+        logFile(`  Poll ${elapsed + 3}s: pid ${child.pid} alive=${alive}`);
+        if (check().status === 0) {
+            logFile(`  Ollama server ready after ${elapsed + 3}s`);
+            return;
+        }
+        if (!alive) {
+            // Process died — read the log to find out why
+            const serveLog = readFileSync(ollamaLog, "utf-8").slice(-2000);
+            logFile(`  Ollama serve exited. Log tail:\n${serveLog}`);
+            console.error(`  Ollama serve exited unexpectedly. Log: ${ollamaLog}`);
+            throw new Error(`Ollama serve failed to start. Log: ${ollamaLog}\n${serveLog}`);
+        }
+    }
+    // Timed out — include diagnostics
+    const serveLog = readFileSync(ollamaLog, "utf-8").slice(-2000);
+    logFile(`  Ollama serve timed out after 30s. Log tail:\n${serveLog}`);
+    throw new Error(`Ollama server did not respond within 30s. Log: ${ollamaLog}\n${serveLog}`);
+}
+function installOllama(embedModel) {
+    if (!commandExists("ollama")) {
+        log("5", TOTAL, "Installing Ollama...");
+        spawnSync("bash", ["-c", "curl -fsSL https://ollama.ai/install.sh | sh"], { stdio: "inherit" });
+    }
+    else {
+        log("5", TOTAL, "Ollama already installed.");
+    }
+    ensureOllamaServing();
+    console.log(`  Pulling ${embedModel} embedding model...`);
+    logFile(`  Pulling embedding model: ${embedModel}`);
+    shellRetry("ollama", ["pull", embedModel], { timeout: 600_000 }, 3, 15);
+}
+// Task 557 — uv/uvx bootstrap. Required by the `graph` MCP server which
+// spawns `uvx mcp-neo4j-cypher@0.6.0 --transport stdio`. Idempotent: when
+// uvx is already on PATH (or under $HOME/.local/bin) we skip. Non-fatal on
+// failure — the installer continues; the graph server will loudly fail
+// at session start with a clear "uvx not found" error, which is retriable
+// via a second installer run with network access.
+function installUv() {
+    if (commandExists("uvx")) {
+        logFile("  uv: already installed");
+        console.log("  uv/uvx already installed.");
+        return;
+    }
+    console.log("  Installing uv (Python tool runner — required by Neo4j MCP server)...");
+    logFile("  uv: installing via astral.sh installer");
+    // astral.sh installer auto-confirms when stdin is not a TTY (our case under
+    // systemd-run). Historically we passed `-y`, which the script rejects with
+    // "unknown option -y" and causes uv to never install on upgrade.
+    const result = spawnSync("bash", ["-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"], { stdio: "inherit" });
+    if (result.status !== 0) {
+        console.error(`  WARNING: uv install exited ${result.status} — graph MCP server will fail at session start until this is retried`);
+        logFile(`  WARNING: uv install failed with status ${result.status}`);
+        return;
+    }
+    // The installer writes uvx to $HOME/.local/bin — add it to PATH for the
+    // remainder of this install so commandExists("uvx") works downstream.
+    const localBin = `${process.env.HOME}/.local/bin`;
+    if (process.env.PATH && !process.env.PATH.includes(localBin)) {
+        process.env.PATH = `${localBin}:${process.env.PATH}`;
+    }
+    if (commandExists("uvx")) {
+        logFile("  uv: install succeeded; uvx on PATH");
+    }
+    else {
+        console.error("  WARNING: uv installed but uvx not on PATH — check $HOME/.local/bin");
+    }
+}
+function installCloudflared() {
+    if (commandExists("cloudflared")) {
+        log("6", TOTAL, "Cloudflared already installed.");
+        return;
+    }
+    log("6", TOTAL, "Installing cloudflared...");
+    const platform = requireSupportedPlatform(process.platform);
+    if (platform === "darwin") {
+        // Homebrew's `cloudflared` formula tracks the Cloudflare release stream;
+        // tunnel-login flow stays unchanged (`feedback_no_api_token_route.md`).
+        // `cloudflared service install` is invoked by the launchd supervisor in
+        // Task 838 — out of scope here.
+        installAllBrewPackages(["cloudflared"], logFile);
+        return;
+    }
+    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]);
+}
+function installWhisperCpp() {
+    const WHISPER_DIR = "/opt/whisper.cpp";
+    const WHISPER_BINARY = join(WHISPER_DIR, "build/bin/whisper-cli");
+    const WHISPER_MODEL = join(WHISPER_DIR, "models", "ggml-base.bin");
+    if (existsSync(WHISPER_BINARY) && existsSync(WHISPER_MODEL)) {
+        log("7", TOTAL, "whisper.cpp already installed.");
+        return;
+    }
+    log("7", TOTAL, "Installing whisper.cpp (speech-to-text)...");
+    if (!isLinux()) {
+        console.log("  Skipping — install manually for your platform.");
+        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.");
+}
+/**
+ * Provision the shared HMAC secret used to sign remote-session cookies
+ * (Task 653). Both `maxy-edge` and `maxy-ui` read this file; without it
+ * they independently mint ephemeral secrets on first use and the
+ * cross-process session namespace silently diverges again.
+ *
+ * First install: create the file (0600, 32-byte hex).
+ * Upgrade: leave the existing file untouched — invalidating it here
+ * would log every operator out on every upgrade.
+ */
+function provisionRemoteSessionSecret() {
+    const persistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+    const credentialsDir = join(persistDir, "credentials");
+    const secretFile = join(credentialsDir, "remote-session-secret");
+    if (existsSync(secretFile)) {
+        console.log(`  [install] remote-session-secret exists — preserved`);
+        return;
+    }
+    mkdirSync(credentialsDir, { recursive: true, mode: 0o700 });
+    writeFileSync(secretFile, randomBytes(32).toString("hex"), { mode: 0o600 });
+    console.log(`  [install] remote-session-secret provisioned path=${secretFile}`);
+}
+// Task 904 — install-time admin-auth invariant. Walks every account.json
+// under accountsDir and compares its admins[] to the persistent users.json,
+// emitting one [install-invariant] line per divergence and one summary line.
+// Log-only (no install abort) so pre-Task-904 devices with already-divergent
+// state still upgrade; future sprint can promote to refuse-or-degrade once
+// the deployed fleet is audited clean. Mirror of
+// checkAdminAuthInvariant() in platform/lib/admins-write/src/index.ts.
+function runInstallInvariantCheck(usersFile, accountsDir) {
+    const TAG = "[install-invariant]";
+    const usersUserIds = new Set();
+    if (existsSync(usersFile)) {
+        try {
+            const raw = readFileSync(usersFile, "utf-8").trim();
+            if (raw) {
+                const users = JSON.parse(raw);
+                for (const u of users) {
+                    if (typeof u.userId === "string")
+                        usersUserIds.add(u.userId);
+                }
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.log(`  ${TAG} users.json unreadable usersFile=${usersFile} error=${msg}`);
+        }
+    }
+    const accountUserIds = new Set();
+    let divergences = 0;
+    if (existsSync(accountsDir)) {
+        let entries = [];
+        try {
+            entries = readdirSync(accountsDir);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.log(`  ${TAG} accounts-dir unreadable accountsDir=${accountsDir} error=${msg}`);
+            console.log(`  ${TAG} check complete divergences=0 (accounts-dir unreadable)`);
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith("."))
+                continue;
+            const accountDir = join(accountsDir, entry);
+            try {
+                if (!statSync(accountDir).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const accountJsonPath = join(accountDir, "account.json");
+            if (!existsSync(accountJsonPath))
+                continue;
+            let admins = [];
+            try {
+                const config = JSON.parse(readFileSync(accountJsonPath, "utf-8"));
+                admins = (config.admins ?? []);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.log(`  ${TAG} account.json unreadable source=${accountJsonPath} error=${msg}`);
+                continue;
+            }
+            for (const a of admins) {
+                if (typeof a.userId !== "string")
+                    continue;
+                accountUserIds.add(a.userId);
+                if (!usersUserIds.has(a.userId)) {
+                    const userIdShort = a.userId.slice(0, 8);
+                    console.log(`  ${TAG} direction=account-without-users userId=${userIdShort} source=${accountJsonPath}`);
+                    divergences += 1;
+                }
+            }
+        }
+    }
+    for (const uid of usersUserIds) {
+        if (!accountUserIds.has(uid)) {
+            const userIdShort = uid.slice(0, 8);
+            console.log(`  ${TAG} direction=users-without-account userId=${userIdShort} source=${usersFile}`);
+            divergences += 1;
+        }
+    }
+    console.log(`  ${TAG} check complete divergences=${divergences}`);
+}
+function deployPayload() {
+    log("8", TOTAL, `Deploying ${BRAND.productName}...`);
+    if (!existsSync(PAYLOAD_DIR)) {
+        throw new Error(`Payload not found at ${PAYLOAD_DIR}. Package may be corrupted.`);
+    }
+    // Persistent config lives at ~/{configDir}/ — survives rm -rf ~/{installDir}
+    const persistentDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+    const persistentPasswordFile = join(persistentDir, ".neo4j-password");
+    const persistentAccountsDir = join(persistentDir, "accounts");
+    // Migrate: if password is in old location, move to persistent
+    const oldPasswordFile = join(INSTALL_DIR, "platform/config/.neo4j-password");
+    if (existsSync(oldPasswordFile) && !existsSync(persistentPasswordFile)) {
+        mkdirSync(persistentDir, { recursive: true });
+        cpSync(oldPasswordFile, persistentPasswordFile);
+    }
+    const oldAccountsDir = join(INSTALL_DIR, "platform/config/accounts");
+    if (existsSync(oldAccountsDir) && !existsSync(persistentAccountsDir)) {
+        mkdirSync(persistentDir, { recursive: true });
+        cpSync(oldAccountsDir, persistentAccountsDir, { recursive: true });
+    }
+    // Task 904 — users.json lives at <persistentDir>/users.json. Pre-Task-904
+    // installs wrote to <INSTALL_DIR>/platform/config/users.json (the wipe zone)
+    // and relied on a one-shot copy-up at first install plus a copy-back after
+    // every wipe. The copy-back overwrote LIVE with the FROZEN-AT-FIRST-INSTALL
+    // backup, dropping every admin row added since first install. Writers (paths.ts,
+    // admin-add, set-pin, seed-neo4j.sh, migrate-import.sh) now target the
+    // persistent file directly — see comment in platform/ui/app/lib/paths.ts.
+    //
+    // Legacy pickup: if a pre-Task-904 install left users.json inside the wipe
+    // zone, copy it up once. Idempotent — guarded by !existsSync(persistentUsersFile).
+    // Safe to delete this block one release after Task 904 has been deployed
+    // everywhere; until then it absorbs upgrades from any pre-Task-904 version.
+    const persistentUsersFile = join(persistentDir, "users.json");
+    const oldUsersFile = join(INSTALL_DIR, "platform/config/users.json");
+    if (existsSync(oldUsersFile) && !existsSync(persistentUsersFile)) {
+        mkdirSync(persistentDir, { recursive: true });
+        cpSync(oldUsersFile, persistentUsersFile);
+        console.log("  Migrated pre-Task-904 users.json to persistent storage.");
+    }
+    // Task 923 — Claude Code OAuth credentials legacy pickup. Pre-Task-923
+    // installs shared `~/.claude/.credentials.json` across brands; the brand
+    // main service's `claude` SDK subprocess and admin server now read from
+    // `${persistDir}/.claude/.credentials.json` per the new
+    // Environment=CLAUDE_CONFIG_DIR= block in port-resolution.ts.
+    //
+    // Move-semantics: the FIRST brand to install grabs the legacy file. The
+    // operation is cpSync + unlinkSync (not renameSync) so it survives cross-
+    // volume `~/` mounts that would EXDEV-fail rename. Subsequent brand
+    // installs find no legacy file and require a fresh `claude /login`.
+    //
+    // Idempotency stamp at `${persistentDir}/.claude/.credentials-migrated`
+    // prevents re-pickup on re-installs of the same brand even if an operator
+    // later runs `claude /login` with no CLAUDE_CONFIG_DIR set, which would
+    // re-create the legacy path.
+    const persistentClaudeDir = join(persistentDir, ".claude");
+    const persistentCredsFile = join(persistentClaudeDir, ".credentials.json");
+    const legacyCredsFile = join(process.env.HOME ?? "/root", ".claude", ".credentials.json");
+    const credsMigratedStamp = join(persistentClaudeDir, ".credentials-migrated");
+    if (!existsSync(credsMigratedStamp)) {
+        mkdirSync(persistentClaudeDir, { recursive: true });
+        if (existsSync(legacyCredsFile) && !existsSync(persistentCredsFile)) {
+            cpSync(legacyCredsFile, persistentCredsFile);
+            try {
+                unlinkSync(legacyCredsFile);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.log(`  [install] claude-creds pickup: legacy unlink warn=${msg}`);
+            }
+            console.log(`  [install] claude-creds pickup: brand=${BRAND.hostname} source=${legacyCredsFile} target=${persistentCredsFile}`);
+        }
+        writeFileSync(credsMigratedStamp, new Date().toISOString() + "\n");
+    }
+    // Brand isolation: installer does not read ~/.maxy/, ~/.cloudflared/, or
+    // ~/.cloudflare/ on non-default brands. These are peer-brand or shared-singleton
+    // paths (Task 659). Pre-Task-659 installs that need to recover legacy state
+    // follow the manual recovery paragraph in .docs/deployment.md.
+    // Stop the running service before wiping directories (upgrade path).
+    // The server holds open files in platform/ — rmSync fails with ENOTEMPTY if it's running.
+    // Task 838 — darwin uses `launchctl bootout` instead of systemctl; bootout
+    // returns synchronously when the agent has exited.
+    if (requireSupportedPlatform(process.platform) === "darwin") {
+        spawnSync("launchctl", ["bootout", `${gui()}/${launchdLabel()}`], { stdio: "pipe", timeout: 15_000 });
+    }
+    else {
+        // systemctl stop returns when the main process exits, but ExecStopPost (e.g. VNC cleanup)
+        // may still hold file handles. Poll is-active to wait for full deactivation.
+        const svcName = BRAND.serviceName.replace(".service", "");
+        spawnSync("systemctl", ["--user", "stop", svcName], { stdio: "pipe" });
+        const MAX_STOP_WAIT = 5;
+        for (let i = 0; i < MAX_STOP_WAIT; i++) {
+            const result = spawnSync("systemctl", ["--user", "is-active", svcName], { stdio: "pipe" });
+            const status = result.stdout?.toString().trim();
+            if (status !== "active" && status !== "deactivating") {
+                console.log(`  Service stopped (${status || "not found"}).`);
+                break;
+            }
+            if (i === MAX_STOP_WAIT - 1) {
+                console.log(`  [WARN] Service still ${status} after ${MAX_STOP_WAIT}s — proceeding with directory wipe.`);
+                break;
+            }
+            spawnSync("sleep", ["1"]);
+        }
+    }
+    // Migrate user data to {installDir}/data/ — outside the platform/ wipe zone.
+    // Runs after service stop to avoid copying files while the agent is writing.
+    // Once data/ is populated, subsequent reinstalls skip this entirely.
+    const dataDir = join(INSTALL_DIR, "data");
+    const dataAccountsDir = join(dataDir, "accounts");
+    const dataUploadsDir = join(dataDir, "uploads");
+    const oldLiveAccounts = join(INSTALL_DIR, "platform/config/accounts");
+    if (!existsSync(dataAccountsDir)) {
+        if (existsSync(oldLiveAccounts)) {
+            mkdirSync(dataDir, { recursive: true });
+            cpSync(oldLiveAccounts, dataAccountsDir, { recursive: true });
+            console.log("  Migrated accounts to data/.");
+        }
+        else if (existsSync(persistentAccountsDir)) {
+            mkdirSync(dataDir, { recursive: true });
+            cpSync(persistentAccountsDir, dataAccountsDir, { recursive: true });
+            console.log("  Restored accounts from persistent backup to data/.");
+        }
+    }
+    const oldLiveUploads = join(INSTALL_DIR, "platform/data/attachments");
+    if (!existsSync(dataUploadsDir) && existsSync(oldLiveUploads)) {
+        mkdirSync(dataDir, { recursive: true });
+        cpSync(oldLiveUploads, dataUploadsDir, { recursive: true });
+        console.log("  Migrated uploads to data/.");
+    }
+    // Wipe deployment directories to prevent stale files.
+    // data/ is NOT wiped — it contains user data (accounts, uploads) that must survive.
+    for (const dir of ["platform", "server", "maxy", "premium-plugins", "docs", ".claude"]) {
+        const target = join(INSTALL_DIR, dir);
+        if (existsSync(target)) {
+            rmSync(target, { recursive: true, force: true });
+        }
+    }
+    mkdirSync(INSTALL_DIR, { recursive: true });
+    // Deploy payload
+    cpSync(PAYLOAD_DIR, INSTALL_DIR, {
+        recursive: true,
+        force: true,
+    });
+    // Link persistent config into install directory
+    const configDir = join(INSTALL_DIR, "platform/config");
+    mkdirSync(configDir, { recursive: true });
+    if (existsSync(persistentPasswordFile)) {
+        cpSync(persistentPasswordFile, join(configDir, ".neo4j-password"));
+        console.log("  Restored Neo4j password.");
+    }
+    // Task 904 — users.json is read directly from persistentDir by both
+    // platform/ui/app/lib/paths.ts (USERS_FILE = MAXY_DIR/users.json) and the
+    // admin MCP plugin (USERS_FILE = CONFIG_DIR/users.json). No copy into the
+    // wipe zone — the pre-Task-904 cpSync to platform/config/users.json was the
+    // copy that overwrote new admin rows on every install. The line below
+    // observes the row count + userId prefixes so a future regression is grep-
+    // detectable in the install log without any runtime change (singular
+    // "userId preserved" hid the multi-row failure mode).
+    if (existsSync(persistentUsersFile)) {
+        try {
+            const raw = readFileSync(persistentUsersFile, "utf-8").trim();
+            const rows = raw ? JSON.parse(raw) : [];
+            const ids = rows
+                .map(r => (typeof r.userId === "string" ? r.userId.slice(0, 8) : "?"))
+                .join(",");
+            console.log(`  [install] users.json preserved: rows=${rows.length} userIds=${ids}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.log(`  [install] users.json preserved: rows=? parse-failed error=${msg}`);
+        }
+    }
+    else {
+        console.log("  [install] users.json: no persistent file (fresh install — set-pin will create it)");
+    }
+    // Task 904 item 3 — install-time admin-auth invariant check. Walks every
+    // data/accounts/*/account.json admins[] and compares to the persistent
+    // users.json. Log-only (does NOT refuse install) so pre-Task-904 devices
+    // with already-divergent state still upgrade; the [install-invariant]
+    // line surfaces the bug to the operator without bricking the device.
+    // Inline rather than imported from platform/lib/admins-write because the
+    // installer is its own npm package and doesn't bundle the platform lib.
+    // Mirrors checkAdminAuthInvariant() in platform/lib/admins-write/src/index.ts;
+    // future divergence between the two should be caught by the test suite.
+    runInstallInvariantCheck(persistentUsersFile, join(INSTALL_DIR, "data", "accounts"));
+    // Write version marker so the running platform knows which create-maxy produced this deployment
+    writeFileSync(join(configDir, `.${BRAND.hostname}-version`), PKG_VERSION, "utf-8");
+    console.log(`  Deployed to ${INSTALL_DIR}`);
+}
+function buildPlatform() {
+    log("9", TOTAL, "Installing dependencies and building...");
+    console.log(`  Installing platform dependencies (${join(INSTALL_DIR, "platform")})...`);
+    shellRetry("npm", ["install", ...NPM_NET_FLAGS], { cwd: join(INSTALL_DIR, "platform") }, 3, 15);
+    // MCP server dist/ files are pre-compiled in the payload — no build step needed.
+    // Server external dependencies (neo4j-driver, @anthropic-ai/sdk) are listed in
+    // server/package.json but NOT shipped as pre-built node_modules — npm pack silently
+    // strips files from nested node_modules (e.g. rxjs/package.json), breaking require().
+    // Install fresh on device to guarantee a complete dependency tree.
+    //
+    // On upgrade, wipe `node_modules` first so npm extracts a clean tree. Without
+    // this, an interrupted previous install (network blip, operator cancellation,
+    // power loss) can leave nested package.json files half-truncated — the most
+    // common manifestation is `Error: Invalid package config .../rxjs/package.json`
+    // at server startup, which loops the brand service indefinitely. The wipe
+    // adds ~30 s to upgrades but eliminates a class of unrecoverable customer
+    // states; reliability wins over speed for a one-shot install path.
+    const serverNodeModules = join(INSTALL_DIR, "server", "node_modules");
+    if (existsSync(serverNodeModules)) {
+        console.log("  Wiping previous server/node_modules for a clean reinstall...");
+        rmSync(serverNodeModules, { recursive: true, force: true });
+    }
+    console.log(`  Installing server dependencies (${join(INSTALL_DIR, "server")})...`);
+    shellRetry("npm", ["install", "--omit=dev", ...NPM_NET_FLAGS], { cwd: join(INSTALL_DIR, "server") }, 3, 15);
+    // Task 001 (maxy-code) — claude-session-manager has its own package.json
+    // declaring hono + @hono/node-server + node-pty. node-pty is a native
+    // binding; it MUST be installed on the Pi, not shipped pre-built (different
+    // architecture between the build host and the Pi). Wipe + reinstall on
+    // upgrade so a half-extracted previous install does not loop the unit.
+    const csmDir = join(INSTALL_DIR, "platform", "services", "claude-session-manager");
+    if (existsSync(csmDir)) {
+        const csmNodeModules = join(csmDir, "node_modules");
+        if (existsSync(csmNodeModules)) {
+            console.log("  Wiping previous claude-session-manager/node_modules for a clean reinstall...");
+            rmSync(csmNodeModules, { recursive: true, force: true });
+        }
+        console.log(`  Installing claude-session-manager dependencies (${csmDir})...`);
+        shellRetry("npm", ["install", "--omit=dev", ...NPM_NET_FLAGS], { cwd: csmDir }, 3, 15);
+    }
+}
+function setupVncViewer() {
+    if (!isLinux())
+        return;
+    const novncSrc = "/usr/share/novnc";
+    const novncDest = join(INSTALL_DIR, "server/public/novnc");
+    if (!existsSync(join(novncSrc, "core"))) {
+        console.log("  noVNC not found — skipping VNC viewer setup.");
+        return;
+    }
+    console.log("  Installing VNC viewer...");
+    // Copy core/ and vendor/ (pako compression library) — both required by rfb.js
+    cpSync(join(novncSrc, "core"), join(novncDest, "core"), { recursive: true, force: true });
+    const vendorSrc = join(novncSrc, "vendor");
+    if (existsSync(vendorSrc)) {
+        cpSync(vendorSrc, join(novncDest, "vendor"), { recursive: true, force: true });
+    }
+    // Custom viewer: no toolbar, scales to fit, auto-connects with retry.
+    //
+    // Transport: same-origin WebSocket proxied through the Maxy server's
+    // /websockify upgrade handler. The URL is built from location.protocol
+    // and location.host so that:
+    //   - HTTP origin  → ws://<host>:<port>/websockify   (LAN)
+    //   - HTTPS origin → wss://<host>:<port>/websockify  (Cloudflare tunnel)
+    // This eliminates the mixed-content block that previously killed the
+    // viewer when accessed via https://admin.maxy.bot.
+    //
+    // The viewer does NOT read a host/port from query string — those
+    // parameters are ignored if present (kept for backward compatibility
+    // with any cached callers) and the connection is always same-origin.
+    //
+    // A per-session correlation ID is generated client-side and included
+    // in the WebSocket URL (?corrId=X) and in the POST to
+    // /api/vnc/client-event so the server-side log can correlate the
+    // noVNC disconnect reason to the specific WS upgrade entry.
+    const html = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
+  <title>Connect Claude</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    html, body { width: 100%; height: 100%; background: #111; overflow: hidden; }
+    #screen { position: relative; width: 100%; height: 100%; }
+    #status {
+      position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);
+      color: #888; font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+      font-size: 14px; text-align: center; z-index: 10;
+      transition: opacity 0.3s;
+    }
+    #status.hidden { opacity: 0; pointer-events: none; }
+    .status-spinner {
+      display: inline-block; width: 20px; height: 20px;
+      border: 2px solid #444; border-top-color: #888; border-radius: 50%;
+      animation: spin 0.8s linear infinite; margin-bottom: 8px;
+    }
+    @keyframes spin { to { transform: rotate(360deg); } }
+    .status-reason { font-size: 12px; color: #666; margin-top: 6px; }
+  </style>
+</head>
+<body>
+  <div id="screen"></div>
+  <div id="status">
+    <div class="status-spinner"></div>
+    <div>Connecting to browser…</div>
+    <div class="status-reason"></div>
+  </div>
+  <script type="module">
+    import RFB from '/novnc/core/rfb.js';
+
+    // Build a same-origin WebSocket URL. Protocol auto-matches the
+    // parent page so https pages use wss and http pages use ws.
+    const wsScheme = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    // Generate a client-side correlation ID. This ID is used only for
+    // client-side log correlation (the server assigns its own corrId
+    // on the upgrade handler so an attacker cannot forge server
+    // internal ids). Base-36 random concatenation yields up to 16
+    // chars — collision-free in practice for the 1-session-at-a-time
+    // VNC use case.
+    const corrId = (Math.random().toString(36).slice(2, 10) + Math.random().toString(36).slice(2, 10))
+      .replace(/[^a-z0-9]/gi, '') || 'c' + Date.now().toString(36);
+    const wsUrl = wsScheme + '//' + location.host + '/websockify?corrId=' + encodeURIComponent(corrId);
+
+    const screen = document.getElementById('screen');
+    const status = document.getElementById('status');
+    let retryCount = 0;
+    const MAX_RETRIES = 30;
+
+    // Best-effort POST of a disconnect/error reason to the server so
+    // the noVNC-observed failure mode ends up in vnc-boot.log alongside
+    // the server-side proxy events. Network failures are swallowed —
+    // this is a telemetry side channel, not a critical path.
+    function reportClientEvent(phase, reason) {
+      try {
+        fetch('/api/vnc/client-event', {
+          method: 'POST',
+          credentials: 'same-origin',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ corrId: corrId, phase: phase, reason: reason || '' }),
+          keepalive: true,
+        }).catch(function() { /* swallow */ });
+      } catch (e) { /* swallow */ }
+    }
+
+    // Layer-6 beacon (Task 958): emit event=rfb-connected and
+    // event=rfb-error to the operator-grep lifecycle endpoint so
+    // server.log shows the noVNC outcome alongside [setup-tunnel] /
+    // [cloudflare-setup] / [device-url:click] / [http] / [websockify].
+    // Same-origin POST works whether the iframe is parented by the
+    // React BrowserViewer or by vnc-popout.html.
+    function reportBrowserViewerEvent(event, fields) {
+      try {
+        var body = JSON.stringify(Object.assign(
+          { event: event, surface: 'iframe' },
+          fields || {},
+        ));
+        fetch('/api/admin/browser-iframe/event', {
+          method: 'POST',
+          credentials: 'same-origin',
+          headers: { 'Content-Type': 'application/json' },
+          body: body,
+          keepalive: true,
+        }).catch(function() { /* swallow */ });
+      } catch (e) { /* swallow */ }
+    }
+    var connectStartedAt = 0;
+
+    function connect() {
+      status.classList.remove('hidden');
+      status.querySelector('.status-spinner').style.display = '';
+      status.querySelector('div:nth-child(2)').textContent =
+        retryCount > 0 ? 'Reconnecting… (' + retryCount + ')' : 'Connecting to browser…';
+      status.querySelector('.status-reason').textContent = '';
+      connectStartedAt = Date.now();
+
+      const rfb = new RFB(screen, wsUrl);
+      rfb.scaleViewport = true;
+      rfb.clipViewport = true;
+      rfb.resizeSession = false;
+      window.rfb = rfb;
+
+      rfb.addEventListener('connect', () => {
+        status.classList.add('hidden');
+        retryCount = 0;
+        reportBrowserViewerEvent('rfb-connected', {
+          durationMs: Date.now() - connectStartedAt,
+        });
+      });
+
+      rfb.addEventListener('disconnect', (e) => {
+        status.classList.remove('hidden');
+        const detail = e.detail || {};
+        const reason = detail.reason || (detail.clean === false ? 'Connection refused' : '');
+        reportClientEvent('disconnect', reason || (detail.clean === false ? 'unclean-close' : 'normal'));
+        reportBrowserViewerEvent('rfb-error', {
+          durationMs: Date.now() - connectStartedAt,
+          errorCode: detail.clean === false ? 'unclean-close' : 'normal',
+          message: reason || '',
+        });
+        const reasonEl = status.querySelector('.status-reason');
+        if (retryCount < MAX_RETRIES) {
+          retryCount++;
+          const delay = Math.min(1000 * retryCount, 5000);
+          status.querySelector('div:nth-child(2)').textContent = 'Reconnecting in ' + Math.ceil(delay/1000) + 's…';
+          reasonEl.textContent = reason;
+          setTimeout(connect, delay);
+        } else {
+          status.querySelector('.status-spinner').style.display = 'none';
+          status.querySelector('div:nth-child(2)').textContent = 'Connection lost. Reload the page to retry.';
+          reasonEl.textContent = reason;
+        }
+      });
+
+      // --- Clipboard bridge (local ↔ remote) ---
+
+      // Paste bridge: intercept Cmd/Ctrl+V in the capturing phase before
+      // noVNC's keydown handler can call preventDefault(). noVNC v1.3.0
+      // binds its handler with .bind(this) in the Keyboard constructor and
+      // registers the bound reference via addEventListener — so monkey-
+      // patching the unbound method on the instance is a no-op. A capturing-
+      // phase listener on document fires before noVNC's target-phase handler
+      // regardless of registration timing or internal structure.
+      document.addEventListener('keydown', (e) => {
+        if ((e.ctrlKey || e.metaKey) && (e.key === 'v' || e.key === 'V')) {
+          e.stopImmediatePropagation();
+          reportClientEvent('paste-bridge', 'keydown-intercepted');
+        }
+      }, true);
+
+      // Catch the paste event, sync text to VNC server clipboard, then
+      // send Ctrl+V keystrokes so the remote app pastes the synced content.
+      document.addEventListener('paste', (e) => {
+        e.preventDefault();
+        const text = (e.clipboardData || window.clipboardData)?.getData('text');
+        if (!text || !window.rfb) {
+          reportClientEvent('paste-bridge', 'empty-clipboard');
+          return;
+        }
+        reportClientEvent('paste-bridge', 'paste-event text-length=' + text.length);
+        window.rfb.clipboardPasteFrom(text);
+        reportClientEvent('paste-bridge', 'clipboard-synced');
+        setTimeout(() => {
+          window.rfb.sendKey(0xFFE3, 'ControlLeft', true);
+          window.rfb.sendKey(0x0076, 'v', true);
+          window.rfb.sendKey(0x0076, 'v', false);
+          window.rfb.sendKey(0xFFE3, 'ControlLeft', false);
+        }, 50);
+      });
+
+      // Copy bridge: when the remote clipboard changes, notify the parent frame.
+      rfb.addEventListener('clipboard', (e) => {
+        window.parent.postMessage({ type: 'vnc-clipboard', text: e.detail.text }, '*');
+      });
+    }
+
+    connect();
+  </script>
+</body>
+</html>`;
+    writeFileSync(join(INSTALL_DIR, "server/public/vnc-viewer.html"), html);
+    console.log("  VNC viewer ready at /vnc-viewer.html");
+}
+function setupAccount() {
+    log("10", TOTAL, "Setting up...");
+    // Task 787 — seed-neo4j.sh hard-exits without NEO4J_URI. The installer
+    // owns the brand-correct URI and password, so we derive them once.
+    // Missing password file is a hard error: ensureNeo4jPassword() ran
+    // upstream and would have thrown already if it couldn't reach the
+    // brand's Neo4j.
+    const passwordFile = join(INSTALL_DIR, "platform/config/.neo4j-password");
+    if (!existsSync(passwordFile)) {
+        throw new Error(`Neo4j password file missing at ${passwordFile} — required by setup step.`);
+    }
+    const password = readFileSync(passwordFile, "utf-8").trim();
+    const neo4jUri = `bolt://localhost:${NEO4J_PORT}`;
+    const neo4jEnv = { ...process.env, NEO4J_URI: neo4jUri, NEO4J_PASSWORD: password };
+    const seedScript = join(INSTALL_DIR, "platform/scripts/seed-neo4j.sh");
+    if (existsSync(seedScript)) {
+        console.log(`  [neo4j] passing NEO4J_URI=${neo4jUri} to seed`);
+        logFile(`  [neo4j] passing NEO4J_URI=${neo4jUri} to seed`);
+        shell("bash", [seedScript], { cwd: INSTALL_DIR, env: neo4jEnv });
+    }
+}
+// ---------------------------------------------------------------------------
+// Tunnel script shortcuts
+//
+// The cloudflare plugin's SKILL.md, PLUGIN.md, and reference docs encode the
+// invocation `~/setup-tunnel.sh` (and `~/reset-tunnel.sh`). The filesystem
+// reality is <INSTALL_DIR>/platform/plugins/cloudflare/scripts/*.sh. Without
+// the symlink the agent's first SKILL-compliant invocation fails with exit
+// 127 — the discipline-violation loop Task 555 exists to close.
+//
+// Collision discipline (Task 659 — last-writer-wins across brands):
+//   - absent path                   → create
+//   - regular file                  → exit 1 (operator-owned file, do not clobber)
+//   - symlink → same target         → no-op
+//   - symlink → any other target    → overwrite (unlink + symlink)
+//                                     covers stale-same-brand, dangling,
+//                                     unreadable, and peer-brand cases.
+//                                     setup-tunnel.sh takes <brand> as argv
+//                                     so the script still operates on the
+//                                     correct brand regardless of who owns
+//                                     the shortcut symlink.
+// ---------------------------------------------------------------------------
+function createTunnelSymlink(linkPath, target) {
+    const targetAbs = resolve(target);
+    let lstat = null;
+    try {
+        lstat = lstatSync(linkPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT") {
+            console.error(`Setup failed: ${linkPath} lstat failed: ${err.message}`);
+            console.error(`[create-maxy:error] ${linkPath} lstat failed: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    if (lstat === null) {
+        symlinkSync(targetAbs, linkPath);
+        console.log(`  [create-maxy] symlink ${linkPath} → ${targetAbs}`);
+        logFile(`  symlink created: ${linkPath} → ${targetAbs}`);
+        return;
+    }
+    if (!lstat.isSymbolicLink()) {
+        console.error(`Setup failed: ${linkPath} collision (regular file)`);
+        console.error(`[create-maxy:collision] ${linkPath} already exists target=<regular-file>`);
+        console.error(`  Remove the file and re-run: npx -y @rubytech/create-maxy`);
+        process.exit(1);
+    }
+    // Brand isolation (Task 659): a symlink at this path is either stale-same-brand,
+    // dangling, unreadable, or pointing at another brand. All four cases are resolved
+    // by last-writer-wins overwrite — setup-tunnel.sh takes <brand> as argv, so
+    // whichever brand's installer ran last owns the shortcut.
+    const resolvedTarget = (() => {
+        try {
+            return resolve(dirname(linkPath), readlinkSync(linkPath));
+        }
+        catch {
+            return "<unreadable>";
+        }
+    })();
+    if (resolvedTarget === targetAbs) {
+        console.log(`  [create-maxy] symlink ${linkPath} already points to ${targetAbs}`);
+        logFile(`  symlink unchanged: ${linkPath} → ${targetAbs}`);
+        return;
+    }
+    unlinkSync(linkPath);
+    symlinkSync(targetAbs, linkPath);
+    console.log(`  [create-maxy] symlink replaced: ${linkPath} → ${targetAbs}`);
+    logFile(`  symlink replaced: ${linkPath} was ${resolvedTarget}, now ${targetAbs}`);
+}
+function installTunnelScripts() {
+    const setupSrc = join(INSTALL_DIR, "platform/plugins/cloudflare/scripts/setup-tunnel.sh");
+    const resetSrc = join(INSTALL_DIR, "platform/plugins/cloudflare/scripts/reset-tunnel.sh");
+    const listSrc = join(INSTALL_DIR, "platform/plugins/cloudflare/scripts/list-cf-domains.sh");
+    const setupLink = resolve(process.env.HOME ?? "/root", "setup-tunnel.sh");
+    const resetLink = resolve(process.env.HOME ?? "/root", "reset-tunnel.sh");
+    const listLink = resolve(process.env.HOME ?? "/root", "list-cf-domains.sh");
+    for (const src of [setupSrc, resetSrc, listSrc]) {
+        try {
+            chmodSync(src, 0o755);
+        }
+        catch (err) {
+            console.error(`Setup failed: tunnel script missing or chmod failed: ${src}`);
+            console.error(`[create-maxy:error] tunnel script missing or chmod failed: ${src}`);
+            console.error(`  ${err.message}`);
+            process.exit(1);
+        }
+    }
+    createTunnelSymlink(setupLink, setupSrc);
+    createTunnelSymlink(resetLink, resetSrc);
+    createTunnelSymlink(listLink, listSrc);
+}
+// ---------------------------------------------------------------------------
+// Account discovery (shared between installService + installCrons)
+//
+// Task 955 — `installService` stamps `Environment=ACCOUNT_ID=` into the brand
+// systemd unit so the writeNodeWithEdges gate has a non-undefined identity to
+// compare against; `installCrons` needs the same value to scope cron stdout
+// to the per-account log dir + stamp ACCOUNT_ID into the cron entry env.
+// Both pull from `INSTALL_DIR/data/accounts/<uuid>/account.json` written by
+// seed-neo4j.sh during setupAccount(). One reader, one shape, one source of
+// truth — without sharing, the two callers would drift on classification of
+// `corrupt account.json` (one might count it, the other might not) and the
+// gate would reject writes the cron's "scoped" log was already happily
+// publishing under that uuid.
+// ---------------------------------------------------------------------------
+function resolveInstallAccountId() {
+    const accountsDir = join(INSTALL_DIR, "data/accounts");
+    if (!existsSync(accountsDir))
+        return "";
+    try {
+        for (const d of readdirSync(accountsDir)) {
+            if (existsSync(join(accountsDir, d, "account.json")))
+                return d;
+        }
+    }
+    catch { /* directory unreadable */ }
+    return "";
+}
+// ---------------------------------------------------------------------------
+// Cron Registration
+//
+// Registers platform cron jobs (heartbeat, email-fetch, email-auto-respond).
+// Uses BEGIN/END markers for idempotent replacement on re-install.
+// Crons persist across reboots — registered once at install time.
+// Email crons run unconditionally; scripts exit early if unconfigured.
+// ---------------------------------------------------------------------------
+const CRON_BLOCK_BEGIN = `# BEGIN ${BRAND.productName.toUpperCase()} CRONS`;
+const CRON_BLOCK_END = `# END ${BRAND.productName.toUpperCase()} CRONS`;
+function installCrons() {
+    if (!isLinux())
+        return;
+    const nodeBin = spawnSync("which", ["node"], { encoding: "utf-8" }).stdout.trim() || "/usr/bin/node";
+    const platformRoot = join(INSTALL_DIR, "platform");
+    // Account discovery shared with installService — see resolveInstallAccountId.
+    const accountId = resolveInstallAccountId();
+    const accountsDir = join(INSTALL_DIR, "data/accounts");
+    if (!accountId) {
+        console.error("  Cron jobs: skipped — no account found. Crons will register on the next install after account creation.");
+        logFile("  cron registration skipped: no account directory with account.json found");
+        return;
+    }
+    const accountLogDir = join(accountsDir, accountId, "logs");
+    // NEO4J_URI is explicit per brand so a secondary-brand install (dedicated
+    // Neo4j on a non-default port) doesn't silently fall back to
+    // bolt://localhost:7687 in cron — cron inherits none of the user's shell
+    // env or .env file. Without this, the scheduler writes and reads from the
+    // shared default instance, producing cross-install event leaks (Task 571).
+    const accountEnv = `ACCOUNT_ID=${accountId} NEO4J_URI=bolt://localhost:${NEO4J_PORT} `;
+    const cronEntries = [
+        `* * * * * mkdir -p ${accountLogDir} && PLATFORM_ROOT=${platformRoot} ${accountEnv}${nodeBin} ${platformRoot}/plugins/scheduling/mcp/dist/scripts/check-due-events.js >> ${accountLogDir}/check-due-events.log 2>&1 # heartbeat`,
+        `* * * * * mkdir -p ${accountLogDir} && PLATFORM_ROOT=${platformRoot} ${accountEnv}${nodeBin} ${platformRoot}/plugins/email/mcp/dist/scripts/email-fetch.js >> ${accountLogDir}/email-fetch.log 2>&1 # email-fetch`,
+        `* * * * * mkdir -p ${accountLogDir} && PLATFORM_ROOT=${platformRoot} ${accountEnv}${nodeBin} ${platformRoot}/plugins/email/mcp/dist/scripts/email-auto-respond.js >> ${accountLogDir}/email-auto-respond.log 2>&1 # email-auto-respond`,
+    ];
+    // Read existing crontab (empty string if none)
+    const existing = spawnSync("crontab", ["-l"], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    const currentCrontab = existing.status === 0 ? existing.stdout : "";
+    // Strip any existing Maxy cron block
+    const blockPattern = new RegExp(`${CRON_BLOCK_BEGIN}[\\s\\S]*?${CRON_BLOCK_END}\\n?`, "g");
+    const cleaned = currentCrontab.replace(blockPattern, "").trimEnd();
+    // Build new crontab with Maxy block
+    const newBlock = [
+        CRON_BLOCK_BEGIN,
+        ...cronEntries,
+        CRON_BLOCK_END,
+    ].join("\n");
+    const newCrontab = cleaned ? `${cleaned}\n${newBlock}\n` : `${newBlock}\n`;
+    // Write the new crontab
+    const write = spawnSync("crontab", ["-"], {
+        input: newCrontab,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    if (write.status === 0) {
+        console.log("  Cron jobs: registered (heartbeat, email-fetch, email-auto-respond)");
+    }
+    else {
+        console.error(`  Cron jobs: failed to register — ${(write.stderr || "").trim()}`);
+        logFile(`  crontab write failed: ${write.stderr}`);
+    }
+}
+// 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.
+// Task 838 — reverse-DNS LaunchAgent label. Becomes both the plist's
+// <key>Label</key> value and the file basename
+// (`~/Library/LaunchAgents/com.rubytech.<hostname>.plist`). Per-brand so
+// installing brand B never displaces brand A's agent (mirrors the per-brand
+// systemd unit invariant from Task 662).
+function launchdLabel() {
+    return `com.rubytech.${BRAND.hostname}`;
+}
+function launchAgentsDir() {
+    return resolve(process.env.HOME ?? "/", "Library/LaunchAgents");
+}
+function plistPath() {
+    return join(launchAgentsDir(), `${launchdLabel()}.plist`);
+}
+function gui() {
+    // launchd's gui domain is keyed on the user's UID. process.getuid is only
+    // defined on POSIX (always present on darwin); typed conservatively.
+    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+    return `gui/${uid}`;
+}
+// Task 838 — darwin LaunchAgent supervisor. Mirrors the systemd-user body
+// below at the success-criteria level: process registered with the user's
+// session manager, KeepAlive respawns on crash, RunAtLoad starts the agent
+// on every login. Out-of-scope today (Task 839): brew-resolved node path,
+// dedicated Neo4j on a non-default port. Falls back to /usr/local/bin/node
+// (homebrew Intel + manual Apple-silicon installs) — Task 839 will replace
+// this with the resolver.
+function installServiceDarwin() {
+    const persistDir = resolve(process.env.HOME ?? "/", BRAND.configDir);
+    const logsDir = join(persistDir, "logs");
+    mkdirSync(logsDir, { recursive: true });
+    // Write install-time config to .env (the server reads it directly on
+    // darwin; launchd does not have systemd's EnvironmentFile primitive).
+    const envPath = join(persistDir, ".env");
+    try {
+        let envContent = "";
+        try {
+            envContent = readFileSync(envPath, "utf-8");
+        }
+        catch { /* first install */ }
+        for (const [key, value] of [
+            ["DISPLAY_MODE", DISPLAY_MODE],
+            ["EMBED_MODEL", EMBED_MODEL],
+            ["EMBED_DIMENSIONS", String(EMBED_DIMS)],
+            ["NEO4J_URI", `bolt://localhost:${NEO4J_PORT}`],
+            ["PORT", String(PORT)],
+            ["MAXY_PLATFORM_ROOT", `${INSTALL_DIR}/platform`],
+        ]) {
+            const re = new RegExp(`^${key}=.*$`, "m");
+            if (re.test(envContent)) {
+                envContent = envContent.replace(re, `${key}=${value}`);
+            }
+            else {
+                envContent = envContent.trimEnd() + (envContent.length > 0 ? "\n" : "") + `${key}=${value}\n`;
+            }
+        }
+        writeFileSync(envPath, envContent);
+        logFile(`  .env: DISPLAY_MODE=${DISPLAY_MODE}, EMBED_MODEL=${EMBED_MODEL}, EMBED_DIMENSIONS=${EMBED_DIMS}, NEO4J_URI=bolt://localhost:${NEO4J_PORT}, PORT=${PORT}`);
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to write .env to ${envPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Render the plist. The wrapper shell script reads .env before exec'ing
+    // node so the runtime config (PORT, MAXY_PLATFORM_ROOT, NEO4J_URI) lands
+    // in the child env. Without this, ProgramArguments executes node directly
+    // and the .env values are unread — server binds the wrong port.
+    const wrapperPath = join(persistDir, "launchd-wrapper.sh");
+    // Resolve node binary at install time so the wrapper picks the right
+    // path on both Intel (/usr/local/bin/node) and Apple Silicon
+    // (/opt/homebrew/bin/node) — Homebrew's prefix differs by arch.
+    const nodeProbe = spawnSync("command", ["-v", "node"], { encoding: "utf-8", shell: true });
+    const nodeBin = (nodeProbe.stdout ?? "").trim() || "/usr/local/bin/node";
+    const wrapperBody = [
+        "#!/bin/bash",
+        "# Task 838 — generated by create-maxy installService(). Reads .env then",
+        "# execs node so launchd's child inherits PORT, NEO4J_URI, etc. Replaces",
+        "# the systemd EnvironmentFile= directive that has no launchd analogue.",
+        `set -a; [ -f "${envPath}" ] && . "${envPath}"; set +a`,
+        `cd "${INSTALL_DIR}/server"`,
+        `exec ${nodeBin} --require ./server-init.cjs server.js`,
+        "",
+    ].join("\n");
+    writeFileSync(wrapperPath, wrapperBody);
+    chmodSync(wrapperPath, 0o755);
+    const label = launchdLabel();
+    const plist = renderPlist({
+        label,
+        programArguments: ["/bin/bash", wrapperPath],
+        stdoutPath: join(logsDir, "server.log"),
+        stderrPath: join(logsDir, "server.log"),
+        keepAlive: true,
+        runAtLoad: true,
+        workingDirectory: `${INSTALL_DIR}/server`,
+    });
+    mkdirSync(launchAgentsDir(), { recursive: true });
+    const path = plistPath();
+    writeFileSync(path, plist);
+    logFile(`  ${path} written (${plist.length} bytes)`);
+    // Idempotent re-install: bootout the previous instance (if any) first so
+    // the second `bootstrap` does not exit 5 ("already loaded"). Best-effort —
+    // a missing service is the expected case on fresh installs.
+    spawnSync("launchctl", ["bootout", `${gui()}/${label}`], { stdio: "pipe" });
+    const bootstrap = spawnSync("launchctl", ["bootstrap", gui(), path], {
+        stdio: "pipe",
+        encoding: "utf-8",
+        timeout: 15_000,
+    });
+    if (bootstrap.status === 0) {
+        console.log(`  [launchd] bootstrap ${gui()}/${label} ok`);
+        logFile(`  [launchd] bootstrap ${gui()}/${label} ok`);
+    }
+    else {
+        const stderr = (bootstrap.stderr ?? "").trim();
+        console.error(`  [launchd] bootstrap returned ${bootstrap.status}: ${stderr}`);
+        logFile(`  [launchd] bootstrap returned ${bootstrap.status}: ${stderr}`);
+        throw new Error(`launchctl bootstrap ${gui()} ${path} failed (exit ${bootstrap.status}): ${stderr}`);
+    }
+    // Wait for the server to come up.
+    console.log("  Waiting for web server...");
+    let webServerUp = false;
+    for (let i = 0; i < 20; i++) {
+        try {
+            execFileSync("curl", ["-sf", `http://localhost:${PORT}`, "-o", "/dev/null"], { timeout: 3000 });
+            webServerUp = true;
+            break;
+        }
+        catch {
+            spawnSync("sleep", ["2"]);
+        }
+    }
+    if (!webServerUp) {
+        console.log(`  Server may still be starting. Check http://localhost:${PORT} in a moment.`);
+    }
+}
+function installService() {
+    log("11", TOTAL, `Starting ${BRAND.productName}...`);
+    // Task 838 — branch on the Task 836 ternary instead of the legacy
+    // `isLinux()` boolean. Linux falls through to the systemd-user body
+    // below; darwin renders + bootstraps a LaunchAgent and returns;
+    // unsupported throws the literal refusal at requireSupportedPlatform.
+    const platform = requireSupportedPlatform(process.platform);
+    if (platform === "darwin") {
+        installServiceDarwin();
+        return;
+    }
+    // Persist UDP buffer sizes for cloudflared QUIC stability (applied on every boot via sysctl.d)
+    const sysctlTmpPath = `/tmp/99-${BRAND.hostname}-quic.conf`;
+    const sysctlDestPath = `/etc/sysctl.d/99-${BRAND.hostname}-quic.conf`;
+    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 });
+    }
+    catch { /* non-critical — values applied on next reboot */ }
+    const serviceDir = resolve(process.env.HOME ?? "/root", ".config/systemd/user");
+    mkdirSync(serviceDir, { recursive: true });
+    // Create systemd user service
+    const persistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+    mkdirSync(join(persistDir, "logs"), { recursive: true });
+    // Write install-time config to .env (systemd reads via EnvironmentFile).
+    // Preserves existing .env content (e.g. PORT overrides) — only
+    // replaces or appends each managed line.
+    const envPath = join(persistDir, ".env");
+    try {
+        let envContent = "";
+        try {
+            envContent = readFileSync(envPath, "utf-8");
+        }
+        catch { /* first install */ }
+        // DISPLAY_MODE
+        if (/^DISPLAY_MODE=.*/m.test(envContent)) {
+            envContent = envContent.replace(/^DISPLAY_MODE=.*/m, `DISPLAY_MODE=${DISPLAY_MODE}`);
+        }
+        else {
+            envContent = envContent.trimEnd() + (envContent.length > 0 ? "\n" : "") + `DISPLAY_MODE=${DISPLAY_MODE}\n`;
+        }
+        // EMBED_MODEL
+        if (/^EMBED_MODEL=.*/m.test(envContent)) {
+            envContent = envContent.replace(/^EMBED_MODEL=.*/m, `EMBED_MODEL=${EMBED_MODEL}`);
+        }
+        else {
+            envContent = envContent.trimEnd() + (envContent.length > 0 ? "\n" : "") + `EMBED_MODEL=${EMBED_MODEL}\n`;
+        }
+        // EMBED_DIMENSIONS
+        if (/^EMBED_DIMENSIONS=.*/m.test(envContent)) {
+            envContent = envContent.replace(/^EMBED_DIMENSIONS=.*/m, `EMBED_DIMENSIONS=${EMBED_DIMS}`);
+        }
+        else {
+            envContent = envContent.trimEnd() + (envContent.length > 0 ? "\n" : "") + `EMBED_DIMENSIONS=${EMBED_DIMS}\n`;
+        }
+        // NEO4J_URI — always written so the platform connects to the correct instance.
+        // For shared instances this is bolt://localhost:7687 (the default seed-neo4j.sh
+        // would use anyway), but writing it explicitly makes the .env self-documenting
+        // and ensures upgrade detection works for any future port change.
+        const neo4jUri = `bolt://localhost:${NEO4J_PORT}`;
+        if (/^NEO4J_URI=.*/m.test(envContent)) {
+            envContent = envContent.replace(/^NEO4J_URI=.*/m, `NEO4J_URI=${neo4jUri}`);
+        }
+        else {
+            envContent = envContent.trimEnd() + (envContent.length > 0 ? "\n" : "") + `NEO4J_URI=${neo4jUri}\n`;
+        }
+        writeFileSync(envPath, envContent);
+        logFile(`  .env: DISPLAY_MODE=${DISPLAY_MODE}, EMBED_MODEL=${EMBED_MODEL}, EMBED_DIMENSIONS=${EMBED_DIMS}, NEO4J_URI=${neo4jUri}`);
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to write .env to ${envPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Propagate to child processes — seed-neo4j.sh reads both variables.
+    process.env.EMBED_DIMENSIONS = String(EMBED_DIMS);
+    process.env.NEO4J_URI = `bolt://localhost:${NEO4J_PORT}`;
+    // Task 647: maxy-ui runs on an internal-only port so a restart does not
+    // drop the public TCP socket. maxy-edge.service owns the public port and
+    // the VNC stack; maxy-ui sits behind it on 127.0.0.1:MAXY_UI_INTERNAL_PORT.
+    // PORT + 1 (derived) avoids a fixed-port collision if the operator chose a
+    // non-default --port.
+    //
+    // 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 edgeUnitShort = `${BRAND.hostname}-edge`;
+    const edgeUnitName = `${edgeUnitShort}.service`;
+    // Per-brand X display (Task 553). Same value used for the edge unit's
+    // DISPLAY env (stamped via __VNC_DISPLAY__ a few lines down) so the main
+    // brand service and the edge service agree on which display Chromium runs.
+    // Task 924 + 959 — brand.json (BRAND) is the single source of truth for
+    // these fields at install time. The vncDisplay-derived offset rule lives
+    // in the brand-creation tooling; at this point in the installer BRAND
+    // already represents a parsed, validated brand manifest, and any missing
+    // field is a brand-publish defect. Loud-fail rather than silently
+    // substituting an offset (silent-fallback-masks-root-cause recurrence).
+    if (typeof BRAND.vncDisplay !== "number") {
+        console.error(`[create-maxy] error reason=cdp-port-unresolved brand=${BRAND.configDir} field=vncDisplay`);
+        throw new Error(`brand.json missing required field: vncDisplay`);
+    }
+    const VNC_DISPLAY = BRAND.vncDisplay;
+    for (const field of ["rfbPort", "websockifyPort", "cdpPort"]) {
+        if (typeof BRAND[field] !== "number") {
+            console.error(`[create-maxy] error reason=cdp-port-unresolved brand=${BRAND.configDir} field=${field}`);
+            throw new Error(`brand.json missing required field: ${field}`);
+        }
+    }
+    const RFB_PORT = BRAND.rfbPort;
+    const WEBSOCKIFY_PORT_BRAND = BRAND.websockifyPort;
+    const CDP_PORT_BRAND = BRAND.cdpPort;
+    const CLAUDE_SESSION_MANAGER_PORT_BRAND = BRAND.claudeSessionManagerPort;
+    // Task 924/938 pre-flight — refuse to write service files if any of the
+    // three brand-scoped ports is already held by a process that is NOT this
+    // brand's own on-demand browser nor a peer brand's edge stack.
+    //
+    // Classification (Task 938 chromium, Task 939 Xtigervnc + websockify) reads
+    // `/proc/<pid>/cmdline` and applies a holder-specific argv anchor. Task 938
+    // covered chromium-only via `--user-data-dir=`; Task 939 closed the gap on
+    // Xtigervnc (no such flag — anchor on the `:N` display literal) and
+    // websockify (anchor on bind port). Brand identities (configDir,
+    // vncDisplay, websockifyPort) come from brand-registry.json which the
+    // bundler stamps at build time from every brands/<brand>/brand.json.
+    //
+    // Decisions per holder:
+    //   OWN_BRAND  — SIGTERM, recheck, SIGKILL on stragglers, exit-1 only if
+    //                the port is still held after both signals.
+    //   PEER_BRAND — log OK and return (per-brand port sets are disjoint).
+    //   UNRELATED  — refuse to write service files; emit operator override.
+    // macOS dev hosts (no ss) fall through the catch and skip pre-flight
+    // entirely — the runtime check in vnc.sh covers Linux production.
+    const ownBrand = {
+        configDir: BRAND.configDir,
+        vncDisplay: VNC_DISPLAY,
+        websockifyPort: WEBSOCKIFY_PORT_BRAND,
+    };
+    // Peer registry — load from payload/platform/config/brand-registry.json
+    // when present (Task 939+ bundles). Older bundles ship without the
+    // registry; in that case peerBrands stays empty. PEER_BRAND classification
+    // for Xtigervnc/websockify is a defence-in-depth case anyway (port sets
+    // are disjoint by Task 924), so the empty-list fallback is safe — peer
+    // chromium will fall through to UNRELATED, matching pre-Task 938 behaviour
+    // for the only realistic scenario (a stale peer browser on the wrong CDP
+    // port).
+    const peerBrands = (() => {
+        const registryPath = join(PAYLOAD_DIR, "platform", "config", "brand-registry.json");
+        if (!existsSync(registryPath)) {
+            logFile(`  [preflight] brand-registry.json not in payload — peer matching disabled`);
+            return [];
+        }
+        try {
+            const raw = JSON.parse(readFileSync(registryPath, "utf-8"));
+            const entries = [];
+            for (const b of raw.brands ?? []) {
+                if (b.hostname === BRAND.hostname)
+                    continue;
+                if (typeof b.configDir !== "string" || typeof b.vncDisplay !== "number" || typeof b.websockifyPort !== "number")
+                    continue;
+                entries.push({ configDir: b.configDir, vncDisplay: b.vncDisplay, websockifyPort: b.websockifyPort });
+            }
+            return entries;
+        }
+        catch (err) {
+            logFile(`  [preflight] brand-registry.json parse failed: ${err instanceof Error ? err.message : String(err)} — peer matching disabled`);
+            return [];
+        }
+    })();
+    const ssReadHolder = (port) => {
+        return execFileSync("ss", ["-tlnpH", `sport = :${port}`], {
+            encoding: "utf-8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"],
+        });
+    };
+    // Pass raw NUL-separated cmdline to the classifier so it can argv-anchor
+    // on `--user-data-dir=`. Replacing NUL with space here would defeat that.
+    const readCmdline = (pid) => readFileSync(`/proc/${pid}/cmdline`, "utf-8");
+    const sleepMs = (ms) => { spawnSync("sleep", [(ms / 1000).toString()]); };
+    // Tightly scoped variant for retry-path ss reads. Failures here (timeout,
+    // ENOMEM, signal) are structural — never the macOS-no-ss case (we already
+    // succeeded once) — so they get a structured exit, not a stack trace.
+    const ssReadOrAbort = (label, port) => {
+        try {
+            return ssReadHolder(port);
+        }
+        catch (err) {
+            console.error(`  ERROR: [preflight] ${label}=${port} ss recheck failed: ${err instanceof Error ? err.message : String(err)}`);
+            console.error(`         Resolve manually before retrying.`);
+            process.exit(1);
+        }
+    };
+    // Distinguish ESRCH (process already gone — expected) from EPERM/EINVAL
+    // (alarming — signals we can't deliver, possibly a recycled pid). Returns
+    // true for clean kill or ESRCH, false otherwise (caller logs a warning).
+    const killNoThrow = (pid, signal) => {
+        try {
+            process.kill(pid, signal);
+            return true;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ESRCH")
+                return true;
+            logFile(`  [preflight] kill(${pid}, ${signal}) failed code=${code ?? "unknown"}`);
+            return false;
+        }
+    };
+    const classify = (ssOutput) => classifyPortHolder({
+        ssOutput, ownBrand, peerBrands, getCmdline: readCmdline,
+    });
+    // Task 939 — log line varies by detected holder so the operator can see
+    // which OWN_BRAND stack is being killed. The kill loop is identical for
+    // all three holders (SIGTERM → 300ms → recheck → SIGKILL → recheck), so
+    // only the announce line differs.
+    const ownBrandAnnounceLine = (label, port, c) => {
+        if (c.holderType === "xtigervnc") {
+            return `  [preflight] ${label}=${port} held by OWN brand Xtigervnc display=:${c.vncDisplay} pid=${c.pid} — sending SIGTERM`;
+        }
+        if (c.holderType === "websockify") {
+            return `  [preflight] ${label}=${port} held by OWN brand websockify pid=${c.pid} — sending SIGTERM`;
+        }
+        // Default — chromium / unknown OWN_BRAND
+        return `  [preflight] ${label}=${port} held by OWN brand process pid=${c.pid} profile=${c.profilePath} — sending SIGTERM`;
+    };
+    const checkInstallPortFree = (label, port) => {
+        let firstSsOutput;
+        try {
+            firstSsOutput = ssReadHolder(port);
+        }
+        catch (err) {
+            // ss may not be present on macOS dev hosts — skip the pre-flight there
+            // rather than abort the install. The runtime check in vnc.sh covers
+            // production-like Linux installs where this matters. This catch is
+            // narrow on purpose: only the first ss invocation may legitimately
+            // fail (binary missing); retry-path failures use ssReadOrAbort.
+            logFile(`  [preflight] ${label}=${port} check skipped: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        let r = classify(firstSsOutput);
+        // ENOENT race — process exited between ss and cmdline read. Port is
+        // probably free now; one re-check resolves it deterministically.
+        if (r.cmdlineReadFailed)
+            r = classify(ssReadOrAbort(label, port));
+        if (r.kind === "EMPTY")
+            return;
+        if (r.kind === "PEER_BRAND") {
+            logFile(`  [preflight] ${label}=${port} held by a peer brand's stack — OK (per-brand ports are disjoint by construction)`);
+            return;
+        }
+        if (r.kind === "OWN_BRAND" && r.pid !== undefined) {
+            logFile(ownBrandAnnounceLine(label, port, r));
+            killNoThrow(r.pid, "SIGTERM");
+            sleepMs(300);
+            const after = classify(ssReadOrAbort(label, port));
+            if (after.kind === "EMPTY") {
+                logFile(`  [preflight] ${label}=${port} freed`);
+                return;
+            }
+            if (after.kind === "OWN_BRAND" && after.pid === r.pid) {
+                logFile(`  [preflight] ${label}=${port} survived SIGTERM — sending SIGKILL`);
+                killNoThrow(r.pid, "SIGKILL");
+                sleepMs(300);
+                const final = classify(ssReadOrAbort(label, port));
+                if (final.kind === "EMPTY") {
+                    logFile(`  [preflight] ${label}=${port} freed`);
+                    return;
+                }
+                console.error(`  ERROR: [preflight] ${label}=${port} OWN_BRAND auto-kill failed pid=${r.pid} — resolve manually before retrying.`);
+                process.exit(1);
+            }
+            // A different OWN_BRAND pid took the port. The brand's user services
+            // are respawning Chromium — installer cannot win this race. Stop the
+            // services, then retry.
+            if (after.kind === "OWN_BRAND") {
+                console.error(`  ERROR: [preflight] ${label}=${port} brand respawned a new OWN_BRAND pid (was ${r.pid}, now ${after.pid}).`);
+                console.error(`         Stop the brand's user services first: \`systemctl --user stop ${BRAND.hostname}-edge ${BRAND.hostname}\`, then re-run the installer.`);
+                process.exit(1);
+            }
+            // PEER_BRAND or UNRELATED took the port post-kill — fall through to
+            // those branches by re-classifying the surviving holder.
+            r = after;
+            if (r.kind === "EMPTY")
+                return;
+            if (r.kind === "PEER_BRAND") {
+                logFile(`  [preflight] ${label}=${port} now held by a peer brand's stack — OK`);
+                return;
+            }
+            // r.kind === "UNRELATED" — fall through to the operator-override block.
+        }
+        // UNRELATED — preserve the operator-override path verbatim.
+        console.error(`  ERROR: [preflight:collision] brand=${BRAND.hostname} ${label}=${port} held by an unrelated process:`);
+        console.error(`         ${firstSsOutput.trim()}`);
+        if (r.cmdline)
+            console.error(`         cmdline: ${r.cmdline}`);
+        console.error(`         Refusing to write service files; resolve the collision before retrying.`);
+        console.error(`         Operator override: edit brands/${BRAND.hostname}/brand.json, set/add \`${label}\` to a free port, re-bundle, re-install.`);
+        process.exit(1);
+    };
+    checkInstallPortFree("rfbPort", RFB_PORT);
+    checkInstallPortFree("websockifyPort", WEBSOCKIFY_PORT_BRAND);
+    checkInstallPortFree("cdpPort", CDP_PORT_BRAND);
+    // Task 955 — ACCOUNT_ID stamped into the brand unit so the writeNodeWithEdges
+    // gate at platform/lib/graph-write/src/index.ts:170 has a real identity to
+    // compare against (instead of process.env.ACCOUNT_ID === undefined). Resolved
+    // here AFTER setupAccount() ran upstream — seed-neo4j.sh wrote account.json,
+    // so an empty resolution at this point is a corrupted install (e.g. the seed
+    // failed silently, or accounts/ was wiped between setup and unit-write).
+    const installAccountId = resolveInstallAccountId();
+    if (!installAccountId) {
+        throw new Error(`installService: no account discovered at ${INSTALL_DIR}/data/accounts/<uuid>/account.json — ` +
+            `setupAccount() (seed-neo4j.sh) should have created one. Refusing to write a systemd unit ` +
+            `without ACCOUNT_ID; the boot validator would FATAL on every restart.`);
+    }
+    const serviceFile = buildMaxyUnitFile({
+        productName: BRAND.productName,
+        brandHostname: BRAND.hostname,
+        neo4jDedicated: NEO4J_DEDICATED,
+        installDir: INSTALL_DIR,
+        persistDir,
+        port: PORT,
+        maxyUiInternalPort: MAXY_UI_INTERNAL_PORT,
+        vncDisplay: VNC_DISPLAY,
+        rfbPort: RFB_PORT,
+        websockifyPort: WEBSOCKIFY_PORT_BRAND,
+        cdpPort: CDP_PORT_BRAND,
+        claudeSessionManagerPort: CLAUDE_SESSION_MANAGER_PORT_BRAND, // Task 001 (maxy-code)
+        chromiumBin: RESOLVED_CHROMIUM_BIN, // Task 929
+        accountId: installAccountId, // Task 955
+    });
+    writeFileSync(join(serviceDir, BRAND.serviceName), serviceFile);
+    // Task 001 (maxy-code) — write the claude-session-manager unit. The main
+    // brand unit Requires= + After= this one, so systemd starts it first.
+    const claudeSessionManagerUnitName = `${BRAND.hostname}-claude-session-manager.service`;
+    const claudeSessionManagerUnit = buildClaudeSessionManagerUnitFile({
+        productName: BRAND.productName,
+        brandHostname: BRAND.hostname,
+        installDir: INSTALL_DIR,
+        persistDir,
+        claudeSessionManagerPort: CLAUDE_SESSION_MANAGER_PORT_BRAND,
+        accountId: installAccountId,
+    });
+    writeFileSync(join(serviceDir, claudeSessionManagerUnitName), claudeSessionManagerUnit);
+    logFile(`  ${claudeSessionManagerUnitName}: CLAUDE_SESSION_MANAGER_PORT=${CLAUDE_SESSION_MANAGER_PORT_BRAND}`);
+    // 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.
+    // VNC_DISPLAY (defined above for the main brand unit) is also stamped into
+    // the edge unit so both services agree on the X display. Per-brand display
+    // closes the cross-brand cookie leak documented in Task 553.
+    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)
+            .replace(/__VNC_DISPLAY__/g, String(VNC_DISPLAY))
+            .replace(/__WEBSOCKIFY_PORT__/g, String(WEBSOCKIFY_PORT_BRAND))
+            .replace(/__CDP_PORT__/g, String(CDP_PORT_BRAND))
+            .replace(/__RFB_PORT__/g, String(RFB_PORT));
+        writeFileSync(join(serviceDir, edgeUnitName), edgeServiceContent);
+        logFile(`  ${edgeUnitName}: EDGE_PORT=${PORT} MAXY_UI_PORT=${MAXY_UI_INTERNAL_PORT} VNC_DISPLAY=:${VNC_DISPLAY} RFB_PORT=${RFB_PORT} WEBSOCKIFY_PORT=${WEBSOCKIFY_PORT_BRAND} CDP_PORT=${CDP_PORT_BRAND}`);
+    }
+    else {
+        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
+    // this line, the service inherits the default systemd-user PATH — which
+    // excludes ~/.local/bin — and the shim exits ENOENT before any query lands.
+    logFile(`  ${BRAND.serviceName}: PATH env includes %h/.local/bin for uvx resolution`);
+    // WiFi AP provisioning service — system-level (requires root for hostapd/dnsmasq).
+    // Runs at boot to check connectivity. If no saved WiFi and no ethernet, activates
+    // a temporary AP with a captive portal for first-time WiFi configuration.
+    const currentUser = execFileSync("whoami", [], { encoding: "utf-8" }).trim();
+    const wifiProvisionService = `[Unit]
+Description=${BRAND.productName} WiFi Provisioning
+After=NetworkManager.service
+Before=${BRAND.serviceName}
+
+[Service]
+Type=simple
+ExecStart=/bin/bash ${INSTALL_DIR}/platform/scripts/wifi-provision.sh
+ExecStopPost=/bin/bash ${INSTALL_DIR}/platform/scripts/wifi-provision.sh cleanup
+Environment=MAXY_PLATFORM_ROOT=${INSTALL_DIR}/platform
+Environment=INSTALL_USER=${currentUser}
+Environment=INSTALL_HOME=${process.env.HOME ?? "/home/" + currentUser}
+TimeoutStartSec=300
+TimeoutStopSec=30
+
+[Install]
+WantedBy=multi-user.target
+`;
+    const systemServiceDir = "/etc/systemd/system";
+    const wifiProvisionPath = join(systemServiceDir, "wifi-provision.service");
+    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" });
+        spawnSync("sudo", ["systemctl", "enable", "wifi-provision"], { stdio: "inherit" });
+        logFile("  WiFi provisioning service installed and enabled");
+    }
+    catch (err) {
+        console.error(`  WARNING: Failed to install wifi-provision service: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Disable hostapd and dnsmasq system services (we manage them manually
+    // from wifi-provision.sh — the system services would conflict).
+    spawnSync("sudo", ["systemctl", "stop", "hostapd"], { stdio: "ignore" });
+    spawnSync("sudo", ["systemctl", "disable", "hostapd"], { stdio: "ignore" });
+    spawnSync("sudo", ["systemctl", "stop", "dnsmasq"], { stdio: "ignore" });
+    spawnSync("sudo", ["systemctl", "disable", "dnsmasq"], { stdio: "ignore" });
+    // Enable lingering so user services run without login
+    try {
+        spawnSync("sudo", ["loginctl", "enable-linger", currentUser], { stdio: "inherit" });
+    }
+    catch { /* not critical */ }
+    // Reload and (re)start.
+    //
+    // 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", "");
+    const claudeSessionManagerUnitShort = claudeSessionManagerUnitName.replace(".service", "");
+    spawnSync("systemctl", ["--user", "stop", unitName], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "enable", edgeUnitShort], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "enable", claudeSessionManagerUnitShort], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "enable", unitName], { stdio: "inherit" });
+    // edge first: binds public port + starts VNC stack. Then claude-session-manager
+    // (so the main brand unit's Requires= is satisfied). Then main brand service.
+    spawnSync("systemctl", ["--user", "restart", edgeUnitShort], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "restart", claudeSessionManagerUnitShort], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "restart", unitName], { stdio: "inherit" });
+    // Wait for the server to come up
+    console.log("  Waiting for web server...");
+    let webServerUp = false;
+    for (let i = 0; i < 20; i++) {
+        try {
+            execFileSync("curl", ["-sf", `http://localhost:${PORT}`, "-o", "/dev/null"], { timeout: 3000 });
+            webServerUp = true;
+            break;
+        }
+        catch {
+            spawnSync("sleep", ["2"]);
+        }
+    }
+    if (!webServerUp) {
+        console.log(`  Server may still be starting. Check http://${DEVICE_HOSTNAME}.local:${PORT} in a moment.`);
+    }
+    // Register cron jobs — depends on web server, independent of CDP
+    installCrons();
+    // Validate CDP: the programmatic Playwright MCP server connects to Chromium
+    // via --cdp-endpoint http://127.0.0.1:9222. In virtual (VNC) mode, Chromium is
+    // started by vnc.sh (ExecStartPre) before the web server — a failed probe here
+    // indicates a genuine VNC boot failure and must fail the install loudly.
+    // In native mode, Chromium is launched on-demand by the server and is not
+    // expected to be bound at install time — the probe is skipped.
+    if (DISPLAY_MODE === "native") {
+        console.log("  [cdp-check] skipped reason=native-display (on-demand Chromium)");
+    }
+    else {
+        console.log(`  Verifying browser automation (CDP on port ${CDP_PORT_BRAND})...`);
+        const cdpCheck = spawnSync("curl", ["-sf", `http://127.0.0.1:${CDP_PORT_BRAND}/json/version`, "-o", "/dev/null"], {
+            timeout: 5000,
+            stdio: "pipe",
+        });
+        if (cdpCheck.status === 0) {
+            console.log("  Browser automation ready (CDP connected).");
+        }
+        else {
+            const vncLogPath = resolve(process.env.HOME ?? "/root", BRAND.configDir, "logs/vnc-boot.log");
+            let vncLog = "";
+            try {
+                vncLog = readFileSync(vncLogPath, "utf-8").slice(-2000);
+            }
+            catch {
+                vncLog = `(no boot log found at ${vncLogPath})`;
+            }
+            console.error("");
+            console.error(`Setup failed: Browser automation unavailable — CDP port ${CDP_PORT_BRAND} not responding`);
+            console.error(`  ERROR: Browser automation unavailable — CDP port ${CDP_PORT_BRAND} not responding.`);
+            console.error("  Chromium should be started by vnc.sh (ExecStartPre). Check the boot log:");
+            console.error("");
+            console.error(vncLog);
+            process.exit(1);
+        }
+    }
+    // Tunnel script smoke check — the cloudflare SKILL contract invokes
+    // ~/setup-tunnel.sh directly. If the install-time symlink creation in
+    // installTunnelScripts() didn't land, fail the install loudly here rather
+    // than shipping the exact Task 456 gap Task 555 exists to close.
+    for (const linkPath of [
+        resolve(process.env.HOME ?? "/root", "setup-tunnel.sh"),
+        resolve(process.env.HOME ?? "/root", "reset-tunnel.sh"),
+        resolve(process.env.HOME ?? "/root", "list-cf-domains.sh"),
+    ]) {
+        try {
+            accessSync(linkPath, fsConstants.X_OK);
+            console.log(`  [create-maxy] verify: ${linkPath} executable ✓`);
+        }
+        catch (err) {
+            console.error("");
+            console.error(`Setup failed: tunnel script symlink missing or not executable: ${linkPath}`);
+            console.error(`  [create-maxy:error] tunnel script symlink missing or not executable: ${linkPath}`);
+            console.error(`  ${err.message}`);
+            process.exit(1);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+// Route to uninstall if --uninstall flag is present
+const _args = process.argv.slice(2);
+if (_args.includes("--uninstall")) {
+    const { runUninstall } = await import("./uninstall.js");
+    const exportIdx = _args.indexOf("--export-data");
+    const exportPath = exportIdx !== -1 ? _args[exportIdx + 1] : undefined;
+    const skipConfirm = _args.includes("--yes");
+    if (exportIdx !== -1 && !exportPath) {
+        console.error("Setup failed: --export-data requires a path argument");
+        console.error("--export-data requires a path argument.");
+        process.exit(1);
+    }
+    await runUninstall({ exportPath, skipConfirm });
+    process.exit(0);
+}
+// ---------------------------------------------------------------------------
+// Port — install-time flag, not a brand attribute.
+//
+// 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 portFlag;
+const portIdx = _args.indexOf("--port");
+if (portIdx !== -1) {
+    const raw = _args[portIdx + 1];
+    const parsed = raw ? parseInt(raw, 10) : NaN;
+    if (isNaN(parsed) || parsed < 1024 || parsed > 65535) {
+        console.error(`Setup failed: --port requires a numeric value between 1024 and 65535 (got: ${raw ?? "nothing"})`);
+        console.error(`Error: --port requires a numeric value between 1024 and 65535 (got: ${raw ?? "nothing"}).`);
+        process.exit(1);
+    }
+    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.
+//
+// Priority: --hostname flag > OS detection (same-brand upgrade) > OS preservation
+// (another brand's service detected) > BRAND.hostname (fresh install).
+// When --hostname is provided, it is set unconditionally — no detection, no preservation.
+// ---------------------------------------------------------------------------
+let HOSTNAME_FLAG;
+const hostnameIdx = _args.indexOf("--hostname");
+if (hostnameIdx !== -1) {
+    const raw = _args[hostnameIdx + 1];
+    if (!raw || raw.startsWith("--")) {
+        console.error("Setup failed: --hostname requires a value");
+        console.error("Error: --hostname requires a value (e.g. --hostname muvin).");
+        process.exit(1);
+    }
+    // RFC 1123: lowercase alphanumeric + hyphens, max 63 chars, no leading/trailing hyphen
+    if (!/^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/.test(raw)) {
+        console.error(`Setup failed: --hostname value '${raw}' is invalid`);
+        console.error(`Error: --hostname value '${raw}' is invalid. Must be lowercase letters, digits, and hyphens only (max 63 chars, no leading/trailing hyphen).`);
+        process.exit(1);
+    }
+    HOSTNAME_FLAG = raw;
+}
+let DISPLAY_MODE = "virtual";
+let DISPLAY_MODE_SOURCE = "default";
+const displayIdx = _args.indexOf("--display");
+if (displayIdx !== -1) {
+    const raw = _args[displayIdx + 1];
+    if (!raw || raw.startsWith("--")) {
+        console.error("Setup failed: --display requires a value");
+        console.error("Error: --display requires a value: native or virtual.");
+        process.exit(1);
+    }
+    if (raw !== "native" && raw !== "virtual") {
+        console.error(`Setup failed: --display value '${raw}' is invalid`);
+        console.error(`Error: --display value '${raw}' is invalid. Must be 'native' or 'virtual'.`);
+        process.exit(1);
+    }
+    DISPLAY_MODE = raw;
+    DISPLAY_MODE_SOURCE = "--display flag";
+}
+else {
+    // Upgrade detection: preserve existing DISPLAY_MODE from .env
+    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(/^DISPLAY_MODE=(native|virtual)$/m);
+            if (envMatch) {
+                DISPLAY_MODE = envMatch[1];
+                DISPLAY_MODE_SOURCE = ".env (preserved)";
+            }
+        }
+    }
+    catch { /* non-critical */ }
+}
+// ---------------------------------------------------------------------------
+// Embedding model — install-time flag, not a brand attribute.
+//
+// Controls which Ollama embedding model is pulled and the dimension count used
+// for Neo4j vector indexes. Dimensions are fixed at schema-creation time; changing
+// them later requires dropping and recreating all vector indexes.
+//
+// Priority: --embed-model flag > .env (upgrade) > default nomic-embed-text.
+// --embed-dimensions is required for models not in the curated lookup table.
+// --embed-dimensions without --embed-model is rejected (dimensions are model-specific).
+// ---------------------------------------------------------------------------
+const EMBED_MODEL_DIMS = {
+    "nomic-embed-text": 768,
+    "nomic-embed-text-v1.5": 768,
+    "mxbai-embed-large": 1024,
+    "snowflake-arctic-embed:335m": 768,
+};
+const DEFAULT_EMBED_MODEL = "nomic-embed-text";
+const DEFAULT_EMBED_DIMS = 768;
+let EMBED_MODEL = DEFAULT_EMBED_MODEL;
+let EMBED_DIMS = DEFAULT_EMBED_DIMS;
+let EMBED_SOURCE = "default";
+const embedModelIdx = _args.indexOf("--embed-model");
+const embedDimsIdx = _args.indexOf("--embed-dimensions");
+if (embedDimsIdx !== -1 && embedModelIdx === -1) {
+    console.error("Setup failed: --embed-dimensions requires --embed-model");
+    console.error("Error: --embed-dimensions requires --embed-model (dimensions are model-specific).");
+    process.exit(1);
+}
+if (embedModelIdx !== -1) {
+    const raw = _args[embedModelIdx + 1];
+    if (!raw || raw.startsWith("--")) {
+        console.error("Setup failed: --embed-model requires a value");
+        console.error("Error: --embed-model requires a value (e.g. --embed-model mxbai-embed-large).");
+        process.exit(1);
+    }
+    EMBED_MODEL = raw;
+    EMBED_SOURCE = "--embed-model flag";
+    if (embedDimsIdx !== -1) {
+        // Explicit dimensions override the lookup table
+        const rawDims = _args[embedDimsIdx + 1];
+        const parsed = rawDims ? parseInt(rawDims, 10) : NaN;
+        if (isNaN(parsed) || parsed <= 0) {
+            console.error(`Setup failed: --embed-dimensions requires a positive integer (got: ${rawDims ?? "nothing"})`);
+            console.error(`Error: --embed-dimensions requires a positive integer (got: ${rawDims ?? "nothing"}).`);
+            process.exit(1);
+        }
+        EMBED_DIMS = parsed;
+    }
+    else if (EMBED_MODEL in EMBED_MODEL_DIMS) {
+        // Known model — resolve dimensions from lookup table
+        EMBED_DIMS = EMBED_MODEL_DIMS[EMBED_MODEL];
+    }
+    else {
+        // Unknown model without explicit dimensions — cannot proceed
+        console.error(`Setup failed: unknown embedding model '${EMBED_MODEL}'`);
+        console.error(`Error: Unknown embedding model '${EMBED_MODEL}'.`);
+        console.error("Known models and their dimensions:");
+        for (const [model, dims] of Object.entries(EMBED_MODEL_DIMS)) {
+            console.error(`  ${model} — ${dims} dimensions`);
+        }
+        console.error("\nFor a custom model, pass --embed-dimensions N explicitly:");
+        console.error(`  npx -y @rubytech/create-maxy --embed-model ${EMBED_MODEL} --embed-dimensions 512`);
+        process.exit(1);
+    }
+}
+else {
+    // No --embed-model flag: check .env for upgrade preservation
+    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 modelMatch = envContent.match(/^EMBED_MODEL=(.+)$/m);
+            const dimsMatch = envContent.match(/^EMBED_DIMENSIONS=(\d+)$/m);
+            if (modelMatch) {
+                EMBED_MODEL = modelMatch[1];
+                EMBED_SOURCE = ".env (preserved)";
+                if (dimsMatch) {
+                    EMBED_DIMS = parseInt(dimsMatch[1], 10);
+                }
+                else if (EMBED_MODEL in EMBED_MODEL_DIMS) {
+                    EMBED_DIMS = EMBED_MODEL_DIMS[EMBED_MODEL];
+                }
+                // Unknown model without dims in .env: keep DEFAULT_EMBED_DIMS — the schema
+                // was created with whatever dims were configured at original install time.
+            }
+        }
+    }
+    catch { /* non-critical */ }
+}
+// ---------------------------------------------------------------------------
+// Neo4j port — multi-brand data isolation.
+//
+// Default Maxy brand: 7687 (shared system Neo4j instance). Branded builds ship
+// a dedicated port in brand.json (e.g. Real Agent = 7688) so installing a
+// second brand on the same device gets its own database by default — Task 659.
+//
+// Priority: --neo4j-port flag > .env NEO4J_URI (upgrade preserve) > BRAND.neo4jPort > 7687.
+// ---------------------------------------------------------------------------
+const DEFAULT_NEO4J_PORT = 7687;
+let NEO4J_PORT = BRAND.neo4jPort ?? DEFAULT_NEO4J_PORT;
+let NEO4J_PORT_SOURCE = BRAND.neo4jPort ? "brand.json" : "default";
+const neo4jPortIdx = _args.indexOf("--neo4j-port");
+if (neo4jPortIdx !== -1) {
+    const raw = _args[neo4jPortIdx + 1];
+    const parsed = raw ? parseInt(raw, 10) : NaN;
+    if (isNaN(parsed) || parsed < 1024 || parsed > 65535) {
+        console.error(`Setup failed: --neo4j-port requires a numeric value between 1024 and 65535 (got: ${raw ?? "nothing"})`);
+        console.error(`Error: --neo4j-port requires a numeric value between 1024 and 65535 (got: ${raw ?? "nothing"}).`);
+        process.exit(1);
+    }
+    NEO4J_PORT = parsed;
+    NEO4J_PORT_SOURCE = "--neo4j-port flag";
+}
+else {
+    // Upgrade detection: check .env for NEO4J_URI=bolt://localhost:{port}.
+    // Preserves an existing install's port even if brand.json now says different.
+    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 uriMatch = envContent.match(/^NEO4J_URI=bolt:\/\/localhost:(\d+)$/m);
+            if (uriMatch) {
+                const envPort = parseInt(uriMatch[1], 10);
+                if (envPort >= 1024 && envPort <= 65535) {
+                    NEO4J_PORT = envPort;
+                    NEO4J_PORT_SOURCE = ".env (preserved)";
+                }
+            }
+        }
+    }
+    catch { /* non-critical */ }
+}
+// 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;
+// ---------------------------------------------------------------------------
+// Task 840 — pre-flight platform refusal.
+//
+// Runs BEFORE initLogging() (LOG_DIR creation), port resolution, and any
+// brew/scutil/hostnamectl probe. Only Linux + darwin are supported (Task 836);
+// on darwin, macOS major must be ≥ 14 (the floor required by Tasks 838/839).
+// Older macOS partially succeeds, then breaks at the supervisor or brew-cellar
+// layer with cryptic errors — refusing loudly here is the contract.
+//
+// Platform-header line is emitted on every install start so operators can grep
+// `[create-maxy] platform=` to confirm pre-flight ran. On darwin the line also
+// carries `macos=<v>` (Task 840 token) so the macOS-14 floor check is visible.
+// ---------------------------------------------------------------------------
+const PLATFORM = requireSupportedPlatform(process.platform);
+let MACOS_VERSION = null;
+if (PLATFORM === "darwin") {
+    const swVers = spawnSync("sw_vers", [], { encoding: "utf-8", stdio: "pipe", timeout: 5_000 });
+    const parsed = parseSwVers(swVers.stdout ?? "");
+    if (!parsed) {
+        const head = (swVers.stdout ?? "").split("\n").slice(0, 2).join(" | ");
+        console.error(`[create-maxy] sw_vers stdout malformed: ${head}`);
+        console.error(`[create-maxy] platform=darwin macos=<unknown> — refusing: macOS 14+ required`);
+        process.exit(1);
+    }
+    MACOS_VERSION = parsed.version;
+    if (!isSupportedMacosVersion(MACOS_VERSION)) {
+        console.error(`[create-maxy] platform=darwin macos=${MACOS_VERSION} — refusing: macOS 14+ required`);
+        process.exit(1);
+    }
+}
+// Platform-header — first log line. Operators grep `[create-maxy] platform=`
+// to confirm pre-flight ran. The /* macos=<v> */ token is the Task 840 marker;
+// keep it on this same line so 3-way merges with parallel installer edits stay
+// mechanical (no rewrap, no split into two log lines).
+const PLATFORM_HEADER = `[create-maxy] platform=${PLATFORM} arch=${process.arch}` +
+    (MACOS_VERSION ? ` macos=${MACOS_VERSION}` : ``) +
+    ` version=${PKG_VERSION}`;
+initLogging();
+console.log(PLATFORM_HEADER);
+console.log("================================================================");
+console.log(`  ${BRAND.productName} — ${BRAND.tagline}.  (${BRAND.hostname} v${PKG_VERSION})`);
+console.log("================================================================");
+console.log(`  Install log: ${LOG_FILE}`);
+console.log(`  Port: ${PORT} (${PORT_SOURCE})`);
+if (HOSTNAME_FLAG)
+    console.log(`  Hostname: ${HOSTNAME_FLAG} (from --hostname flag)`);
+console.log(`  Display: ${DISPLAY_MODE} (${DISPLAY_MODE_SOURCE})`);
+console.log(`  Embed model: ${EMBED_MODEL} (${EMBED_DIMS} dims, ${EMBED_SOURCE})`);
+console.log(`  Neo4j: ${NEO4J_DEDICATED ? "dedicated" : "shared"} on bolt://localhost:${NEO4J_PORT} (${NEO4J_PORT_SOURCE})`);
+console.log("");
+logDiagnostics("pre-flight");
+logFile(`  Neo4j instance: ${NEO4J_DEDICATED ? "dedicated" : "shared"} on bolt://localhost:${NEO4J_PORT}`);
+try {
+    installSystemDeps();
+    installNodejs();
+    installClaudeCode();
+    installNeo4j();
+    setupDedicatedNeo4j();
+    installOllama(EMBED_MODEL);
+    installUv();
+    installCloudflared();
+    installWhisperCpp();
+    deployPayload(); // Must happen before ensureNeo4jPassword — restores config backup
+    // Task 929: write the resolved Chromium absolute path into the deployed
+    // platform/config/ so vnc.sh, writeChromiumWrapper, and setup-tunnel.sh
+    // all read the same value. Must run after deployPayload (config dir is
+    // a payload subdirectory). Linux-only; no-op on darwin/non-linux.
+    writeChromiumBinaryPathFile();
+    // Task 744: scrub plaintext neo4j passwords from any pre-fix install-*.log.
+    // Idempotent — re-running on already-redacted logs is a no-op. Runs after
+    // payload deploy so the bundled redact-install-logs.sh is on disk.
+    redactInstallLogs();
+    ensureNeo4jPassword(); // Now config/.neo4j-password is available if it existed before
+    provisionRemoteSessionSecret(); // Task 653: shared HMAC key readable by maxy-edge + maxy-ui
+    buildPlatform();
+    setupVncViewer();
+    setupAccount();
+    installTunnelScripts(); // ~/setup-tunnel.sh, ~/reset-tunnel.sh — the SKILL contract
+    installService();
+    console.log("");
+    console.log("================================================================");
+    console.log("");
+    console.log(`  Open in your browser: http://${DEVICE_HOSTNAME}.local:${PORT}`);
+    console.log("");
+    console.log("================================================================");
+}
+catch (err) {
+    console.error("");
+    console.error(`Setup failed: ${err instanceof Error ? err.message : String(err)}`);
+    console.error(`  Full log: ${LOG_FILE}`);
+    logDiagnostics("post-failure");
+    process.exit(1);
+}