@rubytech/create-siteoffice-code 0.1.256

package/dist/index.js

@@ -0,0 +1,4048 @@
+#!/usr/bin/env node
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync, cpSync, readFileSync, rmSync, readdirSync, appendFileSync, openSync, closeSync, chmodSync, statSync, realpathSync } from "node:fs";
+import { registerSpecialistAgentsAt, SpecialistSymlinkCollision } from "./specialist-registration.js";
+import { seedBypassPermissionsSettings, assertBypassPermissionsSeed } from "./permissions-seed.js";
+import { resolve, join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { resolveInstallPortFromFs, buildMaxyUnitFile, buildClaudeSessionManagerUnitFile, buildClaudePtysSliceUnitFile, buildCloudflaredSliceUnitFile } from "./port-resolution.js";
+import { validateTierFlag, validateEntitlementBase64, applyTierToAccountConfig, entitlementPath } from "./tier-flag.js";
+import { parseOsRelease, isUbuntuLike as isUbuntuLikePure, parseAptCacheCandidate, decideAptResolution, } from "./apt-resolve.js";
+import { findPeerBrandOnDefaultNeo4jPort } from "./peer-brand-detect.js";
+import { runInitLogging } from "./init-logging.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";
+import { parsePluginList, computeInstallActions, parseExternalPlugins, } from "./lib/plugin-install.js";
+import { findPremiumMcpDirs } from "./lib/premium-mcp-discover.js";
+import { pickLanInterface, mergeSmbConf, formatSambaMarker, } from "./samba-provision.js";
+import { networkInterfaces, userInfo } from "node:os";
+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 PERSIST_DIR = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+const LOG_DIR = join(PERSIST_DIR, "logs");
+const LOG_FILE = join(LOG_DIR, `install-${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+// every `claude plugin` shellout must read/write the per-brand
+// CLAUDE_CONFIG_DIR that the systemd unit at port-resolution.ts:229,286 uses
+// at runtime. Without this override, the installer writes marketplaces and
+// enabledPlugins to $HOME/.claude/settings.json (user-default), and the
+// PTY spawned by the session-manager sees an empty config dir — plugins
+// the operator turned on are invisible to the agent.
+const CLAUDE_CONFIG_DIR = join(PERSIST_DIR, ".claude");
+function claudePluginEnv() {
+    return { ...process.env, CLAUDE_CONFIG_DIR };
+}
+/** Known brand hostnames in the Maxy ecosystem. Each brand ships a main unit
+ *  (`<hostname>.service`) and a per-brand edge unit
+ *  (`<hostname>-edge.service`). 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", "maxy-code", "realagent", "realagent-code", "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;
+// 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() {
+    runInitLogging({
+        logDir: LOG_DIR,
+        logFile: LOG_FILE,
+        persistDir: PERSIST_DIR,
+        headerLines: [
+            "",
+            "=".repeat(64),
+            `  ${BRAND.productName} Install Log — ${new Date().toISOString()}`,
+            `  Node ${process.version} | ${process.platform} ${process.arch}`,
+            "=".repeat(64),
+            "",
+        ],
+    });
+}
+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: 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: 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;
+}
+// verified-not-asserted apt-dep reconciliation.
+// 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. 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}`;
+}
+/**
+ * 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 the 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 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";
+/**
+ * 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`);
+}
+/**
+ * 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 the original denial 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);
+}
+/**
+ * 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} (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
+            ? "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`);
+}
+/**
+ * write the resolved Chromium absolute path to
+ * `<INSTALL_DIR>/platform/config/chromium-binary.path` so vnc.sh and
+ * writeChromiumWrapper 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") {
+        // 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)`);
+            logFile(`  [create-maxy] darwin-hostname-mode=scutil-set value=${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 {
+            // No flag — read the live LocalHostName so the printed URL matches mDNS
+            // resolution (`<LocalHostName>.local`). The `hostname` command on darwin
+            // returns the fully-qualified `<name>.local`, which would render the
+            // completion URL with a double `.local` suffix; scutil --get returns the
+            // bare token. No sudo, no system mutation.
+            const scutilGet = spawnSync("scutil", ["--get", "LocalHostName"], { encoding: "utf-8", stdio: "pipe", timeout: 5_000 });
+            const scutilName = ((scutilGet.stdout ?? "").trim());
+            if (scutilGet.status === 0 && scutilName.length > 0) {
+                DEVICE_HOSTNAME = scutilName;
+                console.log(`  Hostname: ${DEVICE_HOSTNAME} (from scutil --get LocalHostName — no --hostname flag)`);
+                logFile(`  [create-maxy] darwin-hostname-mode=scutil-get value=${DEVICE_HOSTNAME}`);
+            }
+            else {
+                // scutil failed or returned empty — fall back to BRAND.hostname so the
+                // completion URL at least matches the brand's documented .local name.
+                DEVICE_HOSTNAME = BRAND.hostname;
+                console.log(`  Hostname: ${DEVICE_HOSTNAME} (brand fallback — scutil --get LocalHostName empty)`);
+                logFile(`  [create-maxy] darwin-hostname-mode=brand-fallback value=${DEVICE_HOSTNAME} scutil-status=${scutilGet.status}`);
+            }
+        }
+        // macOS has no apt analogue for the VNC/WiFi-AP stacks
+        // (kiosk display + hostapd/dnsmasq are Pi-specific'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", "tesseract", "ocrmypdf"];
+        installAllBrewPackages(DARWIN_BASE_DEPS, logFile);
+        return;
+    }
+    const BASE_DEPS = ["curl", "git", "unzip", "jq", "avahi-daemon", "avahi-utils", "poppler-utils", "ffmpeg", "bind9-dnsutils", "tesseract-ocr", "ocrmypdf"];
+    // xterm is the *preferred* terminal-emulator binary for the VNC-rendered
+    // Terminal surface
+    // 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 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"];
+    // 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];
+    // verify the "deps are present" assumption with `dpkg -s` instead
+    // of asserting it (feedback_loud_failures.md). The previous silent-skip
+    // branch was benign 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);
+    }
+    // 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();
+    // Task 600 — provision swap so the OOM-killer has a buffer to work in
+    // instead of silently freezing the box. dphys-swapfile is the standard
+    // Raspberry Pi OS swap manager. CONF_MAXSWAP raised to 4096 so the
+    // operator can manually grow the swap file without reinstalling.
+    // Best-effort: a failure here warns but does not abort the install.
+    try {
+        console.log("  [privileged] apt-get install dphys-swapfile");
+        shell("apt-get", ["install", "-y", "dphys-swapfile"], { sudo: true, bestEffort: true });
+        const desiredSwapConf = "CONF_SWAPSIZE=2048\nCONF_MAXSWAP=4096\n";
+        const swapConfPath = "/etc/dphys-swapfile";
+        let swapCurrent = "";
+        if (existsSync(swapConfPath)) {
+            try {
+                swapCurrent = readFileSync(swapConfPath, "utf-8");
+            }
+            catch {
+                swapCurrent = "";
+            }
+        }
+        if (swapCurrent === desiredSwapConf) {
+            logFile("  swap: already configured (CONF_SWAPSIZE=2048 CONF_MAXSWAP=4096)");
+        }
+        else {
+            const swapTmpPath = `/tmp/dphys-swapfile.${process.pid}`;
+            writeFileSync(swapTmpPath, desiredSwapConf);
+            console.log("  [privileged] install /etc/dphys-swapfile (CONF_SWAPSIZE=2048 CONF_MAXSWAP=4096)");
+            shell("cp", [swapTmpPath, swapConfPath], { sudo: true });
+            spawnSync("rm", ["-f", swapTmpPath]);
+            console.log("  [privileged] systemctl restart dphys-swapfile");
+            shell("systemctl", ["restart", "dphys-swapfile"], { sudo: true, bestEffort: true });
+            logFile("  swap: configured CONF_SWAPSIZE=2048 CONF_MAXSWAP=4096 and restarted dphys-swapfile");
+        }
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to provision swap: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // 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));
+        // 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 the `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.
+        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...");
+    // pre-create the per-brand CLAUDE_CONFIG_DIR so the first
+    // `claude plugin marketplace add` has a directory to write into.
+    mkdirSync(CLAUDE_CONFIG_DIR, { recursive: true });
+    // Task 583 — seed the brand-scoped permissions block so claude.ai/code
+    // sessions short-circuit Stage 1 of the local matcher and never fall
+    // through to the Anthropic remote auto-classifier (which routes Agent
+    // dispatch to `ask` and surfaces a prompt no unattended operator clicks).
+    const permissionsSeed = seedBypassPermissionsSettings(CLAUDE_CONFIG_DIR);
+    logFile(`[install-permissions] action=${permissionsSeed.action} path=${permissionsSeed.path}`);
+    const marketplaceList = spawnSync("claude", ["plugin", "marketplace", "list"], { stdio: "pipe", encoding: "utf-8", env: claudePluginEnv() });
+    if (marketplaceList.stderr)
+        process.stderr.write(marketplaceList.stderr);
+    const listed = marketplaceList.stdout ?? "";
+    // 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 CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
+            continue;
+        }
+        const add = spawnSync("claude", ["plugin", "marketplace", "add", slug], { stdio: "pipe", encoding: "utf-8", timeout: 60_000, env: claudePluginEnv() });
+        if (add.status === 0) {
+            logFile(`[plugin-marketplace] added ${slug} idempotent=false CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
+        }
+        else {
+            const stderrShort = (add.stderr ?? "").split("\n")[0]?.slice(0, 200) ?? "";
+            logFile(`[plugin-marketplace] ERROR add ${slug} exit=${add.status} stderr=${JSON.stringify(stderrShort)} CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
+        }
+    }
+    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", env: claudePluginEnv() });
+    if (pluginList.stdout?.includes("playwright")) {
+        console.log("  Removing Playwright plugin (replaced by programmatic CDP server)...");
+        spawnSync("claude", ["plugin", "uninstall", "playwright"], { stdio: "inherit", env: claudePluginEnv() });
+    }
+    // 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;
+}
+/**
+ * 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: 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; 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 });
+        // Start Neo4j under brew's launchd supervision. Linux path starts the
+        // service via systemd a few lines below; without this start the darwin
+        // brand server binds successfully but every Cypher write fails with
+        // "Failed to connect to server" because nothing is listening on 7687.
+        // `brew services start` is idempotent — if already running it no-ops,
+        // and the LaunchAgent persists across reboots.
+        const brewStart = spawnSync("brew", ["services", "start", "neo4j"], { stdio: "inherit" });
+        if (brewStart.status !== 0) {
+            throw new Error(`brew services start neo4j failed (exit ${brewStart.status}) — Neo4j must be running before the brand server starts or all graph writes will fail`);
+        }
+        console.log("  Neo4j installed and started via Homebrew launchd. 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.");
+}
+/**
+ * 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 mode the kept-active path 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
+ * 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.
+ *
+ * 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 established that state remediation must
+    // run every install 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.
+    // Older Neo4j 5.x templates ship a SECOND commented occurrence of these
+    // keys in the "Other Neo4j system properties" section. An in-place
+    // `sed s|^#?key=.*|key=value|` matches both and writes duplicate active
+    // lines; the 5.26.26 parser turns that into a fatal startup error.
+    // Delete-all-then-append guarantees exactly one active line per key
+    // regardless of how many commented occurrences the template ships.
+    const confPath = `${confDir}/neo4j.conf`;
+    const confKeys = [
+        ["server.bolt.listen_address", `:${NEO4J_PORT}`],
+        ["server.http.listen_address", `:${httpPort}`],
+        ["server.directories.data", `${dataDir}/data`],
+        ["server.directories.logs", logDir],
+        ["server.directories.plugins", `${dataDir}/plugins`],
+        ["server.directories.import", `${dataDir}/import`],
+    ];
+    for (const [key, value] of confKeys) {
+        const keyRe = key.replace(/\./g, "\\.");
+        console.log("  [privileged] sed -i (delete)");
+        shell("sed", ["-i", `/^#\\?${keyRe}=/d`, confPath], { sudo: true });
+        console.log("  [privileged] echo >>");
+        shell("sh", ["-c", `echo '${key}=${value}' >> ${confPath}`], { sudo: true });
+    }
+    // Verify exactly one active line per key. Any n>1 aborts the install
+    // BEFORE the systemd unit is written. n==0 means the append failed.
+    const activeCounts = [];
+    for (const [key] of confKeys) {
+        const r = spawnSync("sudo", ["grep", "-c", `^${key}=`, confPath], { stdio: "pipe" });
+        const n = parseInt((r.stdout?.toString() ?? "0").trim(), 10) || 0;
+        activeCounts.push(`${key}:${n}`);
+        if (n !== 1) {
+            const msg = `[neo4j-conf] FATAL ${key} active_count=${n}`;
+            console.error(`  ${msg}`);
+            logFile(`  ${msg}`);
+            throw new Error(msg);
+        }
+    }
+    const summary = `[neo4j-conf] keys_active=${activeCounts.join(",")}`;
+    console.log(`  ${summary}`);
+    logFile(`  ${summary}`);
+    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",
+        });
+    }
+    // ============================================================================
+    // 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 });
+    // 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 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.
+        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);
+}
+// 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` and `cloudflared tunnel route dns` are not
+        // invoked by the installer on darwin — public reach is operator-driven
+        // post-install (`cloudflared tunnel login` + follow-up tooling). The brew
+        // install puts the binary on PATH so the operator can opt in later.
+        logFile(`  [create-maxy] darwin-cloudflare-skip=true reason="Mac laptop — no public hostname provisioned at install time"`);
+        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
+ *. 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}`);
+}
+// 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); 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");
+    // users.json lives at <persistentDir>/users.json. Writers (paths.ts,
+    // admin-add, set-pin, seed-neo4j.sh) target the persistent file directly —
+    // see comment in platform/ui/app/lib/paths.ts.
+    const persistentUsersFile = join(persistentDir, "users.json");
+    // Claude Code OAuth credentials live at
+    // `${persistDir}/.claude/.credentials.json`. The brand main service's
+    // `claude` SDK subprocess and admin server read from there via the
+    // Environment=CLAUDE_CONFIG_DIR= block in port-resolution.ts. Fresh
+    // installs prompt the operator to run `claude /login`.
+    const persistentClaudeDir = join(persistentDir, ".claude");
+    mkdirSync(persistentClaudeDir, { recursive: true });
+    // pre-populate the brand `.claude.json` so the manager's
+    // PTY-spawned `claude --verbose --remote-control` boots straight into the
+    // session URL without stopping at the first-run theme picker or the
+    // workspace-trust dialog. Both prompts ate the manager's 30 s url-capture
+    // window on 0.1.6 / 0.1.8 installs (Pi 192.168.88.16 verified). The two
+    // markers required are:
+    //   - hasCompletedOnboarding: true       (suppresses theme picker)
+    //   - projects[$HOME].hasTrustDialogAccepted: true
+    // Existing fields (firstStartTime, oauthAccount, migrationVersion, …) are
+    // preserved so a brand re-install does not clobber state written by claude
+    // during the previous run.
+    const claudeStateFile = join(persistentClaudeDir, ".claude.json");
+    const homeWorkspace = process.env.HOME ?? "/root";
+    let claudeState = {};
+    if (existsSync(claudeStateFile)) {
+        try {
+            claudeState = JSON.parse(readFileSync(claudeStateFile, "utf-8"));
+        }
+        catch {
+            claudeState = {};
+        }
+    }
+    claudeState.hasCompletedOnboarding = true;
+    claudeState.theme = claudeState.theme ?? "auto";
+    const projects = (claudeState.projects ?? {});
+    const homeEntry = projects[homeWorkspace] ?? {};
+    homeEntry.hasTrustDialogAccepted = true;
+    projects[homeWorkspace] = homeEntry;
+    claudeState.projects = projects;
+    writeFileSync(claudeStateFile, JSON.stringify(claudeState, null, 2) + "\n", { mode: 0o600 });
+    console.log(`  [install] claude-state primed: ${claudeStateFile} hasCompletedOnboarding=true trustedWorkspace=${homeWorkspace}`);
+    // Brand isolation: installer does not read ~/.maxy/, ~/.cloudflared/, or
+    // ~/.cloudflare/ on non-default brands. These are peer-brand or
+    // shared-singleton paths.
+    // Stop the running service before wiping directories (upgrade path).
+    // The server holds open files in platform/ — rmSync fails with ENOTEMPTY if it's running.
+    // 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"]);
+        }
+    }
+    // User data lives at {installDir}/data/ — outside the platform/ wipe zone.
+    // Install path creates this fresh; runtime writers populate it on demand.
+    mkdirSync(join(INSTALL_DIR, "data"), { recursive: true });
+    // 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.");
+    }
+    // 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 line below observes the row count + userId prefixes so a
+    // future regression is grep-detectable in the install log without any
+    // runtime change.
+    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)");
+    }
+    // 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); 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
+    const versionMarkerPath = join(configDir, `.${BRAND.hostname}-version`);
+    writeFileSync(versionMarkerPath, PKG_VERSION, "utf-8");
+    console.log(`  [install] version-marker written path=${versionMarkerPath} version=${PKG_VERSION}`);
+    console.log(`  Deployed to ${INSTALL_DIR}`);
+}
+// register the local + external Claude Code plugins after the
+// payload is on disk. The bundler stamps `.claude-plugin/marketplace.json`
+// at each plugin-tree root (platform/plugins/, premium-plugins/real-agent/
+// plugins/, premium-plugins/) so this function discovers them generically
+// from the install directory rather than hardcoding names.
+//
+// Idempotent on every step: marketplace add is skipped when already in
+// `marketplace list`; `plugin install` is skipped when the plugin is
+// already in `plugin list` (matched by `<name>@<marketplace>` or by name
+// alone). One `[plugin-install] <name>@<src>
+// idempotent=<bool>` log line per attempt; failures log
+// `[plugin-install] ERROR <name>@<src> exit=<n> stderr=<short>` and do
+// NOT abort — one plugin failing must not block the rest, mirroring the
+// marketplace-add behaviour at src/index.ts:1018-1019.
+function registerLocalAndExternalPlugins() {
+    console.log("  Registering local + external Claude Code plugins...");
+    const localTrees = [];
+    // The three known marketplace.json locations the bundler emits. Missing
+    // ones are silently skipped (e.g. a brand that ships no premium plugins).
+    const candidates = [
+        join(INSTALL_DIR, "platform", "plugins"),
+        join(INSTALL_DIR, "premium-plugins", "real-agent", "plugins"),
+        join(INSTALL_DIR, "premium-plugins"),
+    ];
+    for (const dir of candidates) {
+        const mkPath = join(dir, ".claude-plugin", "marketplace.json");
+        if (!existsSync(mkPath))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(mkPath, "utf-8"));
+            if (typeof parsed.name === "string" && parsed.name.length > 0) {
+                localTrees.push({ name: parsed.name, dir });
+            }
+            else {
+                logFile(`[plugin-marketplace] ERROR malformed marketplace at ${mkPath} reason=no-name`);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logFile(`[plugin-marketplace] ERROR parse ${mkPath} error=${JSON.stringify(msg.slice(0, 200))}`);
+        }
+    }
+    // Add each local marketplace. Idempotence via `marketplace list` grep.
+    // every `claude plugin …` call carries CLAUDE_CONFIG_DIR so
+    // marketplaces register into the per-brand config dir that the runtime
+    // session-manager unit reads from.
+    const mkList = spawnSync("claude", ["plugin", "marketplace", "list"], { stdio: "pipe", encoding: "utf-8", env: claudePluginEnv() });
+    const mkListed = mkList.stdout ?? "";
+    for (const { name, dir } of localTrees) {
+        if (mkListed.includes(name)) {
+            logFile(`[plugin-marketplace] added ${name} idempotent=true CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
+            continue;
+        }
+        const add = spawnSync("claude", ["plugin", "marketplace", "add", dir], { stdio: "pipe", encoding: "utf-8", timeout: 60_000, env: claudePluginEnv() });
+        if (add.status === 0) {
+            logFile(`[plugin-marketplace] added ${name} source=${dir} idempotent=false CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
+        }
+        else {
+            const stderrShort = (add.stderr ?? "").split("\n")[0]?.slice(0, 200) ?? "";
+            logFile(`[plugin-marketplace] ERROR add ${name} source=${dir} exit=${add.status} stderr=${JSON.stringify(stderrShort)} CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
+        }
+    }
+    // Build the desired plugin list = (every local marketplace's plugins) +
+    // (brand.json#externalPlugins). The local entries' `marketplace` field
+    // matches the marketplace.json `name`; the external entries declare
+    // their own.
+    const desired = [];
+    for (const { name: mkName, dir } of localTrees) {
+        const mkPath = join(dir, ".claude-plugin", "marketplace.json");
+        try {
+            const parsed = JSON.parse(readFileSync(mkPath, "utf-8"));
+            for (const p of parsed.plugins ?? []) {
+                if (typeof p.name === "string" && p.name.length > 0) {
+                    desired.push({ name: p.name, marketplace: mkName });
+                }
+            }
+        }
+        catch {
+            // Already logged above.
+        }
+    }
+    let externals = [];
+    try {
+        externals = parseExternalPlugins(BRAND.externalPlugins);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logFile(`[plugin-install] ERROR brand.externalPlugins parse error=${JSON.stringify(msg.slice(0, 200))}`);
+    }
+    desired.push(...externals);
+    // The directory-source marketplaces are exactly the local trees discovered
+    // from on-disk marketplace.json above. Remote marketplaces (the Anthropic
+    // ones, GitHub externals) are never in this set, so they keep version-pinned
+    // idempotence. (Task 643.)
+    const directorySourceMarketplaces = new Set(localTrees.map(t => t.name));
+    // Snapshot what's installed to compute the install set.
+    const pluginList = spawnSync("claude", ["plugin", "list"], { stdio: "pipe", encoding: "utf-8", env: claudePluginEnv() });
+    const installed = parsePluginList(pluginList.stdout ?? "");
+    const { toInstall, toResync, alreadyInstalled } = computeInstallActions(desired, installed, directorySourceMarketplaces);
+    for (const ref of alreadyInstalled) {
+        logFile(`[plugin-install] ${ref.name}@${ref.marketplace} idempotent=true`);
+    }
+    // Single source of truth for the install invocation, shared by the resync
+    // and fresh-install loops so a future flag/timeout/scope change cannot drift
+    // between them.
+    const pluginInstall = (ref) => spawnSync("claude", ["plugin", "install", `${ref.name}@${ref.marketplace}`, "--scope", "user"], { stdio: "pipe", encoding: "utf-8", timeout: 120_000, env: claudePluginEnv() });
+    // Resync directory-source plugins (Task 643). A directory marketplace
+    // overwrites its tree in place on upgrade with no version bump, so the
+    // runtime cache snapshot the session loads from (installed_plugins.json
+    // `installPath`) freezes at first-install time — `plugin install` and
+    // `plugin update` both short-circuit on the pinned version and never
+    // re-copy. Uninstall then install is the only sequence that rebuilds the
+    // snapshot from the live tree; `install` reads the directory source live.
+    // The uninstall+install pair is not atomic: a failed reinstall leaves the
+    // plugin deregistered, surfaced by the ERROR line below — hardening tracked
+    // in Task 645.
+    for (const ref of toResync) {
+        spawnSync("claude", ["plugin", "uninstall", `${ref.name}@${ref.marketplace}`, "--scope", "user"], { stdio: "pipe", encoding: "utf-8", timeout: 120_000, env: claudePluginEnv() });
+        const install = pluginInstall(ref);
+        if (install.status === 0) {
+            logFile(`[plugin-install] recache ${ref.name}@${ref.marketplace}`);
+        }
+        else {
+            const stderrShort = (install.stderr ?? "").split("\n")[0]?.slice(0, 200) ?? "";
+            logFile(`[plugin-install] ERROR recache ${ref.name}@${ref.marketplace} exit=${install.status} stderr=${JSON.stringify(stderrShort)}`);
+        }
+    }
+    for (const ref of toInstall) {
+        const install = pluginInstall(ref);
+        if (install.status === 0) {
+            logFile(`[plugin-install] ${ref.name}@${ref.marketplace} idempotent=false`);
+        }
+        else {
+            const stderrShort = (install.stderr ?? "").split("\n")[0]?.slice(0, 200) ?? "";
+            logFile(`[plugin-install] ERROR ${ref.name}@${ref.marketplace} exit=${install.status} stderr=${JSON.stringify(stderrShort)}`);
+        }
+    }
+    // Cache-vs-live audit (Task 643). Prove the per-plugin cache snapshot the
+    // runtime loads from now matches the live tree, so drift is a logged
+    // post-condition rather than a "no such skill" surprise in a later session.
+    // Read the authoritative load path from installed_plugins.json
+    // (`installPath`) rather than reconstructing the cache path from a pinned
+    // version string. Warn-only: a count mismatch is surfaced, not fatal — a
+    // benign skill directory without a SKILL.md must not abort the install.
+    const countSkills = (skillsDir) => {
+        if (!existsSync(skillsDir))
+            return 0;
+        let n = 0;
+        for (const entry of readdirSync(skillsDir)) {
+            if (existsSync(join(skillsDir, entry, "SKILL.md")))
+                n++;
+        }
+        return n;
+    };
+    let installedPluginsMap = {};
+    try {
+        const ipPath = join(CLAUDE_CONFIG_DIR, "plugins", "installed_plugins.json");
+        const parsed = JSON.parse(readFileSync(ipPath, "utf-8"));
+        installedPluginsMap = parsed.plugins ?? {};
+    }
+    catch {
+        // No readable installed_plugins.json — audit reports cache-skills=0; any
+        // failed install above already logged a recache/install ERROR line.
+    }
+    // `treeDirByMarketplace` is keyed on the directory-source marketplace names
+    // (= `directorySourceMarketplaces`), so a present tree dir is itself the
+    // directory-source test — no separate Set lookup needed.
+    const treeDirByMarketplace = new Map(localTrees.map(t => [t.name, t.dir]));
+    for (const ref of desired) {
+        const treeDir = treeDirByMarketplace.get(ref.marketplace);
+        if (!treeDir)
+            continue;
+        const liveSkills = countSkills(join(treeDir, ref.name, "skills"));
+        // The resync installs at `--scope user`, so audit that scope's snapshot —
+        // not whichever entry happens to be first, since a host may also carry a
+        // stale project-scope entry for the same plugin.
+        const entries = installedPluginsMap[`${ref.name}@${ref.marketplace}`] ?? [];
+        const installPath = (entries.find(e => e.scope === "user") ?? entries[0])?.installPath;
+        const cacheSkills = installPath ? countSkills(join(installPath, "skills")) : 0;
+        logFile(`[plugin-install] audit ${ref.name}@${ref.marketplace} live-skills=${liveSkills} cache-skills=${cacheSkills}`);
+        if (liveSkills !== cacheSkills) {
+            logFile(`[plugin-install] WARN cache-drift ${ref.name}@${ref.marketplace} live-skills=${liveSkills} cache-skills=${cacheSkills}`);
+        }
+    }
+    // post-install assertion. The per-brand CLAUDE_CONFIG_DIR is the
+    // only surface the runtime session-manager reads from; if any expected
+    // marketplace is missing under .claude/plugins/marketplaces/, the operator
+    // will hit "Unknown skill: onboarding" at step 6 of the bring-up. Fail the
+    // install loudly here rather than ship a broken PTY.
+    //
+    // Expected set = 3 Anthropic marketplace names (from the constant in
+    // installClaudeCode) + every parsed localTrees name. Hardcoding the
+    // Anthropic names keeps the assertion independent of `MARKETPLACES` scope.
+    const expectedMarketplaces = new Set([
+        "claude-plugins-official",
+        "knowledge-work-plugins",
+        "claude-for-financial-services",
+        ...localTrees.map(t => t.name),
+    ]);
+    // `claude plugin marketplace list` is the authoritative source.
+    // The `.claude/plugins/marketplaces/` directory only contains subdirs for
+    // remote (git-cloned) marketplaces — local-source marketplaces registered
+    // via `claude plugin marketplace add <directory-path>` live in user
+    // settings and are visible only through `marketplace list`. Parsing the
+    // CLI output covers both. The CLI emits each entry as two lines: the
+    // leader-glyph name (`  ❯ <name>`) followed by `    Source: …`, so the
+    // name is on its own line — anchor on `❯` and require the following line
+    // (after blanks) to start with `Source:` to confirm it is a marketplace
+    // header, not a stray glyph in some other CLI panel.
+    const listResult = spawnSync("claude", ["plugin", "marketplace", "list"], { stdio: "pipe", encoding: "utf-8", env: claudePluginEnv() });
+    const listStdout = listResult.stdout ?? "";
+    const listStderr = listResult.stderr ?? "";
+    const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*[A-Za-z]/g, "");
+    const parseMarketplaceList = (raw) => {
+        const lines = stripAnsi(raw).split("\n");
+        const names = [];
+        for (let i = 0; i < lines.length; i++) {
+            const nameMatch = lines[i].match(/^\s*❯\s+([A-Za-z0-9._-]+)\s*$/);
+            if (!nameMatch)
+                continue;
+            let j = i + 1;
+            while (j < lines.length && lines[j].trim() === "")
+                j++;
+            if (j < lines.length && /^\s*Source:/.test(lines[j])) {
+                names.push(nameMatch[1]);
+            }
+        }
+        return names;
+    };
+    const actualMarketplaces = parseMarketplaceList(listStdout);
+    if (listResult.error || listResult.status !== 0 || actualMarketplaces.length === 0) {
+        const errMsg = listResult.error ? listResult.error.message : `exit=${listResult.status}`;
+        throw new Error(`Plugin registration produced no marketplaces — \`claude plugin marketplace list\` returned no parseable entries (${errMsg}). stdout=${JSON.stringify(listStdout)} stderr=${JSON.stringify(listStderr.split("\n")[0] ?? "")}. Check setup.log for [plugin-marketplace] ERROR lines.`);
+    }
+    const missing = [...expectedMarketplaces].filter(m => !actualMarketplaces.includes(m));
+    if (missing.length > 0) {
+        logFile(`[plugin-marketplace] assertion-fail expected=${JSON.stringify([...expectedMarketplaces])} actual=${JSON.stringify(actualMarketplaces)} missing=${JSON.stringify(missing)} CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
+        throw new Error(`Plugin registration incomplete: expected marketplaces ${JSON.stringify([...expectedMarketplaces])} but \`claude plugin marketplace list\` returned ${JSON.stringify(actualMarketplaces)}. Missing: ${JSON.stringify(missing)}. Check setup.log for [plugin-marketplace] ERROR lines.`);
+    }
+    logFile(`[plugin-marketplace] assertion-source=claude-plugin-marketplace-list count=${actualMarketplaces.length} marketplaces=${JSON.stringify(actualMarketplaces)} CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
+    // Task 583 — post-install assertion that the brand-scoped permissions
+    // block survived install. Warn-only: a missing block does not abort the
+    // install (consistent with the marketplace ERROR path that logs and
+    // continues per-entry), but surfaces in setup.log for diagnosis.
+    const permissionsAssert = assertBypassPermissionsSeed(CLAUDE_CONFIG_DIR);
+    logFile(`[install-permissions] brand-settings=${permissionsAssert.status} path=${permissionsAssert.path}`);
+}
+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, @whiskeysockets/baileys, zod, proper-lockfile) 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);
+    // (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);
+    }
+    // Premium-plugin MCP servers (e.g. real-agent/loop) ship dist/ + package.json
+    // in the payload but no node_modules — npm pack strips them, same reason as
+    // server/. Discover every <installDir>/premium-plugins/<bundle>/plugins/<plugin>/mcp
+    // and install --omit=dev there. dirs=0 in the summary line is itself a signal
+    // when a brand ships premium plugins but the discovery glob is broken.
+    const premiumMcpDirs = findPremiumMcpDirs(INSTALL_DIR);
+    console.log(`  [install] premium-mcp-install dirs=${premiumMcpDirs.length}`);
+    for (const mcpDir of premiumMcpDirs) {
+        const mcpNodeModules = join(mcpDir, "node_modules");
+        if (existsSync(mcpNodeModules)) {
+            console.log(`  Wiping previous ${mcpDir}/node_modules for a clean reinstall...`);
+            rmSync(mcpNodeModules, { recursive: true, force: true });
+        }
+        console.log(`  Installing premium plugin MCP dependencies (${mcpDir})...`);
+        shellRetry("npm", ["install", "--omit=dev", ...NPM_NET_FLAGS], { cwd: mcpDir }, 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: emit event=rfb-connected and
+    // event=rfb-error to the operator-grep lifecycle endpoint so
+    // server.log shows the noVNC outcome alongside [device-url:click]
+    // / [http] / [websockify]. Same-origin POST works whether the
+    // iframe is parented by the React VNC viewer or by vnc-popout.html.
+    function reportVncIframeEvent(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;
+        reportVncIframeEvent('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'));
+        reportVncIframeEvent('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...");
+    // Account-side setup runs first: creates the account dir, writes the
+    // Claude Code project settings (hooks only — no permissions.allow),
+    // installs specialist templates, seeds account.json. Then seed-neo4j.sh
+    // applies the schema and MERGEs the root :LocalBusiness / owner
+    // :AdminUser nodes. setup-account.sh has no Neo4j env dependency;
+    // seed-neo4j.sh hard-exits without NEO4J_URI, so we derive the URI +
+    // password (a missing password file is a hard error here — the
+    // upstream ensureNeo4jPassword() would have thrown if it couldn't
+    // reach the brand's Neo4j).
+    const setupScript = join(INSTALL_DIR, "platform/scripts/setup-account.sh");
+    if (existsSync(setupScript)) {
+        shell("bash", [setupScript], { cwd: INSTALL_DIR });
+    }
+    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 });
+    }
+    // Task 165 — register every bundled specialist subagent at
+    // $CLAUDE_CONFIG_DIR/agents/<name>.md. Claude Code's `--agent <name>`
+    // discovery only resolves under this path; without these symlinks,
+    // every `--agent database-operator` etc. silently runs as the admin
+    // agent on admin IDENTITY/SOUL scaffolding. Symlinks (not copies) so
+    // a `npx -y @rubytech/create-maxy-code` upgrade picks up template
+    // changes without a second seed run.
+    registerSpecialistAgents();
+    // install-time defaults. Stamp `account.json` with the
+    // brand's default plugin set + default outputStyle / thinkingView, and
+    // write a minimal admin SOUL.md. The agent boots into a working state
+    // with no onboarding state machine; the operator builds personality up
+    // through use. The graph-write gate blocks user-domain writes
+    // until AdminUser + LocalBusiness/personal-profile Person exist, so the
+    // persona is elicited the first time the operator triggers a write.
+    const accountId = resolveInstallAccountId();
+    if (accountId) {
+        writeInstallDefaults(accountId);
+    }
+    else {
+        console.log("  [install-defaults] SKIPPED reason=no-account-discovered");
+    }
+}
+function writeInstallDefaults(accountId) {
+    const accountDir = join(INSTALL_DIR, "data/accounts", accountId);
+    const accountJsonPath = join(accountDir, "account.json");
+    const enabledPlugins = BRAND.plugins?.defaultEnabled ?? [];
+    let config = {};
+    if (existsSync(accountJsonPath)) {
+        try {
+            config = JSON.parse(readFileSync(accountJsonPath, "utf-8"));
+        }
+        catch (err) {
+            console.error(`  [install-defaults] account.json unreadable at ${accountJsonPath}: ${err.message}`);
+            logFile(`  [install-defaults] account.json unreadable: ${err.message}`);
+            return;
+        }
+    }
+    config.enabledPlugins = enabledPlugins;
+    config.outputStyle = "default";
+    config.thinkingView = "default";
+    if (TIER_FLAG) {
+        config = applyTierToAccountConfig(config, TIER_FLAG);
+    }
+    writeFileSync(accountJsonPath, JSON.stringify(config, null, 2) + "\n");
+    console.log(`  [install-defaults] account-json plugins=${enabledPlugins.length} outputStyle=default thinkingView=default`);
+    logFile(`  [install-defaults] account-json plugins=${enabledPlugins.length} outputStyle=default thinkingView=default`);
+    if (TIER_FLAG) {
+        const tierLine = `  [install-defaults] tier=${TIER_FLAG} mode=personal source=cli-flag`;
+        console.log(tierLine);
+        logFile(tierLine);
+    }
+    // Admin SOUL.md is user-controlled personalisation: create it from the
+    // bundled template (with ${PRODUCT_NAME} substituted) on a fresh install,
+    // and never overwrite it once it exists. The operator builds the agent's
+    // personality up through use, so an existing SOUL must survive every
+    // upgrade. Task 511: an unconditional write here reset SOUL to the 7-byte
+    // template on every full install. Mirrors the public SOUL guard below and
+    // the create-if-missing branch in setup-account.sh.
+    const soulPath = join(accountDir, "agents/admin/SOUL.md");
+    mkdirSync(dirname(soulPath), { recursive: true });
+    if (existsSync(soulPath)) {
+        const preservedBytes = statSync(soulPath).size;
+        console.log(`  [install-defaults] soul-md preserved path=${soulPath} bytes=${preservedBytes}`);
+        logFile(`  [install-defaults] soul-md preserved path=${soulPath} bytes=${preservedBytes}`);
+    }
+    else {
+        const adminSoulTemplate = join(INSTALL_DIR, "platform/templates/agents/admin/SOUL.md");
+        let soulContent;
+        try {
+            soulContent = readFileSync(adminSoulTemplate, "utf-8");
+        }
+        catch (err) {
+            console.error(`  [install-defaults] admin-soul template missing at ${adminSoulTemplate}: ${err.message}`);
+            logFile(`  [install-defaults] admin-soul template missing: ${err.message}`);
+            return;
+        }
+        soulContent = soulContent.replace(/\$\{PRODUCT_NAME\}/g, BRAND.productName);
+        writeFileSync(soulPath, soulContent);
+        console.log(`  [install-defaults] soul-md created path=${soulPath} bytes=${soulContent.length}`);
+        logFile(`  [install-defaults] soul-md created path=${soulPath} bytes=${soulContent.length}`);
+    }
+    // Public agent IDENTITY.md — the only template-seeded public file, always
+    // overwritten (Rubytech-controlled toolless directive). Per Task 618/623,
+    // each public agent's SOUL.md, KNOWLEDGE.md, and config.json are authored
+    // client-side when the operator creates the agent through the admin UI;
+    // they are not seeded from templates at install time. A public spawn for an
+    // un-authored agent refuses as a dud (soul-empty / knowledge-missing), which
+    // is the intended loud signal — do not re-introduce template SOUL/config
+    // copies here (commit 82c5658d6 removed the template files).
+    const publicDir = join(accountDir, "agents/public");
+    mkdirSync(publicDir, { recursive: true });
+    const publicTemplatesDir = join(INSTALL_DIR, "platform/templates/agents/public");
+    const publicIdentityDst = join(publicDir, "IDENTITY.md");
+    cpSync(join(publicTemplatesDir, "IDENTITY.md"), publicIdentityDst);
+    console.log(`  [install-defaults] public-identity path=${publicIdentityDst}`);
+    logFile(`  [install-defaults] public-identity path=${publicIdentityDst}`);
+}
+/**
+ * Commercial-mode entitlement delivery (Task 240). Writes the decoded payload
+ * bytes verbatim to ~/<BRAND.configDir>/entitlement.json. Signature and shape
+ * validation happen at the verifier at session start (entitlement lib); the
+ * installer is a dumb delivery channel — a malformed payload that survived
+ * --entitlement-base64 parsing will be caught there and degrade the install
+ * to anonymous-fallback, which is the correct loud-fail per doctrine.
+ */
+function writeEntitlementFromFlag(payload) {
+    const target = entitlementPath(process.env.HOME ?? "/root", BRAND.configDir);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, payload);
+    const line = `  [install-defaults] entitlement-delivered bytes=${payload.length} path=${target} source=cli-flag`;
+    console.log(line);
+    logFile(line);
+}
+// Task 394 — premium-bundle agents register through the native Claude Code
+// subagent registry via `.claude-plugin/plugin.json` manifests emitted by
+// scripts/generate-plugin-manifests.mjs at bundle time, not through a
+// parallel symlink channel. This function still wires the bundled platform
+// specialists (database-operator, project-manager, …) under
+// platform/templates/specialists/agents/, which are not part of a
+// registered plugin and rely on $CLAUDE_CONFIG_DIR/agents/ resolution.
+function registerSpecialistAgents() {
+    try {
+        registerSpecialistAgentsAt(join(INSTALL_DIR, "platform/templates/specialists/agents"), join(CLAUDE_CONFIG_DIR, "agents"), (line) => { console.log(line); logFile(line); });
+    }
+    catch (err) {
+        if (err instanceof SpecialistSymlinkCollision) {
+            console.error(`Setup failed: ${err.message}`);
+            console.error(`  Remove the file and re-run.`);
+            process.exit(1);
+        }
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Account discovery (shared by installService + the post-install summary)
+//
+// `installService` stamps `Environment=ACCOUNT_ID=` into the brand
+// systemd unit so the writeNodeWithEdges gate has a non-undefined identity to
+// compare against. Pulled from `INSTALL_DIR/data/accounts/<uuid>/account.json`
+// written by setup-account.sh during setupAccount(). One reader, one shape, one
+// source of truth.
+//
+// retired the installer's cron registration — `resolveInstallAccountId`
+// kept its second consumer (installService) and is referenced again at print
+// time for the post-install banner.
+// ---------------------------------------------------------------------------
+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 "";
+}
+// 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 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.
+// 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).
+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}`;
+}
+// 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: brew-resolved node path,
+// dedicated Neo4j on a non-default port. Falls back to /usr/local/bin/node
+// (homebrew Intel + manual Apple-silicon installs) 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 });
+    // Mirror the Linux brand systemd unit's `Environment=` lines into .env.
+    // Linux stamps every var explicitly on the unit; darwin has no systemd
+    // EnvironmentFile primitive, so the wrapper sources .env before exec'ing
+    // node. Any var the boot path or per-request handlers require (PORT,
+    // MAXY_UI_INTERNAL_PORT, CLAUDE_SESSION_MANAGER_PORT, ACCOUNT_ID,
+    // MAXY_PLATFORM_ROOT, NEO4J_URI, CLAUDE_CONFIG_DIR, NODE_ENV) must be
+    // written here or the server hard-fails — boot-throw for module-init
+    // consumers, per-request 500s for handlers like /api/admin/claude-sessions*
+    // that requirePortEnv lazily on the manager port.
+    // VNC/X11 vars (DISPLAY, RFB_PORT, WEBSOCKIFY_PORT, CDP_PORT) are Pi-only
+    // and excluded — darwin runs no kiosk display stack.
+    //
+    // Darwin collapses the two-process model: Linux runs a separate
+    // `maxy-edge.service` on 0.0.0.0:PORT that reverse-proxies into the brand
+    // server on 127.0.0.1:MAXY_UI_INTERNAL_PORT, with edge surviving brand
+    // restarts so the browser WebSocket stays connected. Edge also owns the
+    // VNC websockify stack, which darwin doesn't have. On darwin the brand
+    // server binds the public port directly:
+    //   HOSTNAME=0.0.0.0  →  bind all interfaces (LAN reachable)
+    //   MAXY_UI_INTERNAL_PORT=PORT  →  same port, no +1 split
+    // Tradeoff: no zero-downtime restarts; a brand restart drops live
+    // websockets. Acceptable on a single-operator dev Mac.
+    const installAccountId = resolveInstallAccountId();
+    if (!installAccountId) {
+        throw new Error(`installServiceDarwin: no account discovered at ${INSTALL_DIR}/data/accounts/<uuid>/account.json — ` +
+            `setupAccount() (setup-account.sh) should have created one. Refusing to write .env ` +
+            `without ACCOUNT_ID; the boot validator would FATAL on every kickstart.`);
+    }
+    const envPath = join(persistDir, ".env");
+    try {
+        let envContent = "";
+        try {
+            envContent = readFileSync(envPath, "utf-8");
+        }
+        catch { /* first install */ }
+        for (const [key, value] of [
+            ["NODE_ENV", "production"],
+            ["DISPLAY_MODE", DISPLAY_MODE],
+            ["EMBED_MODEL", EMBED_MODEL],
+            ["EMBED_DIMENSIONS", String(EMBED_DIMS)],
+            ["NEO4J_URI", `bolt://localhost:${NEO4J_PORT}`],
+            ["PORT", String(PORT)],
+            ["MAXY_UI_INTERNAL_PORT", String(PORT)],
+            ["CLAUDE_SESSION_MANAGER_PORT", String(BRAND.claudeSessionManagerPort)],
+            ["ACCOUNT_ID", installAccountId],
+            ["MAXY_PLATFORM_ROOT", `${INSTALL_DIR}/platform`],
+            ["CLAUDE_CONFIG_DIR", `${persistDir}/.claude`],
+            ["HOSTNAME", "0.0.0.0"],
+            ["KEEP_ALIVE_TIMEOUT", "61000"],
+            // launchd hands the server a bare PATH (/usr/bin:/bin:/usr/sbin:/sbin)
+            // that excludes the two Homebrew prefixes the `claude` binary lives in
+            // under Apple Silicon and Intel. The wrapper sources this file with
+            // `set -a; . "$envPath"; set +a`, so `$PATH` expands at source-time
+            // against the bare launchd PATH and Homebrew prefixes get prepended for
+            // every spawned descendant (claude-session-manager, MCP plugin spawns,
+            // route-level spawn('claude', ...)). Task 386.
+            ["PATH", "/opt/homebrew/bin:/usr/local/bin:$PATH"],
+        ]) {
+            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}, MAXY_UI_INTERNAL_PORT=${PORT} (darwin-collapsed), CLAUDE_SESSION_MANAGER_PORT=${BRAND.claudeSessionManagerPort}, HOSTNAME=0.0.0.0, ACCOUNT_ID=${installAccountId.slice(0, 8)}…, CLAUDE_CONFIG_DIR=${persistDir}/.claude`);
+    }
+    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",
+        "# 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`);
+        logFile(`  [create-maxy] launchd-plist=${path} loaded=true`);
+    }
+    else {
+        const stderr = (bootstrap.stderr ?? "").trim();
+        console.error(`  [launchd] bootstrap returned ${bootstrap.status}: ${stderr}`);
+        logFile(`  [launchd] bootstrap returned ${bootstrap.status}: ${stderr}`);
+        logFile(`  [create-maxy] launchd-plist=${path} loaded=false exit=${bootstrap.status}`);
+        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}...`);
+    // 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}`;
+    // 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.
+    //
+    // 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. 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.
+    // 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;
+    // 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 (chromium Xtigervnc + websockify) reads
+    // `/proc/<pid>/cmdline` and applies a holder-specific argv anchor.
+    // covered chromium-only via `--user-data-dir=` 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. 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), so the empty-list fallback is safe — peer
+    // chromium will fall through to UNRELATED, matching earlier 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,
+    });
+    // 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);
+    // 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 — setup-account.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() (setup-account.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,
+        chromiumBin: RESOLVED_CHROMIUM_BIN,
+        accountId: installAccountId,
+    });
+    writeFileSync(join(serviceDir, BRAND.serviceName), serviceFile);
+    // (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,
+        brandPort: PORT,
+        maxyUiInternalPort: MAXY_UI_INTERNAL_PORT,
+        accountId: installAccountId,
+        cdpPort: CDP_PORT_BRAND,
+    });
+    writeFileSync(join(serviceDir, claudeSessionManagerUnitName), claudeSessionManagerUnit);
+    logFile(`  ${claudeSessionManagerUnitName}: CLAUDE_SESSION_MANAGER_PORT=${CLAUDE_SESSION_MANAGER_PORT_BRAND} MAXY_UI_INTERNAL_PORT=${MAXY_UI_INTERNAL_PORT}`);
+    // Task 250 — write the brand-agnostic `claude-ptys.slice` unit. Every
+    // brand's session manager drops its per-spawn scope units under this
+    // slice. Writing it once per install is idempotent (the content is
+    // identical across brands and across runs); subsequent brand installs
+    // re-stamp the same content. No service restart is needed — `daemon-reload`
+    // below picks it up.
+    const claudePtysSliceName = "claude-ptys.slice";
+    writeFileSync(join(serviceDir, claudePtysSliceName), buildClaudePtysSliceUnitFile());
+    logFile(`  ${claudePtysSliceName}: Task 250 slice for claude-session-*.scope cohort`);
+    // Task 602 — write the brand-agnostic `cloudflared.slice` unit. Every
+    // cloudflared-<brand>.scope spawned by resume-tunnel.sh drops under this
+    // slice. Writing once per install is idempotent; daemon-reload below picks it up.
+    const cloudflaredSliceName = "cloudflared.slice";
+    writeFileSync(join(serviceDir, cloudflaredSliceName), buildCloudflaredSliceUnitFile());
+    logFile(`  ${cloudflaredSliceName}: Task 602 slice for cloudflared-*.scope cohort`);
+    // Task 600 — per-brand RSS sampler: a long-running user service that
+    // periodically writes per-claude.exe RSS + aggregate RSS to disk.
+    // Named per-brand (BRAND.hostname prefix) so two brands on the same
+    // device each own their own sampler writing to their own log path.
+    const rssSamplerUnitName = `${BRAND.hostname}-rss-sampler.service`;
+    const rssSamplerScriptPath = resolve(INSTALL_DIR, "platform/scripts/rss-sampler.sh");
+    const rssSamplerLogPath = join(persistDir, "rss-sampler.log");
+    const rssSamplerUnit = `[Unit]
+Description=${BRAND.productName} RSS Sampler
+
+[Service]
+Type=simple
+ExecStart=/bin/bash ${rssSamplerScriptPath}
+Environment=LOG_PATH=${rssSamplerLogPath}
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+    writeFileSync(join(serviceDir, rssSamplerUnitName), rssSamplerUnit);
+    logFile(`  rss-sampler installed: ${rssSamplerUnitName} LOG_PATH=${rssSamplerLogPath}`);
+    // 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.
+    //
+    // 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.
+    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`);
+    }
+    // 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 */ }
+    // Task 504: persist the systemd journal so per-unit lifecycle events
+    // (SIGTERM/SIGKILL transitions, dependency-propagated stops, restart job
+    // records) survive reboots and remain greppable via `journalctl --user -u
+    // <brand>.service` after a restart loop quiets.
+    //
+    // Why a drop-in and not the Task-249 `mkdir /var/log/journal`: the directory
+    // heuristic only takes effect under journald's default `Storage=auto`. A
+    // base image (common on RPi to spare the SD card) that ships an explicit
+    // `Storage=volatile` overrides directory existence, so the bare mkdir is a
+    // no-op there — exactly the state observed on the realagent-code device. An
+    // explicit `Storage=persistent` drop-in wins regardless of the base default,
+    // and journald itself creates `/var/log/journal/<machine-id>` on restart, so
+    // the mkdir is no longer needed.
+    //
+    // journald is one system instance, so the drop-in is host-wide with a neutral
+    // filename — idempotent across brands and reinstalls. Restart journald only
+    // when the drop-in content actually changes, to avoid churning the system
+    // journal on every reinstall. Best-effort: a failure here warns, never aborts
+    // the install.
+    try {
+        const journaldDropinDir = "/etc/systemd/journald.conf.d";
+        const journaldDropinPath = `${journaldDropinDir}/10-maxy-persistent.conf`;
+        const desiredJournaldConf = "[Journal]\nStorage=persistent\n";
+        let journaldCurrent = "";
+        if (existsSync(journaldDropinPath)) {
+            try {
+                journaldCurrent = readFileSync(journaldDropinPath, "utf-8");
+            }
+            catch {
+                // Unreadable existing drop-in — treat as changed so we rewrite + restart.
+                journaldCurrent = "";
+            }
+        }
+        if (journaldCurrent === desiredJournaldConf) {
+            logFile(`  journald persistence: already active (${journaldDropinPath} matches Storage=persistent)`);
+        }
+        else {
+            const journaldTmpPath = "/tmp/10-maxy-persistent.conf";
+            writeFileSync(journaldTmpPath, desiredJournaldConf);
+            console.log("  [privileged] install journald Storage=persistent drop-in");
+            shell("mkdir", ["-p", journaldDropinDir], { sudo: true });
+            shell("cp", [journaldTmpPath, journaldDropinPath], { sudo: true });
+            spawnSync("rm", ["-f", journaldTmpPath]);
+            console.log("  [privileged] systemctl restart systemd-journald");
+            spawnSync("sudo", ["systemctl", "restart", "systemd-journald"], { stdio: "inherit", timeout: 15_000 });
+            logFile(`  journald persistence: enabled (wrote ${journaldDropinPath} Storage=persistent + restarted journald)`);
+        }
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to enable journald persistence: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Task 504: capture the initiator of a brand-service restart so the next
+    // recurrence of the restart loop is attributable to its source from
+    // device-retained evidence. The brand admin process logs only that it
+    // *received* SIGTERM (not the sender), and a JS signal handler cannot read
+    // si_pid. auditd is the device-side primitive that names the initiator:
+    //
+    //   - `kill` syscall with sig=15 (SIGTERM): names a process that sends
+    //     SIGTERM directly to the brand pid. For a systemd-managed stop the
+    //     sender is the user systemd manager itself, so this rule alone does NOT
+    //     name the upstream actor of a managed restart — but it does catch a
+    //     direct, non-systemd kill.
+    //   - `execve` of systemctl: names the pid/cgroup that drives a CLI restart
+    //     (`systemctl --user restart <unit>`), which is the upstream actor the
+    //     kill rule misses for the systemd-mediated path.
+    //   - Once auditd runs, systemd emits native SERVICE_START/SERVICE_STOP audit
+    //     records with no rule needed, covering a restart issued over raw D-Bus
+    //     (no systemctl binary, so the execve rule would miss it).
+    //
+    // Rules are deliberately narrow (SIGTERM + systemctl execve only) so audit
+    // write volume stays bounded on a low-power device; auditd's default log
+    // rotation bounds disk further. Everything here is best-effort: a box with no
+    // apt mirror, or a kernel without audit support, warns and the install still
+    // completes. Load via `augenrules --load` (merges rules.d into the running
+    // daemon without a disruptive auditd restart).
+    try {
+        console.log("  [privileged] apt-get install auditd");
+        shell("apt-get", ["install", "-y", "auditd"], { sudo: true, bestEffort: true });
+        const auditRulesPath = "/etc/audit/rules.d/90-maxy-restart-forensics.rules";
+        // Rule ordering matters: auditctl loads rules in file order, and a rule a
+        // kernel rejects (the arch=b32 kill rule on an arm64 kernel without 32-bit
+        // compat) must not sit ahead of rules that should load. So the b64 kill
+        // rule and the systemctl watch come first; the b32 kill rule (the one that
+        // may be rejected) comes last. The systemctl capture uses a file watch
+        // (`-w … -p x`), the idiomatic form for "audit execution of this binary" —
+        // it records the caller pid/cgroup and is arch-agnostic, avoiding the
+        // invalid `arch`+`path`+`perm` field mix.
+        const auditRules = [
+            "# Maxy restart-loop forensics (Task 504) — name the initiator of a",
+            "# brand-service restart on the next recurrence.",
+            "# SIGTERM sender (a0=target pid, a1=signal).",
+            "-a always,exit -F arch=b64 -S kill -F a1=15 -k maxy_sigterm",
+            "# systemctl execution — names the caller pid/cgroup of a CLI restart.",
+            "-w /usr/bin/systemctl -p x -k maxy_systemctl",
+            "# b32 kill sibling last: a 32-bit-compat caller is still captured, and a",
+            "# rejection on an arm64 kernel without compat cannot block the rules above.",
+            "-a always,exit -F arch=b32 -S kill -F a1=15 -k maxy_sigterm",
+            "",
+        ].join("\n");
+        const auditTmpPath = "/tmp/90-maxy-restart-forensics.rules";
+        writeFileSync(auditTmpPath, auditRules);
+        console.log("  [privileged] install auditd restart-forensics rules");
+        shell("mkdir", ["-p", "/etc/audit/rules.d"], { sudo: true, bestEffort: true });
+        shell("cp", [auditTmpPath, auditRulesPath], { sudo: true, bestEffort: true });
+        spawnSync("rm", ["-f", auditTmpPath]);
+        console.log("  [privileged] augenrules --load");
+        shell("augenrules", ["--load"], { sudo: true, bestEffort: true });
+        logFile(`  auditd restart forensics: rules at ${auditRulesPath} (keys maxy_sigterm, maxy_systemctl) — verify on device with \`ausearch -k maxy_sigterm\``);
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to install auditd restart forensics: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Reload and (re)start.
+    //
+    // 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" });
+    spawnSync("systemctl", ["--user", "enable", `${BRAND.hostname}-rss-sampler`], { 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.
+    // rss-sampler is independent — start last, failure is non-blocking.
+    spawnSync("systemctl", ["--user", "restart", edgeUnitShort], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "restart", claudeSessionManagerUnitShort], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "restart", unitName], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "restart", `${BRAND.hostname}-rss-sampler`], { stdio: "inherit" });
+    // Session manager runs in its own systemd user unit and can boot-fail silently
+    // (e.g. mcp-block-missing). The web server below comes up regardless, so the
+    // install terminal would otherwise report success while every API call 503s.
+    // Surface the boot failure on the trusted surface and refuse to declare success.
+    console.log("  Waiting for session manager...");
+    let sessionManagerActive = false;
+    for (let i = 0; i < 5; i++) {
+        const probe = spawnSync("systemctl", ["--user", "is-active", claudeSessionManagerUnitShort], { stdio: "pipe", encoding: "utf-8" });
+        if ((probe.stdout ?? "").trim() === "active") {
+            sessionManagerActive = true;
+            break;
+        }
+        spawnSync("sleep", ["2"]);
+    }
+    if (!sessionManagerActive) {
+        const status = spawnSync("systemctl", ["--user", "status", claudeSessionManagerUnitShort, "--no-pager", "-n", "20"], { stdio: "pipe", encoding: "utf-8" });
+        const statusOutput = `${status.stdout ?? ""}${status.stderr ?? ""}`.trimEnd();
+        console.error(statusOutput);
+        logFile(statusOutput);
+        const failureLine = `Session manager (${claudeSessionManagerUnitShort}) failed to start. See above for boot-failed reason.`;
+        console.error(failureLine);
+        logFile(failureLine);
+        process.exit(1);
+    }
+    // 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.`);
+    }
+    // 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);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Samba provisioning. Runs after installService() so SMB never
+// blocks the admin server starting; pure decisions live in samba-provision.ts.
+//
+// Four steps, each emitting one [install-invariant] samba-provision-<step>
+// marker:
+//   apt   — install the `samba` package
+//   conf  — write the brand stanza + LAN-only globals to /etc/samba/smb.conf
+//   user  — smbpasswd the install-owner Linux user; deferred at install time
+//           on fresh Pi installs (no plaintext PIN until the operator runs set-pin)
+//   units — systemctl enable --now smbd nmbd
+//
+// The platform's set-pin route handler closes the deferral loop by running
+// `smbpasswd -a -s <install-owner>` inline whenever the PIN is set or
+// rotated. Install owner is the Unix user the installer is running as —
+// `admin` on a Pi/Hetzner box, `neo` (etc.) on a self-hosted laptop. It is
+// persisted to `~/.<brand>/.install-owner` so every later read uses the same
+// value the installer wrote.
+// ---------------------------------------------------------------------------
+function emitSambaMarker(step, state) {
+    const line = formatSambaMarker(step, state);
+    console.log(`  ${line}`);
+    logFile(`  ${line}`);
+}
+function provisionSamba() {
+    if (!isLinux()) {
+        logFile(`  samba-provision skipped: platform=${process.platform}`);
+        return;
+    }
+    const brand = BRAND.hostname;
+    const sharePath = INSTALL_DIR;
+    // Install owner — the Unix user that owns this brand's install on the
+    // device. On a Pi/Hetzner box this is `admin`; on a self-hosted laptop it
+    // is the operator's Unix user (`neo` etc.). Persisted to a file next to
+    // the other install identity (`.neo4j-password`, `.admin-pin`) so the
+    // platform's set-pin route and the uninstall path read the same value the
+    // installer wrote, rather than re-detecting at request time. Task 534.
+    const installOwner = userInfo().username;
+    const installOwnerPersistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+    mkdirSync(installOwnerPersistDir, { recursive: true });
+    writeFileSync(join(installOwnerPersistDir, ".install-owner"), `${installOwner}\n`, { mode: 0o644 });
+    // Step 1 — apt install samba. Precheck `dpkg -s samba` first; if the
+    // package is already installed, skip apt entirely so the install does not
+    // contend with `unattended-upgrades` for `/var/lib/dpkg/lock-frontend`
+    // every time. Mirrors the [1/11] system-deps step.
+    try {
+        const dpkgCheck = spawnSync("dpkg", ["-s", "samba"], { stdio: "pipe", timeout: 5_000 });
+        if (dpkgCheck.status === 0) {
+            logFile("  samba already installed — skipping apt install.");
+            emitSambaMarker("apt", "ok-already-installed");
+        }
+        else {
+            installAptGroup("samba", ["samba"]);
+            emitSambaMarker("apt", "ok");
+        }
+    }
+    catch (err) {
+        const stderr = err instanceof Error ? err.message : String(err);
+        emitSambaMarker("apt", `fail: ${stderr}`);
+        throw err;
+    }
+    // Step 2 — write the brand stanza into /etc/samba/smb.conf.
+    const lanInterface = pickLanInterface(networkInterfaces());
+    if (!lanInterface) {
+        emitSambaMarker("conf", "fail: no non-loopback IPv4 interface");
+        throw new Error("samba-provision: no LAN interface with IPv4 — cannot bind smbd safely");
+    }
+    const SMB_CONF = "/etc/samba/smb.conf";
+    let existing = "";
+    if (existsSync(SMB_CONF)) {
+        try {
+            const cat = spawnSync("sudo", ["cat", SMB_CONF], { encoding: "utf-8", stdio: "pipe", timeout: 5_000 });
+            if (cat.status === 0)
+                existing = cat.stdout ?? "";
+        }
+        catch { /* treat as empty */ }
+    }
+    const merged = mergeSmbConf({ existing, brand, sharePath, lanInterface, installOwner });
+    try {
+        const tee = spawnSync("sudo", ["tee", SMB_CONF], { input: merged, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 10_000 });
+        if (tee.status !== 0) {
+            throw new Error(`sudo tee ${SMB_CONF} exited ${tee.status}: ${(tee.stderr ?? "").trim()}`);
+        }
+        const testparm = spawnSync("sudo", ["testparm", "-s", "--suppress-prompt"], { stdio: "pipe", encoding: "utf-8", timeout: 10_000 });
+        if (testparm.status !== 0) {
+            throw new Error(`testparm rejected merged smb.conf: ${(testparm.stderr ?? "").trim()}`);
+        }
+        // Grant passwordless sudo to the install-owner Unix user for the two
+        // smbpasswd invocations the platform's set-pin route makes (add-user-
+        // with-stdin and remove-user). Without this, the user systemd-unit-
+        // spawned admin server cannot sync the SMB password when the operator
+        // sets/rotates the PIN. Scoped tight: only these two literal arg-vectors
+        // are permitted; every other smbpasswd flavour still prompts. Principal
+        // and `-a -s <user>` / `-x <user>` arguments are the install owner, not
+        // a literal `admin`, so the grant works on a Pi (owner=admin) and on a
+        // laptop (owner=neo) without divergence. Task 534.
+        const SUDOERS = "/etc/sudoers.d/maxy-samba";
+        const sudoersBody = "# maxy-code Samba provisioning (smbpasswd sync from platform set-pin route).\n" +
+            `${installOwner} ALL=(root) NOPASSWD: /usr/bin/smbpasswd -a -s ${installOwner}, /usr/bin/smbpasswd -x ${installOwner}\n`;
+        const sudoersTee = spawnSync("sudo", ["tee", SUDOERS], { input: sudoersBody, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 5_000 });
+        if (sudoersTee.status !== 0) {
+            throw new Error(`sudo tee ${SUDOERS} exited ${sudoersTee.status}: ${(sudoersTee.stderr ?? "").trim()}`);
+        }
+        spawnSync("sudo", ["chmod", "0440", SUDOERS], { stdio: "pipe", timeout: 5_000 });
+        const visudoCheck = spawnSync("sudo", ["visudo", "-c", "-f", SUDOERS], { stdio: "pipe", encoding: "utf-8", timeout: 5_000 });
+        if (visudoCheck.status !== 0) {
+            throw new Error(`visudo rejected ${SUDOERS}: ${(visudoCheck.stderr ?? "").trim()}`);
+        }
+        emitSambaMarker("conf", `ok lan=${lanInterface} owner=${installOwner}`);
+    }
+    catch (err) {
+        const stderr = err instanceof Error ? err.message : String(err);
+        emitSambaMarker("conf", `fail: ${stderr}`);
+        throw err;
+    }
+    // Step 3 — smbpasswd for the install-owner Unix user. At install time the
+    // plaintext PIN is not in any file on disk (users.json stores the SHA-256
+    // hash only); the platform's set-pin route is responsible for syncing on
+    // PIN set/rotate. Mark as deferred so the four-marker contract still fires
+    // unbroken. Owner is recorded in the marker state so the install log shows
+    // which Unix user the smbpasswd entry will target. Task 534.
+    emitSambaMarker("user", `deferred reason=no-plaintext-pin-at-install owner=${installOwner} (set-pin route syncs)`);
+    // Step 4 — enable + start smbd and nmbd.
+    try {
+        shell("systemctl", ["enable", "--now", "smbd", "nmbd"], { sudo: true, timeout: 30_000 });
+        emitSambaMarker("units", "ok");
+    }
+    catch (err) {
+        const stderr = err instanceof Error ? err.message : String(err);
+        emitSambaMarker("units", `fail: ${stderr}`);
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// 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.
+//
+// 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;
+}
+// ---------------------------------------------------------------------------
+// Founder-side tier-set flags (Task 240).
+//
+// `--tier <solo|family|pro>` stamps account.json.tier directly when the brand
+// is personal-mode (today's default for both maxy-code and realagent-code).
+// `--entitlement-base64 <b64>` decodes a signed payload and writes it to
+// ~/<BRAND.configDir>/entitlement.json when the brand is commercial-mode.
+// The verifier at session start consumes whichever path the brand is on.
+//
+// Mode-mismatch combinations reject loudly at parse time — operator gets a
+// redirect message pointing at the correct flag. The installer is the sole
+// doctrine-sanctioned device-mutation channel; the admin agent has no tier-
+// upgrade surface by design.
+// ---------------------------------------------------------------------------
+let TIER_FLAG;
+let ENTITLEMENT_PAYLOAD;
+const tierIdx = _args.indexOf("--tier");
+if (tierIdx !== -1) {
+    try {
+        TIER_FLAG = validateTierFlag(_args[tierIdx + 1], BRAND.commercialMode === true);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Setup failed: ${msg}`);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+}
+const entitlementIdx = _args.indexOf("--entitlement-base64");
+if (entitlementIdx !== -1) {
+    try {
+        ENTITLEMENT_PAYLOAD = validateEntitlementBase64(_args[entitlementIdx + 1], BRAND.commercialMode === true);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Setup failed: ${msg}`);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+}
+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");
+    let preservedFromEnv = false;
+    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)";
+                preservedFromEnv = true;
+            }
+        }
+    }
+    catch { /* non-critical */ }
+    // Darwin has no VNC/X11 stack — `virtual` mode is Pi-only (tigervnc +
+    // websockify + novnc, none of which exist on macOS). A preserved
+    // DISPLAY_MODE=virtual is never operator intent on darwin — it is the
+    // legacy default from installers before 0.1.127, when `virtual` was the
+    // only initial value written. The guard fires whenever the resolved
+    // value is not already `native`, covering both fresh installs and
+    // upgrades that inherited the legacy default.
+    if (process.platform === "darwin" && DISPLAY_MODE !== "native") {
+        DISPLAY_MODE_SOURCE = preservedFromEnv
+            ? "darwin-auto (override-legacy-virtual)"
+            : "darwin-auto (no VNC stack)";
+        DISPLAY_MODE = "native";
+    }
+}
+// ---------------------------------------------------------------------------
+// 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.
+//
+// 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;
+// ---------------------------------------------------------------------------
+// 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;
+// ---------------------------------------------------------------------------
+// pre-flight platform refusal.
+//
+// Runs BEFORE initLogging() (LOG_DIR creation), port resolution, and any
+// brew/scutil/hostnamectl probe. Only Linux + darwin are supported;
+// 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>` (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 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}`;
+// emit platform header and the resolved log/persist paths to
+// stdout BEFORE the log file is opened. If initLogging's mkdir or first
+// appendFileSync throws, the operator still sees brand/version/arch and the
+// exact path the log file SHOULD live at, instead of a silent exit between
+// the LOG_DIR mkdir and the first log write.
+console.log(PLATFORM_HEADER);
+console.log(`[create-maxy] log=${LOG_FILE} persist=${PERSIST_DIR}`);
+initLogging();
+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
+    // write the resolved Chromium absolute path into the deployed
+    // platform/config/ so vnc.sh and writeChromiumWrapper read the same
+    // value. Must run after deployPayload (config dir is
+    // a payload subdirectory). Linux-only; no-op on darwin/non-linux.
+    writeChromiumBinaryPathFile();
+    // 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(); // shared HMAC key readable by maxy-edge + maxy-ui
+    buildPlatform();
+    registerLocalAndExternalPlugins(); // install-time plugin registration
+    setupVncViewer();
+    setupAccount();
+    if (ENTITLEMENT_PAYLOAD) {
+        writeEntitlementFromFlag(ENTITLEMENT_PAYLOAD);
+    }
+    installService();
+    // Samba on the LAN. Runs after the brand systemd unit is up so
+    // SMB provisioning never blocks the admin server starting; loud-fail per
+    // step. The smbpasswd `user` step is deferred at install time and synced
+    // by the platform's /set-pin route when the operator sets a PIN.
+    provisionSamba();
+    console.log("");
+    console.log("================================================================");
+    console.log("");
+    if (isLinux()) {
+        console.log(`  Same network (Pi / LAN):  http://${DEVICE_HOSTNAME}.local:${PORT}`);
+        console.log("");
+        console.log(`  Remote access (Hetzner / cloud) — on your local machine run:`);
+        console.log(`    ssh -L ${PORT}:localhost:${PORT} -L ${BRAND.websockifyPort}:localhost:${BRAND.websockifyPort} admin@<server-ipv4>`);
+        console.log(`  Then open:`);
+        console.log(`    Dashboard: http://localhost:${PORT}`);
+        console.log(`    VNC browser (Claude OAuth + Cloudflare): http://localhost:${BRAND.websockifyPort}/vnc.html`);
+    }
+    else {
+        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);
+}