@rubytech/create-realagent 1.0.852 → 1.0.853

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

@@ -1,163 +1,330 @@
-// Task 938 — acceptance grid for classifyPortHolder.
+// 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 +
-// configDir context → kind. Inputs in, decision out — no fs, no exec, no spawn.
+// 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 `--user-data-dir=PATH` (a real ownership claim) from a different
-// flag whose value happens to contain the profile path substring.
+// 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";
-const ALL_BRANDS = [".maxy", ".realagent", ".maxy-2", ".maxy-3", ".maxy-4"];
-const peers = (own) => ALL_BRANDS.filter(c => c !== own);
+// 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: "",
-        ownConfigDir: ".maxy",
-        peerConfigDirs: peers(".maxy"),
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
         getCmdline: () => { throw new Error("should not be called"); },
     });
     assert.equal(r.kind, "EMPTY");
 });
-test("OWN_BRAND: --user-data-dir=PATH single argv", () => {
+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,
-        ownConfigDir: ".maxy",
-        peerConfigDirs: peers(".maxy"),
+        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("OWN_BRAND: --user-data-dir PATH split across two argvs", () => {
+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,
-        ownConfigDir: ".maxy",
-        peerConfigDirs: peers(".maxy"),
+        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("PEER_BRAND: cmdline holds another known brand's profile path", () => {
+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,
-        ownConfigDir: ".maxy",
-        peerConfigDirs: peers(".maxy"),
+        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("UNRELATED: cmdline matches no known brand profile", () => {
-    const cmdline = cmd("/usr/bin/python3", "-m", "http.server", "9222");
+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,
-        ownConfigDir: ".maxy",
-        peerConfigDirs: peers(".maxy"),
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
         getCmdline: () => cmdline,
     });
     assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.holderType, "chromium");
     assert.equal(r.pid, 42);
-    assert.equal(r.cmdline, "/usr/bin/python3 -m http.server 9222");
-});
-test("UNRELATED: ssOutput non-empty but no pid= token", () => {
-    const r = classifyPortHolder({
-        ssOutput: "Recv-Q Send-Q  Local Address:Port  Peer Address:Port",
-        ownConfigDir: ".maxy",
-        peerConfigDirs: 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,
-        ownConfigDir: ".maxy",
-        peerConfigDirs: 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("UNRELATED: --user-data-dir absent (no profile claim)", () => {
+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 on their argv. They wouldn't be
-    // listening anyway, but if one ever showed up here we must classify as
-    // UNRELATED, never as OWN_BRAND on a substring fluke.
+    // 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,
-        ownConfigDir: ".maxy",
-        peerConfigDirs: peers(".maxy"),
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
         getCmdline: () => cmdline,
     });
     assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.holderType, "chromium");
 });
-test("substring boundary: own=.maxy must NOT match .maxy-2 cmdline", () => {
+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,
-        ownConfigDir: ".maxy",
-        peerConfigDirs: peers(".maxy"),
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
         getCmdline: () => cmdline,
     });
     assert.equal(r.kind, "PEER_BRAND");
     assert.equal(r.profilePath, "/home/neo/.maxy-2/chromium-profile");
 });
-test("substring boundary: own=.maxy-2 must NOT misclassify .maxy cmdline as own", () => {
+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,
-        ownConfigDir: ".maxy-2",
-        peerConfigDirs: peers(".maxy-2"),
+        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("argv-anchor safety: marker in --load-extension value must NOT classify as OWN_BRAND", () => {
-    // Adversarial case from review: 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.
+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,
-        ownConfigDir: ".maxy",
-        peerConfigDirs: peers(".maxy"),
+        ownBrand: MAXY,
+        peerBrands: peers(MAXY),
         getCmdline: () => cmdline,
     });
     assert.equal(r.kind, "UNRELATED");
 });
-test("ss header line containing 'pid=': last pid= wins", () => {
-    // If a future ss locale prepends header text containing the literal `pid=`
-    // (e.g., "Process 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");
+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,
-        ownConfigDir: ".maxy",
-        peerConfigDirs: peers(".maxy"),
-        getCmdline: pid => { assert.equal(pid, 42, "must pick the LISTEN row's pid, not the header's"); return cmdline; },
+        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

@@ -2457,12 +2457,13 @@ function installService() {
     // 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) reads `/proc/<pid>/cmdline` and matches on the
-    // user-data-dir profile path, not on `comm` regex. The previous
-    // `comm`-regex approach (`/Xtigervnc|websockify|chromium/`) failed on the
-    // laptop where Task 929 selects google-chrome-stable: comm is `chrome`,
-    // so the brand's own browser was misclassified UNRELATED and the install
-    // aborted against a port it could legitimately reclaim.
+    // 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
@@ -2471,9 +2472,42 @@ function installService() {
     //   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 peerConfigDirs = KNOWN_BRAND_HOSTNAMES
-        .filter(h => h !== BRAND.hostname)
-        .map(h => `.${h}`);
+    const ownBrand = {
+        configDir: BRAND.configDir,
+        vncDisplay: VNC_DISPLAY,
+        websockifyPort: WEBSOCKIFY_PORT_BRAND,
+    };
+    // Peer registry — load from payload/platform/config/brand-registry.json
+    // when present (Task 939+ bundles). Older bundles ship without the
+    // registry; in that case peerBrands stays empty. PEER_BRAND classification
+    // for Xtigervnc/websockify is a defence-in-depth case anyway (port sets
+    // are disjoint by Task 924), so the empty-list fallback is safe — peer
+    // chromium will fall through to UNRELATED, matching pre-Task 938 behaviour
+    // for the only realistic scenario (a stale peer browser on the wrong CDP
+    // port).
+    const peerBrands = (() => {
+        const registryPath = join(PAYLOAD_DIR, "platform", "config", "brand-registry.json");
+        if (!existsSync(registryPath)) {
+            logFile(`  [preflight] brand-registry.json not in payload — peer matching disabled`);
+            return [];
+        }
+        try {
+            const raw = JSON.parse(readFileSync(registryPath, "utf-8"));
+            const entries = [];
+            for (const b of raw.brands ?? []) {
+                if (b.hostname === BRAND.hostname)
+                    continue;
+                if (typeof b.configDir !== "string" || typeof b.vncDisplay !== "number" || typeof b.websockifyPort !== "number")
+                    continue;
+                entries.push({ configDir: b.configDir, vncDisplay: b.vncDisplay, websockifyPort: b.websockifyPort });
+            }
+            return entries;
+        }
+        catch (err) {
+            logFile(`  [preflight] brand-registry.json parse failed: ${err instanceof Error ? err.message : String(err)} — peer matching disabled`);
+            return [];
+        }
+    })();
     const ssReadHolder = (port) => {
         return execFileSync("ss", ["-tlnpH", `sport = :${port}`], {
             encoding: "utf-8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"],
@@ -2513,8 +2547,22 @@ function installService() {
         }
     };
     const classify = (ssOutput) => classifyPortHolder({
-        ssOutput, ownConfigDir: BRAND.configDir, peerConfigDirs, getCmdline: readCmdline,
+        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 {
@@ -2541,7 +2589,7 @@ function installService() {
             return;
         }
         if (r.kind === "OWN_BRAND" && r.pid !== undefined) {
-            logFile(`  [preflight] ${label}=${port} held by OWN brand process pid=${r.pid} profile=${r.profilePath} — sending SIGTERM`);
+            logFile(ownBrandAnnounceLine(label, port, r));
             killNoThrow(r.pid, "SIGTERM");
             sleepMs(300);
             const after = classify(ssReadOrAbort(label, port));

package/dist/preflight-port-classifier.js

@@ -1,32 +1,39 @@
 // Task 938 — pure classifier for the install-time port collision pre-flight.
-// Extracted from index.ts so the OWN_BRAND / PEER_BRAND / UNRELATED decision
-// can be unit-tested without ss(8), /proc, or kill(2). Mirrors the
-// peer-brand-detect.ts pattern: inputs in, classification out, no I/O.
+// 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.
+// module owns only the classification rule — inputs in, decision out.
 //
-// Rule, in order of precedence:
-//   1. ssOutput is empty                              → EMPTY
-//   2. No `pid=N` token in ssOutput                   → UNRELATED (pid undef)
-//   3. getCmdline(pid) throws                         → UNRELATED (cmdlineReadFailed)
-//   4. argv has --user-data-dir=PATH where PATH contains
-//      `/<ownConfigDir>/chromium-profile`             → OWN_BRAND
-//   5. same for any `<peerConfigDir>`                 → PEER_BRAND
-//   6. otherwise                                       → UNRELATED
+// 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
 //
-// Why argv parsing instead of substring matching: `cmdline.includes('/.maxy/
-// chromium-profile')` would false-match `--load-extension=/tmp/.maxy/chromium-
-// profile` (or any other flag whose value happens to contain the profile path
-// component). Anchoring on `--user-data-dir=` is the only signal that this
-// process actually owns that profile directory.
+// 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 or release prepends a
-// header line that contains `pid=` text, the first-match heuristic would
-// lift the wrong pid. The last `pid=` is always inside the LISTEN row's
-// `users:((…))` segment.
+// 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:
@@ -34,11 +41,9 @@
  * different flag whose value happens to contain `--user-data-dir=`.
  */
 export function classifyPortHolder(args) {
-    const { ssOutput, ownConfigDir, peerConfigDirs, getCmdline } = args;
+    const { ssOutput, ownBrand, peerBrands, getCmdline } = args;
     if (ssOutput.trim() === "")
         return { kind: "EMPTY" };
-    // Take the LAST pid= match. ss -tlnpH puts the LISTEN row (which contains
-    // `users:((…,pid=N,fd=…))`) last, so the last pid= is always the listener.
     const pidMatches = [...ssOutput.matchAll(/pid=(\d+)/g)];
     if (pidMatches.length === 0)
         return { kind: "UNRELATED" };
@@ -50,38 +55,168 @@ export function classifyPortHolder(args) {
     catch {
         return { kind: "UNRELATED", pid, cmdlineReadFailed: true };
     }
-    // Pretty cmdline (NULs → spaces) for log output. The argv-aware matching
-    // operates on the raw NUL-separated form.
     const prettyCmdline = cmdline.replace(/\0/g, " ").trim();
     const argv = cmdline.split("\0").filter(s => s.length > 0);
-    const userDataDir = findUserDataDir(argv);
+    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) {
-        return { kind: "UNRELATED", pid, cmdline: prettyCmdline };
+        // 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 = `/${ownConfigDir}/chromium-profile`;
+    const ownSuffix = `/${ownBrand.configDir}/chromium-profile`;
     if (userDataDir.includes(ownSuffix)) {
-        return { kind: "OWN_BRAND", pid, cmdline: prettyCmdline, profilePath: userDataDir };
+        return {
+            kind: "OWN_BRAND", pid, cmdline: prettyCmdline,
+            profilePath: userDataDir, holderType: "chromium",
+        };
     }
-    for (const peerCD of peerConfigDirs) {
-        const peerSuffix = `/${peerCD}/chromium-profile`;
+    for (const peer of peerBrands) {
+        const peerSuffix = `/${peer.configDir}/chromium-profile`;
         if (userDataDir.includes(peerSuffix)) {
-            return { kind: "PEER_BRAND", pid, cmdline: prettyCmdline, profilePath: userDataDir };
+            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 };
+    return {
+        kind: "UNRELATED", pid, cmdline: prettyCmdline,
+        vncDisplay: display, holderType: "xtigervnc",
+    };
 }
-// Find the value of `--user-data-dir`, supporting both `--user-data-dir=PATH`
-// (single argv) and `--user-data-dir PATH` (split across two argvs). Returns
-// null if the flag is absent.
-function findUserDataDir(argv) {
-    const FLAG = "--user-data-dir";
-    const PREFIX = `${FLAG}=`;
+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)
+        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.852",
+  "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/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