@rubytech/create-realagent 1.0.850 → 1.0.853

package/dist/__tests__/preflight-port-classifier.test.js

@@ -0,0 +1,330 @@
+// Task 938 — acceptance grid for classifyPortHolder (chromium argv-anchor).
+// Task 939 — extended grid for Xtigervnc display anchor + websockify port
+// anchor + holder-type detection on argv[0] basename / full-argv scan.
+//
+// The wrapper in index.ts owns ss(8), /proc reads, kill(2), and the operator-
+// override exit. This suite exercises only the pure decision rule: ssOutput +
+// brand identities → kind. Inputs in, decision out — no fs, no exec, no spawn.
+//
+// Cmdlines below mimic /proc/<pid>/cmdline format: argv joined by NUL bytes,
+// possibly with a trailing NUL. The classifier requires this format so it
+// can distinguish a flag value (a real ownership claim) from a different
+// flag whose value happens to contain the marker substring.
+//
+// Runs via Node's built-in test runner — same convention as
+// peer-brand-detect.test.ts.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { classifyPortHolder } from "../preflight-port-classifier.js";
+// Per-brand identities mirror the live brands/<brand>/brand.json values that
+// bundle.js stamps into payload/platform/config/brand-registry.json. Values
+// are derived from the brand manifests, not hardcoded as ground-truth here:
+// the test suite asserts the rule, not the numbers. Any rebalance in
+// brands/*/brand.json updates the registry on the next bundle and the
+// classifier consumes the new values without source change.
+const MAXY = { configDir: ".maxy", vncDisplay: 99, websockifyPort: 6080 };
+const REAL = { configDir: ".realagent", vncDisplay: 100, websockifyPort: 6081 };
+const MAXY_2 = { configDir: ".maxy-2", vncDisplay: 101, websockifyPort: 6082 };
+const MAXY_3 = { configDir: ".maxy-3", vncDisplay: 102, websockifyPort: 6083 };
+const MAXY_4 = { configDir: ".maxy-4", vncDisplay: 103, websockifyPort: 6084 };
+const ALL = [MAXY, REAL, MAXY_2, MAXY_3, MAXY_4];
+const peers = (own) => ALL.filter(b => b.configDir !== own.configDir);
+const SS_PID_42 = "LISTEN 0 4096  *:9222  *:*  users:((\"chrome\",pid=42,fd=12))";
+const SS_PID_99 = "LISTEN 0 4096  *:9223  *:*  users:((\"chrome\",pid=99,fd=12))";
+const SS_PID_777 = "LISTEN 0 5  127.0.0.1:5900  0.0.0.0:*  users:((\"Xtigervnc\",pid=777,fd=9))";
+const SS_PID_888 = "LISTEN 0 5  127.0.0.1:5901  0.0.0.0:*  users:((\"Xtigervnc\",pid=888,fd=9))";
+const SS_PID_555 = "LISTEN 0 5  *:6080  *:*  users:((\"websockify\",pid=555,fd=8))";
+const cmd = (...argv) => argv.join("\0") + "\0";
+// ---------------------------------------------------------------------------
+// EMPTY / no pid / cmdline race
+// ---------------------------------------------------------------------------
+test("empty ssOutput → EMPTY", () => {
+    const r = classifyPortHolder({
+        ssOutput: "",
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => { throw new Error("should not be called"); },
+    });
+    assert.equal(r.kind, "EMPTY");
+});
+test("UNRELATED: ssOutput non-empty but no pid= token", () => {
+    const r = classifyPortHolder({
+        ssOutput: "Recv-Q Send-Q  Local Address:Port  Peer Address:Port",
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => { throw new Error("should not be called"); },
+    });
+    assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.pid, undefined);
+});
+test("UNRELATED: getCmdline throws (race — process exited between ss and read)", () => {
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => { const e = new Error("ENOENT"); e.code = "ENOENT"; throw e; },
+    });
+    assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.pid, 42);
+    assert.equal(r.cmdlineReadFailed, true);
+});
+test("ss header line containing 'pid=': last pid= wins", () => {
+    // If a future ss locale prepends header text containing the literal `pid=`,
+    // the first-match heuristic would lift the wrong value. The LISTEN row is
+    // always last, so taking the last pid= match is the structural fix.
+    const ssOutput = `State pid= notes\nLISTEN 0 4096  *:9222 *:*  users:(("chrome",pid=42,fd=12))`;
+    const cmdline = cmd("chromium", "--user-data-dir=/home/neo/.maxy/chromium-profile");
+    const r = classifyPortHolder({
+        ssOutput,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: pid => { assert.equal(pid, 42, "must pick the LISTEN row's pid"); return cmdline; },
+    });
+    assert.equal(r.kind, "OWN_BRAND");
+    assert.equal(r.pid, 42);
+});
+// ---------------------------------------------------------------------------
+// Chromium (Task 938 grid, migrated to BrandIdentity API)
+// ---------------------------------------------------------------------------
+test("chromium OWN_BRAND: --user-data-dir=PATH single argv", () => {
+    const cmdline = cmd("/opt/google/chrome/chrome", "--user-data-dir=/home/neo/.maxy/chromium-profile", "--remote-debugging-port=9222");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: pid => { assert.equal(pid, 42); return cmdline; },
+    });
+    assert.equal(r.kind, "OWN_BRAND");
+    assert.equal(r.holderType, "chromium");
+    assert.equal(r.pid, 42);
+    assert.equal(r.profilePath, "/home/neo/.maxy/chromium-profile");
+});
+test("chromium OWN_BRAND: --user-data-dir PATH split across two argvs", () => {
+    const cmdline = cmd("/usr/bin/chromium", "--user-data-dir", "/home/admin/.maxy/chromium-profile", "--remote-debugging-port=9222");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "OWN_BRAND");
+    assert.equal(r.holderType, "chromium");
+    assert.equal(r.profilePath, "/home/admin/.maxy/chromium-profile");
+});
+test("chromium PEER_BRAND: cmdline holds another known brand's profile path", () => {
+    const cmdline = cmd("/usr/bin/chromium", "--user-data-dir=/home/admin/.realagent/chromium-profile", "--remote-debugging-port=9223");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_99,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "PEER_BRAND");
+    assert.equal(r.holderType, "chromium");
+    assert.equal(r.pid, 99);
+    assert.equal(r.profilePath, "/home/admin/.realagent/chromium-profile");
+});
+test("chromium UNRELATED: cmdline matches no known brand profile", () => {
+    // Anchors only on the basename — "/usr/bin/python3" is not chromium.
+    // Use an actual chromium binary with a non-brand profile path instead.
+    const cmdline = cmd("chromium", "--user-data-dir=/tmp/scratch", "--remote-debugging-port=9999");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.holderType, "chromium");
+    assert.equal(r.pid, 42);
+});
+test("chromium UNRELATED: --user-data-dir absent (no profile claim)", () => {
+    // Kernel threads, GPU/zygote/utility chrome processes inherit profile via
+    // fork without re-stating --user-data-dir. They wouldn't be listening
+    // anyway, but if one ever showed up here we must classify as UNRELATED.
+    const cmdline = cmd("/opt/google/chrome/chrome", "--type=gpu-process", "--no-sandbox");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.holderType, "chromium");
+});
+test("chromium substring boundary: own=.maxy must NOT match .maxy-2 cmdline", () => {
+    const cmdline = cmd("chromium", "--user-data-dir=/home/neo/.maxy-2/chromium-profile");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "PEER_BRAND");
+    assert.equal(r.profilePath, "/home/neo/.maxy-2/chromium-profile");
+});
+test("chromium substring boundary: own=.maxy-2 must NOT misclassify .maxy cmdline as own", () => {
+    const cmdline = cmd("chromium", "--user-data-dir=/home/neo/.maxy/chromium-profile");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownBrand: MAXY_2,
+        peerBrands: peers(MAXY_2),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "PEER_BRAND");
+    assert.equal(r.profilePath, "/home/neo/.maxy/chromium-profile");
+});
+test("chromium argv-anchor safety: marker in --load-extension value must NOT match", () => {
+    // Adversarial case: a Chrome flag whose value contains the profile-path
+    // substring, but no actual --user-data-dir claim. Naive substring matching
+    // would false-positive OWN_BRAND.
+    const cmdline = cmd("chromium", "--load-extension=/tmp/decoy/.maxy/chromium-profile", "--remote-debugging-port=9222");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "UNRELATED");
+});
+test("chromium variant basenames: google-chrome-stable detected as chromium", () => {
+    // Ubuntu Noble laptop replaces snap-confined chromium with
+    // google-chrome-stable (Task 929). The classifier must still recognise
+    // it as a chromium-family holder.
+    const cmdline = cmd("/usr/bin/google-chrome-stable", "--user-data-dir=/home/neo/.maxy/chromium-profile", "--remote-debugging-port=9222");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "OWN_BRAND");
+    assert.equal(r.holderType, "chromium");
+});
+// ---------------------------------------------------------------------------
+// Xtigervnc (Task 939 — display-number anchor)
+// ---------------------------------------------------------------------------
+test("xtigervnc OWN_BRAND: argv[1] :99 matches own.vncDisplay", () => {
+    // Reproduces the laptop-maxy and Pi-maxy install-time log:
+    //   cmdline: Xtigervnc :99 -geometry 1280x800 -depth 24 -rfbport 5900 …
+    const cmdline = cmd("Xtigervnc", ":99", "-geometry", "1280x800", "-depth", "24", "-rfbport", "5900", "-localhost", "-SecurityTypes", "None", "-AlwaysShared", "-BlacklistThreshold", "1000000");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_777,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: pid => { assert.equal(pid, 777); return cmdline; },
+    });
+    assert.equal(r.kind, "OWN_BRAND");
+    assert.equal(r.holderType, "xtigervnc");
+    assert.equal(r.pid, 777);
+    assert.equal(r.vncDisplay, 99);
+});
+test("xtigervnc PEER_BRAND: argv[1] :100 matches Real Agent vncDisplay when own is Maxy", () => {
+    const cmdline = cmd("Xtigervnc", ":100", "-rfbport", "5901");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_888,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "PEER_BRAND");
+    assert.equal(r.holderType, "xtigervnc");
+    assert.equal(r.vncDisplay, 100);
+});
+test("xtigervnc UNRELATED: argv display number matches no known brand", () => {
+    const cmdline = cmd("Xtigervnc", ":42", "-rfbport", "5942");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_777,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.holderType, "xtigervnc");
+    assert.equal(r.vncDisplay, 42);
+});
+test("xtigervnc UNRELATED: no `:N` token in argv", () => {
+    // Defence-in-depth: if argv parsing ever sees an Xtigervnc invocation
+    // with no display literal, classify UNRELATED rather than guessing.
+    const cmdline = cmd("Xtigervnc", "-help");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_777,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.holderType, "xtigervnc");
+    assert.equal(r.vncDisplay, undefined);
+});
+// ---------------------------------------------------------------------------
+// websockify (Task 939 — bind-port anchor with full-argv scan for the binary)
+// ---------------------------------------------------------------------------
+test("websockify OWN_BRAND: bind port [::]:6080 matches own.websockifyPort (direct invocation)", () => {
+    const cmdline = cmd("websockify", "--web", "/usr/share/novnc", "[::]:6080", "localhost:5900");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_555,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: pid => { assert.equal(pid, 555); return cmdline; },
+    });
+    assert.equal(r.kind, "OWN_BRAND");
+    assert.equal(r.holderType, "websockify");
+    assert.equal(r.pid, 555);
+    assert.equal(r.websockifyPort, 6080);
+});
+test("websockify OWN_BRAND: detected via argv scan when invoked through python", () => {
+    // Pi Bookworm packages websockify as a python script with no shebang
+    // honoured by systemd in some configs — argv[0] may be `python3` and
+    // argv[1] = `/usr/bin/websockify`. The detector scans the full argv.
+    const cmdline = cmd("/usr/bin/python3", "/usr/bin/websockify", "--web", "/usr/share/novnc", "[::]:6080", "localhost:5900");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_555,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "OWN_BRAND");
+    assert.equal(r.holderType, "websockify");
+    assert.equal(r.websockifyPort, 6080);
+});
+test("websockify PEER_BRAND: bind port matches Real Agent websockifyPort when own is Maxy", () => {
+    const cmdline = cmd("websockify", "--web", "/usr/share/novnc", "[::]:6081", "localhost:5901");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_555,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "PEER_BRAND");
+    assert.equal(r.holderType, "websockify");
+    assert.equal(r.websockifyPort, 6081);
+});
+test("websockify UNRELATED: bind port matches no known brand", () => {
+    const cmdline = cmd("websockify", "--web", "/usr/share/novnc", "[::]:9999", "localhost:5900");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_555,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.holderType, "websockify");
+    assert.equal(r.websockifyPort, undefined);
+});
+// ---------------------------------------------------------------------------
+// Unknown holder (defence-in-depth)
+// ---------------------------------------------------------------------------
+test("UNRELATED holderType=unknown: argv[0] is neither chromium, Xtigervnc, nor websockify", () => {
+    const cmdline = cmd("/usr/bin/python3", "-m", "http.server", "9222");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.holderType, "unknown");
+    assert.equal(r.pid, 42);
+    assert.equal(r.cmdline, "/usr/bin/python3 -m http.server 9222");
+});

package/dist/index.js

@@ -11,6 +11,7 @@ import { renderPlist } from "./launchd-plist.js";
 import { installAllBrewPackages } from "./brew-install.js";
 import { parseSwVers, isSupportedMacosVersion } from "./macos-version.js";
 import { decideChromiumAction, isSnapConfinedPath } from "./snap-chromium.js";
+import { classifyPortHolder } from "./preflight-port-classifier.js";
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive all brand-specific installation values.
 // The bundler stamps brand.json into the payload at build time.
@@ -2452,39 +2453,189 @@ function installService() {
     const RFB_PORT = BRAND.rfbPort ?? 5900 + VNC_OFFSET;
     const WEBSOCKIFY_PORT_BRAND = BRAND.websockifyPort ?? 6080 + VNC_OFFSET;
     const CDP_PORT_BRAND = BRAND.cdpPort ?? 9222 + VNC_OFFSET;
-    // Task 924 pre-flight — refuse to write service files if any of the
-    // three brand-scoped ports is already held by a process that is NOT a
-    // peer brand's edge service. Collisions with peer brands' Xtigervnc or
-    // websockify on this device are normal in concurrent multi-brand
-    // installs and harmless because each brand's port set is disjoint by
-    // construction. Anything else (a stale pre-924 unit, an external VNC,
-    // or operator misconfiguration) is a structural collision the operator
-    // must resolve before service start.
-    const checkInstallPortFree = (label, port) => {
+    // Task 924/938 pre-flight — refuse to write service files if any of the
+    // three brand-scoped ports is already held by a process that is NOT this
+    // brand's own on-demand browser nor a peer brand's edge stack.
+    //
+    // Classification (Task 938 chromium, Task 939 Xtigervnc + websockify) reads
+    // `/proc/<pid>/cmdline` and applies a holder-specific argv anchor. Task 938
+    // covered chromium-only via `--user-data-dir=`; Task 939 closed the gap on
+    // Xtigervnc (no such flag — anchor on the `:N` display literal) and
+    // websockify (anchor on bind port). Brand identities (configDir,
+    // vncDisplay, websockifyPort) come from brand-registry.json which the
+    // bundler stamps at build time from every brands/<brand>/brand.json.
+    //
+    // Decisions per holder:
+    //   OWN_BRAND  — SIGTERM, recheck, SIGKILL on stragglers, exit-1 only if
+    //                the port is still held after both signals.
+    //   PEER_BRAND — log OK and return (per-brand port sets are disjoint).
+    //   UNRELATED  — refuse to write service files; emit operator override.
+    // macOS dev hosts (no ss) fall through the catch and skip pre-flight
+    // entirely — the runtime check in vnc.sh covers Linux production.
+    const ownBrand = {
+        configDir: BRAND.configDir,
+        vncDisplay: VNC_DISPLAY,
+        websockifyPort: WEBSOCKIFY_PORT_BRAND,
+    };
+    // Peer registry — load from payload/platform/config/brand-registry.json
+    // when present (Task 939+ bundles). Older bundles ship without the
+    // registry; in that case peerBrands stays empty. PEER_BRAND classification
+    // for Xtigervnc/websockify is a defence-in-depth case anyway (port sets
+    // are disjoint by Task 924), so the empty-list fallback is safe — peer
+    // chromium will fall through to UNRELATED, matching pre-Task 938 behaviour
+    // for the only realistic scenario (a stale peer browser on the wrong CDP
+    // port).
+    const peerBrands = (() => {
+        const registryPath = join(PAYLOAD_DIR, "platform", "config", "brand-registry.json");
+        if (!existsSync(registryPath)) {
+            logFile(`  [preflight] brand-registry.json not in payload — peer matching disabled`);
+            return [];
+        }
         try {
-            const out = execFileSync("ss", ["-tlnpH", `sport = :${port}`], {
-                encoding: "utf-8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"],
-            });
-            const heldBy = out.trim();
-            if (!heldBy)
-                return;
-            const isPeerBrandStack = /Xtigervnc/.test(heldBy) || /websockify/.test(heldBy) || /chromium/.test(heldBy);
-            if (isPeerBrandStack) {
-                logFile(`  [preflight] ${label}=${port} held by a peer brand's stack — OK (per-brand ports are disjoint by construction)`);
-                return;
+            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 });
             }
-            console.error(`  ERROR: [preflight:collision] brand=${BRAND.hostname} ${label}=${port} held by an unrelated process:`);
-            console.error(`         ${heldBy}`);
-            console.error(`         Refusing to write service files; resolve the collision before retrying.`);
-            console.error(`         Operator override: edit brands/${BRAND.hostname}/brand.json and set ${label}=<free port>, re-bundle, re-install.`);
+            return entries;
+        }
+        catch (err) {
+            logFile(`  [preflight] brand-registry.json parse failed: ${err instanceof Error ? err.message : String(err)} — peer matching disabled`);
+            return [];
+        }
+    })();
+    const ssReadHolder = (port) => {
+        return execFileSync("ss", ["-tlnpH", `sport = :${port}`], {
+            encoding: "utf-8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"],
+        });
+    };
+    // Pass raw NUL-separated cmdline to the classifier so it can argv-anchor
+    // on `--user-data-dir=`. Replacing NUL with space here would defeat that.
+    const readCmdline = (pid) => readFileSync(`/proc/${pid}/cmdline`, "utf-8");
+    const sleepMs = (ms) => { spawnSync("sleep", [(ms / 1000).toString()]); };
+    // Tightly scoped variant for retry-path ss reads. Failures here (timeout,
+    // ENOMEM, signal) are structural — never the macOS-no-ss case (we already
+    // succeeded once) — so they get a structured exit, not a stack trace.
+    const ssReadOrAbort = (label, port) => {
+        try {
+            return ssReadHolder(port);
+        }
+        catch (err) {
+            console.error(`  ERROR: [preflight] ${label}=${port} ss recheck failed: ${err instanceof Error ? err.message : String(err)}`);
+            console.error(`         Resolve manually before retrying.`);
             process.exit(1);
         }
+    };
+    // Distinguish ESRCH (process already gone — expected) from EPERM/EINVAL
+    // (alarming — signals we can't deliver, possibly a recycled pid). Returns
+    // true for clean kill or ESRCH, false otherwise (caller logs a warning).
+    const killNoThrow = (pid, signal) => {
+        try {
+            process.kill(pid, signal);
+            return true;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ESRCH")
+                return true;
+            logFile(`  [preflight] kill(${pid}, ${signal}) failed code=${code ?? "unknown"}`);
+            return false;
+        }
+    };
+    const classify = (ssOutput) => classifyPortHolder({
+        ssOutput, ownBrand, peerBrands, getCmdline: readCmdline,
+    });
+    // Task 939 — log line varies by detected holder so the operator can see
+    // which OWN_BRAND stack is being killed. The kill loop is identical for
+    // all three holders (SIGTERM → 300ms → recheck → SIGKILL → recheck), so
+    // only the announce line differs.
+    const ownBrandAnnounceLine = (label, port, c) => {
+        if (c.holderType === "xtigervnc") {
+            return `  [preflight] ${label}=${port} held by OWN brand Xtigervnc display=:${c.vncDisplay} pid=${c.pid} — sending SIGTERM`;
+        }
+        if (c.holderType === "websockify") {
+            return `  [preflight] ${label}=${port} held by OWN brand websockify pid=${c.pid} — sending SIGTERM`;
+        }
+        // Default — chromium / unknown OWN_BRAND
+        return `  [preflight] ${label}=${port} held by OWN brand process pid=${c.pid} profile=${c.profilePath} — sending SIGTERM`;
+    };
+    const checkInstallPortFree = (label, port) => {
+        let firstSsOutput;
+        try {
+            firstSsOutput = ssReadHolder(port);
+        }
         catch (err) {
             // ss may not be present on macOS dev hosts — skip the pre-flight there
             // rather than abort the install. The runtime check in vnc.sh covers
-            // production-like Linux installs where this matters.
+            // 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);
@@ -2631,8 +2782,8 @@ WantedBy=multi-user.target
         console.log("  [cdp-check] skipped reason=native-display (on-demand Chromium)");
     }
     else {
-        console.log("  Verifying browser automation (CDP on port 9222)...");
-        const cdpCheck = spawnSync("curl", ["-sf", "http://127.0.0.1:9222/json/version", "-o", "/dev/null"], {
+        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",
         });
@@ -2649,8 +2800,8 @@ WantedBy=multi-user.target
                 vncLog = `(no boot log found at ${vncLogPath})`;
             }
             console.error("");
-            console.error("Setup failed: Browser automation unavailable — CDP port 9222 not responding");
-            console.error("  ERROR: Browser automation unavailable — CDP port 9222 not responding.");
+            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);

package/dist/preflight-port-classifier.js

@@ -0,0 +1,222 @@
+// Task 938 — pure classifier for the install-time port collision pre-flight.
+// Task 939 — extended with Xtigervnc and websockify holder anchors, closing
+// the laptop + Pi miss where the brand's own VNC stack was misclassified
+// UNRELATED because Xtigervnc has no `--user-data-dir=` argv to anchor on.
+//
+// The wrapper in index.ts owns the side effects: ss read, /proc/<pid>/cmdline
+// read, SIGTERM/SIGKILL escalation, and the operator-override exit. This
+// module owns only the classification rule — inputs in, decision out.
+//
+// Holder detection (post-pid):
+//   argv[0] basename ∈ chromium-set                    → chromium
+//   argv[0] basename === "Xtigervnc"                   → xtigervnc
+//   any argv basename === "websockify" (full scan      → websockify
+//     because Pi Bookworm invokes it as
+//     `python3 /usr/bin/websockify …`, so argv[0] is
+//     the interpreter, not websockify itself)
+//   else                                                → unknown
+//
+// Per-holder anchor:
+//   chromium   — `--user-data-dir=PATH`; PATH contains `/<configDir>/chromium-profile`
+//                → OWN_BRAND if configDir matches own; PEER_BRAND if matches peer.
+//                False-match guard: argv-anchor on the flag, never substring,
+//                so `--load-extension=…/<configDir>/…` cannot poison.
+//   xtigervnc  — first non-flag argv of the form `:N` (display number);
+//                vnc.sh invokes `Xtigervnc "${VNC_DISPLAY}" -rfbport …` so
+//                argv[1] is literally `:99`, `:100`, etc. Match N against
+//                own.vncDisplay / peer.vncDisplay.
+//   websockify — collect every port number embedded in argv (covers both
+//                `[::]:6080` bind form and `localhost:5900` upstream form).
+//                Per Task 924, brand websockifyPort/rfbPort sets are
+//                disjoint, so at most one brand's websockifyPort can appear.
+//
+// Why "last pid=" instead of "first pid=": ss with `-tlnpH sport = :PORT`
+// emits the LISTEN row last; if a future ss locale prepends a header line
+// containing `pid=` text, the first-match heuristic would lift the wrong
+// pid. The last `pid=` is always inside the LISTEN row's `users:((…))`.
+/**
+ * `cmdline` should be the raw `/proc/<pid>/cmdline` contents — NUL-separated
+ * argv as the kernel emits it. Do NOT replace NUL with space before passing:
+ * the argv boundaries are what disambiguate `--user-data-dir=PATH` from a
+ * different flag whose value happens to contain `--user-data-dir=`.
+ */
+export function classifyPortHolder(args) {
+    const { ssOutput, ownBrand, peerBrands, getCmdline } = args;
+    if (ssOutput.trim() === "")
+        return { kind: "EMPTY" };
+    const pidMatches = [...ssOutput.matchAll(/pid=(\d+)/g)];
+    if (pidMatches.length === 0)
+        return { kind: "UNRELATED" };
+    const pid = Number(pidMatches[pidMatches.length - 1][1]);
+    let cmdline;
+    try {
+        cmdline = getCmdline(pid);
+    }
+    catch {
+        return { kind: "UNRELATED", pid, cmdlineReadFailed: true };
+    }
+    const prettyCmdline = cmdline.replace(/\0/g, " ").trim();
+    const argv = cmdline.split("\0").filter(s => s.length > 0);
+    const holderType = detectHolderType(argv);
+    switch (holderType) {
+        case "chromium":
+            return classifyChromium(argv, prettyCmdline, pid, ownBrand, peerBrands);
+        case "xtigervnc":
+            return classifyXtigervnc(argv, prettyCmdline, pid, ownBrand, peerBrands);
+        case "websockify":
+            return classifyWebsockify(argv, prettyCmdline, pid, ownBrand, peerBrands);
+        case "unknown":
+            return { kind: "UNRELATED", pid, cmdline: prettyCmdline, holderType };
+    }
+}
+// ---------------------------------------------------------------------------
+// Holder detection
+// ---------------------------------------------------------------------------
+const CHROMIUM_BASENAMES = new Set([
+    "chrome",
+    "chromium",
+    "chromium-browser",
+    "google-chrome",
+    "google-chrome-stable",
+]);
+function basename(p) {
+    const i = p.lastIndexOf("/");
+    return i === -1 ? p : p.slice(i + 1);
+}
+function detectHolderType(argv) {
+    if (argv.length === 0)
+        return "unknown";
+    const head = basename(argv[0]);
+    if (CHROMIUM_BASENAMES.has(head))
+        return "chromium";
+    if (head === "Xtigervnc")
+        return "xtigervnc";
+    // websockify can be invoked directly (shebang) or via python; scan argv.
+    for (const a of argv) {
+        if (basename(a) === "websockify")
+            return "websockify";
+    }
+    return "unknown";
+}
+// ---------------------------------------------------------------------------
+// Per-holder anchors
+// ---------------------------------------------------------------------------
+function classifyChromium(argv, prettyCmdline, pid, ownBrand, peerBrands) {
+    const userDataDir = findFlagValue(argv, "--user-data-dir");
+    if (userDataDir === null) {
+        // Kernel threads, GPU/zygote/utility chrome processes inherit profile
+        // via fork without re-stating --user-data-dir. They wouldn't be
+        // listening anyway, but classify UNRELATED if one ever shows up here
+        // — never OWN_BRAND on a substring fluke.
+        return { kind: "UNRELATED", pid, cmdline: prettyCmdline, holderType: "chromium" };
+    }
+    const ownSuffix = `/${ownBrand.configDir}/chromium-profile`;
+    if (userDataDir.includes(ownSuffix)) {
+        return {
+            kind: "OWN_BRAND", pid, cmdline: prettyCmdline,
+            profilePath: userDataDir, holderType: "chromium",
+        };
+    }
+    for (const peer of peerBrands) {
+        const peerSuffix = `/${peer.configDir}/chromium-profile`;
+        if (userDataDir.includes(peerSuffix)) {
+            return {
+                kind: "PEER_BRAND", pid, cmdline: prettyCmdline,
+                profilePath: userDataDir, holderType: "chromium",
+            };
+        }
+    }
+    return { kind: "UNRELATED", pid, cmdline: prettyCmdline, holderType: "chromium" };
+}
+function classifyXtigervnc(argv, prettyCmdline, pid, ownBrand, peerBrands) {
+    const display = parseDisplayArg(argv);
+    if (display === null) {
+        return { kind: "UNRELATED", pid, cmdline: prettyCmdline, holderType: "xtigervnc" };
+    }
+    if (display === ownBrand.vncDisplay) {
+        return {
+            kind: "OWN_BRAND", pid, cmdline: prettyCmdline,
+            vncDisplay: display, holderType: "xtigervnc",
+        };
+    }
+    for (const peer of peerBrands) {
+        if (display === peer.vncDisplay) {
+            return {
+                kind: "PEER_BRAND", pid, cmdline: prettyCmdline,
+                vncDisplay: display, holderType: "xtigervnc",
+            };
+        }
+    }
+    return {
+        kind: "UNRELATED", pid, cmdline: prettyCmdline,
+        vncDisplay: display, holderType: "xtigervnc",
+    };
+}
+function classifyWebsockify(argv, prettyCmdline, pid, ownBrand, peerBrands) {
+    const ports = collectPorts(argv);
+    if (ports.has(ownBrand.websockifyPort)) {
+        return {
+            kind: "OWN_BRAND", pid, cmdline: prettyCmdline,
+            websockifyPort: ownBrand.websockifyPort, holderType: "websockify",
+        };
+    }
+    for (const peer of peerBrands) {
+        if (ports.has(peer.websockifyPort)) {
+            return {
+                kind: "PEER_BRAND", pid, cmdline: prettyCmdline,
+                websockifyPort: peer.websockifyPort, holderType: "websockify",
+            };
+        }
+    }
+    return { kind: "UNRELATED", pid, cmdline: prettyCmdline, holderType: "websockify" };
+}
+// ---------------------------------------------------------------------------
+// argv parsing helpers
+// ---------------------------------------------------------------------------
+// Find --flag=VALUE (single argv) or --flag VALUE (split across two argvs).
+function findFlagValue(argv, flag) {
+    const PREFIX = `${flag}=`;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith(PREFIX))
+            return a.slice(PREFIX.length);
+        if (a === flag && i + 1 < argv.length)
+            return argv[i + 1];
+    }
+    return null;
+}
+// First non-flag argv of the form `:N` after argv[0]. vnc.sh's invocation
+// puts the display in argv[1], but the function tolerates additional
+// pre-positional flags by scanning past any `-`-prefixed token.
+function parseDisplayArg(argv) {
+    for (let i = 1; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("-"))
+            continue;
+        const m = a.match(/^:(\d+)$/);
+        if (m)
+            return Number(m[1]);
+    }
+    return null;
+}
+// Collect every port number embedded in argv. Matches:
+//   "[::]:6080"        → 6080  (websockify bind, IPv6 wildcard)
+//   "0.0.0.0:8080"     → 8080  (bind, IPv4 wildcard)
+//   "localhost:5900"   → 5900  (websockify upstream)
+//   "6080"             → 6080  (bare positional)
+// Skips flag tokens beginning with "-".
+function collectPorts(argv) {
+    const ports = new Set();
+    const portRe = /(?::|^)(\d{1,5})$/;
+    for (const a of argv) {
+        if (a.startsWith("-"))
+            continue;
+        const m = a.match(portRe);
+        if (m === null)
+            continue;
+        const n = Number(m[1]);
+        if (n >= 1 && n <= 65535)
+            ports.add(n);
+    }
+    return ports;
+}

package/package.json

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

package/payload/platform/config/brand-registry.json

@@ -0,0 +1,44 @@
+{
+  "brands": [
+    {
+      "hostname": "maxy",
+      "configDir": ".maxy",
+      "vncDisplay": 99,
+      "rfbPort": 5900,
+      "websockifyPort": 6080,
+      "cdpPort": 9222
+    },
+    {
+      "hostname": "maxy-2",
+      "configDir": ".maxy-2",
+      "vncDisplay": 101,
+      "rfbPort": 5902,
+      "websockifyPort": 6082,
+      "cdpPort": 9224
+    },
+    {
+      "hostname": "maxy-3",
+      "configDir": ".maxy-3",
+      "vncDisplay": 102,
+      "rfbPort": 5903,
+      "websockifyPort": 6083,
+      "cdpPort": 9225
+    },
+    {
+      "hostname": "maxy-4",
+      "configDir": ".maxy-4",
+      "vncDisplay": 103,
+      "rfbPort": 5904,
+      "websockifyPort": 6084,
+      "cdpPort": 9226
+    },
+    {
+      "hostname": "realagent",
+      "configDir": ".realagent",
+      "vncDisplay": 100,
+      "rfbPort": 5901,
+      "websockifyPort": 6081,
+      "cdpPort": 9223
+    }
+  ]
+}

package/payload/platform/plugins/workflows/PLUGIN.md

@@ -79,7 +79,7 @@ The executor can access these capabilities through agentic steps:
 
 | Capability | MCP Server | Infrastructure |
 |---|---|---|
-| Browser automation | `@playwright/mcp` | Chromium with CDP on port 9222 (started by `vnc.sh`, always running) |
+| Browser automation | `@playwright/mcp` | Chromium with CDP on the brand's `cdpPort` from `brand.json` (started by `vnc.sh`, always running) |
 | Any MCP-compatible tool | Declared in step's `mcpServers` | Command must be in PATH on the device |
 
 The executor cannot:

package/payload/platform/scripts/installer-device-verify.sh

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# Task 939 — post-publish device-side verification harness.
+#
+# Closes the verification gap that let Task 938 archive on source-diff alone:
+# without a device run, neither (a) the classifier-extension fix nor (b) the
+# CDP probe brand-aware fix shipped to actual hardware. This script SSHes to
+# every device in a manifest, runs the published installer for that brand,
+# then greps the install log for the canonical CDP success banner.
+#
+# Exit zero ↔ every device's installer reached "Browser automation ready
+# (CDP connected)". Any other state — ssh failure, npx non-zero, missing
+# banner — is a non-zero exit with the failing device named on stderr.
+#
+# CONTRACT
+#   Archival of any task that touches packages/create-maxy/** is contingent
+#   on this script exiting zero against the published version. The exit code
+#   and the per-device summary are quoted in the close commit body.
+#
+# USAGE
+#   $ installer-device-verify.sh <published-version>
+#
+#   <published-version>  e.g. 1.0.853 — appended to `npx -y @rubytech/create-<brand>@<version>`.
+#
+# MANIFEST
+#   Path: $MAXY_VERIFY_MANIFEST (default $HOME/.maxy-verify-devices.json).
+#   Format: JSON array of devices; each entry:
+#     {
+#       "name":    "maxy-pi-test",            // free-form display name
+#       "brand":   "maxy",                    // npm package suffix (@rubytech/create-<brand>)
+#       "configDir": ".maxy",                 // brand configDir; logs live in $HOME/<configDir>/logs/
+#       "sshTarget": "admin@maxytest.local",  // user@host for ssh
+#       "sshPass":  "password"                // optional; uses sshpass if present
+#     }
+#   sshTarget supports inline port via "user@host:port" — script splits if present.
+#   sshPass omission → relies on existing ssh keys / agent.
+#
+# OUTPUT
+#   Per-device summary line on stdout.
+#   Detailed log: $HOME/.maxy/logs/installer-verify-<runId>.log (created if absent).
+#
+# DEPENDENCIES
+#   ssh (always), sshpass (only if any device uses sshPass), jq (always — the
+#   manifest is JSON; bash-only parse would be a CVE waiting to happen).
+
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+  echo "ERROR: missing argument <published-version>" >&2
+  echo "Usage: $0 <published-version>" >&2
+  echo "Example: $0 1.0.853" >&2
+  exit 2
+fi
+
+VERSION="$1"
+# Pattern-validate version before any remote-shell interpolation. The version
+# flows into `npx -y @rubytech/create-<brand>@$VERSION` over SSH; a stray
+# semicolon or backtick would land inside the remote shell. Operator-owned
+# input but the principle is validate-at-boundary.
+if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?$ ]]; then
+  echo "ERROR: invalid version '$VERSION' — expected semver (e.g. 1.0.853 or 1.0.853-rc.1)" >&2
+  exit 2
+fi
+
+MANIFEST="${MAXY_VERIFY_MANIFEST:-$HOME/.maxy-verify-devices.json}"
+RUN_ID="$(date +%Y%m%dT%H%M%SZ)-$$"
+SUMMARY_DIR="$HOME/.maxy/logs"
+SUMMARY_LOG="$SUMMARY_DIR/installer-verify-$RUN_ID.log"
+
+if [[ ! -f "$MANIFEST" ]]; then
+  cat >&2 <<EOF
+ERROR: device manifest not found at $MANIFEST.
+
+Create one with this shape (JSON array, one entry per device):
+[
+  {
+    "name":      "maxy-pi-test",
+    "brand":     "maxy",
+    "configDir": ".maxy",
+    "sshTarget": "admin@maxytest.local",
+    "sshPass":   "password"
+  }
+]
+
+Or set \$MAXY_VERIFY_MANIFEST to point elsewhere.
+Device list reference: ~/.claude/projects/-Users-neo-getmaxy/memory/reference_device_ssh.md
+EOF
+  exit 2
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "ERROR: jq is required (manifest is JSON)." >&2
+  echo "  macOS:    brew install jq" >&2
+  echo "  Ubuntu:   sudo apt-get install -y jq" >&2
+  exit 2
+fi
+
+mkdir -p "$SUMMARY_DIR"
+: > "$SUMMARY_LOG"
+
+# Resolve sshpass once: required only if any manifest entry has sshPass set.
+NEEDS_SSHPASS=$(jq -r 'any(.[]; .sshPass != null and .sshPass != "")' "$MANIFEST")
+if [[ "$NEEDS_SSHPASS" == "true" ]] && ! command -v sshpass >/dev/null 2>&1; then
+  echo "ERROR: manifest references sshPass but sshpass is not installed." >&2
+  echo "  macOS:    brew install hudochenkov/sshpass/sshpass" >&2
+  echo "  Ubuntu:   sudo apt-get install -y sshpass" >&2
+  exit 2
+fi
+
+DEVICE_COUNT=$(jq 'length' "$MANIFEST")
+FAILED=0
+
+# Common ssh hardening: short timeouts, no host-key prompt that would block
+# when adding a new Pi to the fleet, and StrictHostKeyChecking=accept-new so
+# fingerprints are recorded the first time but rejected on mismatch after.
+SSH_OPTS=(
+  -o "ConnectTimeout=10"
+  -o "ServerAliveInterval=15"
+  -o "ServerAliveCountMax=2"
+  -o "StrictHostKeyChecking=accept-new"
+  -o "BatchMode=no"
+)
+
+run_ssh() {
+  local target="$1" pass="$2"
+  shift 2
+  if [[ -n "$pass" ]]; then
+    SSHPASS="$pass" sshpass -e ssh "${SSH_OPTS[@]}" "$target" "$@"
+  else
+    ssh "${SSH_OPTS[@]}" "$target" "$@"
+  fi
+}
+
+# Allowed brand pattern matches what bundle.js validates: lowercase
+# alphanumeric, hyphens. Reject anything else before interpolating into
+# remote shell commands. configDir mirrors the brand convention (a leading
+# dot then the same character class), so the same shape passes through.
+# `$NAME` is interpolated into `--hostname "$NAME"` over SSH — same boundary
+# discipline applies; allow dots so it can carry mDNS hostnames like
+# `maxytest.local`, but never quote characters or shell metacharacters.
+ALLOWED='^[a-z0-9][a-z0-9-]*$'
+ALLOWED_HOSTNAME='^[a-zA-Z0-9][a-zA-Z0-9.-]*$'
+
+echo "installer-device-verify run=$RUN_ID version=$VERSION devices=$DEVICE_COUNT" | tee -a "$SUMMARY_LOG"
+
+for i in $(seq 0 $((DEVICE_COUNT - 1))); do
+  NAME=$(jq -r ".[$i].name"      "$MANIFEST")
+  BRAND=$(jq -r ".[$i].brand"     "$MANIFEST")
+  CONFIGDIR=$(jq -r ".[$i].configDir" "$MANIFEST")
+  TARGET=$(jq -r ".[$i].sshTarget" "$MANIFEST")
+  PASS=$(jq -r ".[$i].sshPass // \"\"" "$MANIFEST")
+
+  if [[ ! "$BRAND" =~ $ALLOWED ]]; then
+    echo "FAIL  $NAME — invalid brand '$BRAND' (must match $ALLOWED)" | tee -a "$SUMMARY_LOG"
+    FAILED=1
+    continue
+  fi
+
+  if [[ ! "$NAME" =~ $ALLOWED_HOSTNAME ]]; then
+    echo "FAIL  device name '$NAME' rejected — must match $ALLOWED_HOSTNAME" | tee -a "$SUMMARY_LOG"
+    FAILED=1
+    continue
+  fi
+
+  # configDir always begins with '.' (e.g. .maxy); strip the dot and validate
+  # the remainder with the same allowed-character class.
+  CD_TAIL="${CONFIGDIR#.}"
+  if [[ "$CD_TAIL" == "$CONFIGDIR" || ! "$CD_TAIL" =~ $ALLOWED ]]; then
+    echo "FAIL  $NAME — invalid configDir '$CONFIGDIR' (must be a leading dot + $ALLOWED)" | tee -a "$SUMMARY_LOG"
+    FAILED=1
+    continue
+  fi
+
+  echo "" | tee -a "$SUMMARY_LOG"
+  echo "[$NAME] brand=$BRAND target=$TARGET version=$VERSION" | tee -a "$SUMMARY_LOG"
+
+  # Step 1 — install. Run npx with auto-yes; redirect to the device's own
+  # install log path so the summary log on the operator side stays clean,
+  # and so the device-side log matches what reference_device_ssh.md would
+  # tail.
+  set +e
+  run_ssh "$TARGET" "$PASS" "npx -y @rubytech/create-$BRAND@$VERSION --hostname \"$NAME\"" >>"$SUMMARY_LOG" 2>&1
+  INSTALL_RC=$?
+  set -e
+
+  if [[ $INSTALL_RC -ne 0 ]]; then
+    echo "FAIL  $NAME — install exited $INSTALL_RC (see $SUMMARY_LOG)" | tee -a "$SUMMARY_LOG"
+    FAILED=1
+    continue
+  fi
+
+  # Step 2 — confirm CDP banner in the latest install log on the device.
+  # logs are at $HOME/<configDir>/logs/install-*.log; pick the newest by
+  # mtime (`ls -t`) and grep for the canonical success banner emitted by
+  # the installer at packages/create-maxy/src/index.ts.
+  REMOTE_CHECK=$(cat <<'REMOTE'
+set -euo pipefail
+LOG_DIR="$HOME/__CONFIGDIR__/logs"
+LATEST=$(ls -t "$LOG_DIR"/install-*.log 2>/dev/null | head -n1 || true)
+if [[ -z "${LATEST:-}" ]]; then
+  echo "no-install-log"
+  exit 1
+fi
+echo "log=$LATEST"
+if grep -F -q "Browser automation ready (CDP connected)" "$LATEST"; then
+  exit 0
+fi
+echo "banner-not-found"
+tail -n 30 "$LATEST"
+exit 1
+REMOTE
+)
+  REMOTE_CHECK="${REMOTE_CHECK//__CONFIGDIR__/$CONFIGDIR}"
+
+  set +e
+  run_ssh "$TARGET" "$PASS" "$REMOTE_CHECK" >>"$SUMMARY_LOG" 2>&1
+  CHECK_RC=$?
+  set -e
+
+  if [[ $CHECK_RC -eq 0 ]]; then
+    echo "OK    $NAME — CDP banner present" | tee -a "$SUMMARY_LOG"
+  else
+    echo "FAIL  $NAME — CDP banner missing (rc=$CHECK_RC, see $SUMMARY_LOG)" | tee -a "$SUMMARY_LOG"
+    FAILED=1
+  fi
+done
+
+echo "" | tee -a "$SUMMARY_LOG"
+if [[ $FAILED -eq 0 ]]; then
+  echo "PASS — all $DEVICE_COUNT devices installed and reported CDP banner" | tee -a "$SUMMARY_LOG"
+  echo "summary: $SUMMARY_LOG"
+  exit 0
+else
+  echo "FAIL — at least one device did not reach CDP banner; details in $SUMMARY_LOG" | tee -a "$SUMMARY_LOG"
+  echo "summary: $SUMMARY_LOG"
+  exit 1
+fi