@rubytech/create-siteoffice-code 0.1.256

package/dist/__tests__/plugin-install.test.js

@@ -0,0 +1,123 @@
+// Unit tests for the installer's plugin-install pure functions.
+// Tests are ephemeral per the sprint workflow — they prove behaviour
+// during the sprint; the installer's runtime exercise on a real Pi is the
+// permanent verification artifact.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parsePluginList, computeInstallActions, parseExternalPlugins, } from "../lib/plugin-install.js";
+test("parsePluginList extracts name@marketplace tuples", () => {
+    const stdout = `
+  ❯ work@maxy-platform
+    Version: 0.1.0
+    Scope: local
+
+  ❯ telegram@claude-plugins-official
+    Version: 1.2.3
+`;
+    const out = parsePluginList(stdout);
+    assert.deepEqual(out, [
+        { name: "work", marketplace: "maxy-platform" },
+        { name: "telegram", marketplace: "claude-plugins-official" },
+    ]);
+});
+test("parsePluginList returns empty array for empty stdout", () => {
+    assert.deepEqual(parsePluginList(""), []);
+    assert.deepEqual(parsePluginList("No plugins installed.\n"), []);
+});
+// `dirSrc` is the directory-source-marketplace discriminator passed as the
+// third argument. maxy-platform is directory-source; claude-plugins-official
+// is a remote (GitHub) marketplace that keeps version-pinned idempotence.
+const dirSrc = new Set(["maxy-platform"]);
+test("computeInstallActions: every desired plugin needs installing when none present", () => {
+    const desired = [
+        { name: "admin", marketplace: "maxy-platform" },
+        { name: "telegram", marketplace: "claude-plugins-official" },
+    ];
+    const { toInstall, toResync, alreadyInstalled } = computeInstallActions(desired, [], dirSrc);
+    assert.equal(toInstall.length, 2);
+    assert.equal(toResync.length, 0);
+    assert.equal(alreadyInstalled.length, 0);
+});
+test("computeInstallActions: directory-source plugin already installed goes to resync, not skip", () => {
+    const desired = [
+        { name: "admin", marketplace: "maxy-platform" },
+        { name: "telegram", marketplace: "claude-plugins-official" },
+    ];
+    const installed = [
+        { name: "admin", marketplace: "maxy-platform" },
+        { name: "telegram", marketplace: "claude-plugins-official" },
+    ];
+    const { toInstall, toResync, alreadyInstalled } = computeInstallActions(desired, installed, dirSrc);
+    // admin's directory source changes in place with no version bump, so it must
+    // be re-synced even though it is already in `plugin list`. The remote
+    // telegram stays idempotent-skipped.
+    assert.deepEqual(toInstall.map(p => p.name), []);
+    assert.deepEqual(toResync.map(p => p.name), ["admin"]);
+    assert.deepEqual(alreadyInstalled.map(p => p.name), ["telegram"]);
+});
+test("computeInstallActions: full directory-marketplace set resyncs when every plugin already installed", () => {
+    const desired = [
+        { name: "admin", marketplace: "maxy-platform" },
+        { name: "work", marketplace: "maxy-platform" },
+    ];
+    const installed = [
+        { name: "admin", marketplace: "maxy-platform" },
+        { name: "work", marketplace: "maxy-platform" },
+    ];
+    const { toInstall, toResync, alreadyInstalled } = computeInstallActions(desired, installed, dirSrc);
+    assert.deepEqual(toResync.map(p => p.name), ["admin", "work"]);
+    assert.equal(toInstall.length, 0);
+    assert.equal(alreadyInstalled.length, 0);
+});
+test("computeInstallActions: remote plugin already installed stays idempotent-skipped", () => {
+    const desired = [{ name: "telegram", marketplace: "claude-plugins-official" }];
+    const installed = [{ name: "telegram", marketplace: "claude-plugins-official" }];
+    const { toInstall, toResync, alreadyInstalled } = computeInstallActions(desired, installed, dirSrc);
+    assert.equal(toInstall.length, 0);
+    assert.equal(toResync.length, 0);
+    assert.deepEqual(alreadyInstalled.map(p => p.name), ["telegram"]);
+});
+test("computeInstallActions: directory-source plugin not yet installed goes to install (fresh build is clean)", () => {
+    const desired = [{ name: "admin", marketplace: "maxy-platform" }];
+    const { toInstall, toResync, alreadyInstalled } = computeInstallActions(desired, [], dirSrc);
+    assert.deepEqual(toInstall.map(p => p.name), ["admin"]);
+    assert.equal(toResync.length, 0);
+    assert.equal(alreadyInstalled.length, 0);
+});
+test("computeInstallActions: name-only match on a remote marketplace skips install (legacy install state)", () => {
+    const desired = [{ name: "telegram", marketplace: "claude-plugins-official" }];
+    const installed = [{ name: "telegram", marketplace: "" }];
+    const { toInstall, toResync, alreadyInstalled } = computeInstallActions(desired, installed, dirSrc);
+    assert.equal(toInstall.length, 0);
+    assert.equal(toResync.length, 0);
+    assert.equal(alreadyInstalled.length, 1);
+});
+test("computeInstallActions: name-only legacy match on a directory marketplace still resyncs", () => {
+    const desired = [{ name: "admin", marketplace: "maxy-platform" }];
+    const installed = [{ name: "admin", marketplace: "" }];
+    const { toInstall, toResync, alreadyInstalled } = computeInstallActions(desired, installed, dirSrc);
+    assert.equal(toInstall.length, 0);
+    assert.deepEqual(toResync.map(p => p.name), ["admin"]);
+    assert.equal(alreadyInstalled.length, 0);
+});
+test("parseExternalPlugins: undefined returns []", () => {
+    assert.deepEqual(parseExternalPlugins(undefined), []);
+    assert.deepEqual(parseExternalPlugins(null), []);
+});
+test("parseExternalPlugins: well-formed array round-trips", () => {
+    const raw = [
+        { name: "telegram", marketplace: "claude-plugins-official", channelPlugin: true },
+        { name: "discord", marketplace: "claude-plugins-official" },
+    ];
+    const out = parseExternalPlugins(raw);
+    assert.deepEqual(out, [
+        { name: "telegram", marketplace: "claude-plugins-official", channelPlugin: true },
+        { name: "discord", marketplace: "claude-plugins-official" },
+    ]);
+});
+test("parseExternalPlugins: missing marketplace throws", () => {
+    assert.throws(() => parseExternalPlugins([{ name: "telegram" }]));
+});
+test("parseExternalPlugins: missing name throws", () => {
+    assert.throws(() => parseExternalPlugins([{ marketplace: "x" }]));
+});

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

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

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

@@ -0,0 +1,330 @@
+// acceptance grid for classifyPortHolder (chromium argv-anchor).
+// 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 (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. 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 (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 (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");
+});