@rubytech/create-realagent 1.0.854 → 1.0.856

package/dist/__tests__/account-id-env.test.js

@@ -0,0 +1,47 @@
+// Task 955 — acceptance gate for ACCOUNT_ID stamping in the brand systemd unit.
+//
+// Two invariants this test protects:
+//   (a) buildMaxyUnitFile emits a literal `Environment=ACCOUNT_ID=<uuid>` line
+//       in the [Service] block when accountId is provided. Pi recovery via
+//       `npx -y @rubytech/create-maxy@latest` depends on this line landing —
+//       without it, process.env.ACCOUNT_ID is undefined and the
+//       writeNodeWithEdges gate rejects every CF-setup graph write at
+//       cloudflare-task-tracker.ts:187/326/347/559.
+//   (b) buildMaxyUnitFile throws on an empty accountId. Falling through with
+//       "" would emit a unit with no ACCOUNT_ID line; the boot validator at
+//       platform/ui/server/index.ts would then FATAL reason=missing on every
+//       restart, surfacing the same regression class behind a different log
+//       prefix. Throwing at build time aborts the install loud, before the
+//       broken unit is written.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildMaxyUnitFile } from "../port-resolution.js";
+const VALID_UUID = "12345678-9abc-def0-1234-56789abcdef0";
+function callBuildUnit(accountId) {
+    return buildMaxyUnitFile({
+        productName: "Maxy",
+        brandHostname: "maxy",
+        neo4jDedicated: false,
+        installDir: "/home/me/maxy",
+        persistDir: "/home/me/.maxy",
+        port: 19200,
+        maxyUiInternalPort: 19201,
+        vncDisplay: 99,
+        rfbPort: 5900,
+        websockifyPort: 6080,
+        cdpPort: 9222,
+        chromiumBin: "/usr/bin/chromium",
+        accountId,
+    });
+}
+test("buildMaxyUnitFile emits Environment=ACCOUNT_ID=<uuid> for a valid accountId", () => {
+    const unit = callBuildUnit(VALID_UUID);
+    assert.match(unit, /^Environment=ACCOUNT_ID=12345678-9abc-def0-1234-56789abcdef0$/m, "ACCOUNT_ID line missing or malformed");
+    // Placement matters: identity (NODE_ENV → ACCOUNT_ID → PORT) so the most
+    // fundamental brand identity sits next to the env that selects the brand
+    // runtime. Anchored regex against the three adjacent lines.
+    assert.match(unit, /Environment=NODE_ENV=production\nEnvironment=ACCOUNT_ID=12345678-9abc-def0-1234-56789abcdef0\nEnvironment=PORT=19200/, "ACCOUNT_ID line is not placed between NODE_ENV and PORT");
+});
+test("buildMaxyUnitFile throws when accountId is empty", () => {
+    assert.throws(() => callBuildUnit(""), /accountId is required/, "expected throw on empty accountId, did not throw");
+});

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

@@ -33,6 +33,7 @@ function makeUnitFile(port, internal) {
         websockifyPort: 6080,
         cdpPort: 9222,
         chromiumBin: "/usr/bin/chromium",
+        accountId: "00000000-0000-0000-0000-000000000001",
     });
 }
 function makeEdgeFile(edgePort) {

package/dist/index.js

@@ -2130,6 +2130,33 @@ function installTunnelScripts() {
     createTunnelSymlink(listLink, listSrc);
 }
 // ---------------------------------------------------------------------------
+// Account discovery (shared between installService + installCrons)
+//
+// Task 955 — `installService` stamps `Environment=ACCOUNT_ID=` into the brand
+// systemd unit so the writeNodeWithEdges gate has a non-undefined identity to
+// compare against; `installCrons` needs the same value to scope cron stdout
+// to the per-account log dir + stamp ACCOUNT_ID into the cron entry env.
+// Both pull from `INSTALL_DIR/data/accounts/<uuid>/account.json` written by
+// seed-neo4j.sh during setupAccount(). One reader, one shape, one source of
+// truth — without sharing, the two callers would drift on classification of
+// `corrupt account.json` (one might count it, the other might not) and the
+// gate would reject writes the cron's "scoped" log was already happily
+// publishing under that uuid.
+// ---------------------------------------------------------------------------
+function resolveInstallAccountId() {
+    const accountsDir = join(INSTALL_DIR, "data/accounts");
+    if (!existsSync(accountsDir))
+        return "";
+    try {
+        for (const d of readdirSync(accountsDir)) {
+            if (existsSync(join(accountsDir, d, "account.json")))
+                return d;
+        }
+    }
+    catch { /* directory unreadable */ }
+    return "";
+}
+// ---------------------------------------------------------------------------
 // Cron Registration
 //
 // Registers platform cron jobs (heartbeat, email-fetch, email-auto-respond).
@@ -2144,21 +2171,9 @@ function installCrons() {
         return;
     const nodeBin = spawnSync("which", ["node"], { encoding: "utf-8" }).stdout.trim() || "/usr/bin/node";
     const platformRoot = join(INSTALL_DIR, "platform");
-    // Discover the account — required for log directory and ACCOUNT_ID env
+    // Account discovery shared with installService — see resolveInstallAccountId.
+    const accountId = resolveInstallAccountId();
     const accountsDir = join(INSTALL_DIR, "data/accounts");
-    let accountId = "";
-    if (existsSync(accountsDir)) {
-        try {
-            const dirs = readdirSync(accountsDir);
-            for (const d of dirs) {
-                if (existsSync(join(accountsDir, d, "account.json"))) {
-                    accountId = d;
-                    break;
-                }
-            }
-        }
-        catch { /* directory unreadable */ }
-    }
     if (!accountId) {
         console.error("  Cron jobs: skipped — no account found. Crons will register on the next install after account creation.");
         logFile("  cron registration skipped: no account directory with account.json found");
@@ -2450,9 +2465,15 @@ function installService() {
     // Mirrors paths.ts and vnc.sh so all four sites compute the same numbers
     // regardless of which one reads brand.json first.
     const VNC_OFFSET = VNC_DISPLAY - 99;
-    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;
+    // Parenthesise the deterministic derivation. Operator-precedence already
+    // groups (offset + base) ahead of nullish-coalesce, so this is purely a
+    // textual change for readability and to satisfy Task 954's grep audit
+    // (the runtime path was the real silent default; these are install-time
+    // deterministic fallbacks but the audit is a single regex over the
+    // codebase).
+    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/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.
@@ -2640,6 +2661,18 @@ function installService() {
     checkInstallPortFree("rfbPort", RFB_PORT);
     checkInstallPortFree("websockifyPort", WEBSOCKIFY_PORT_BRAND);
     checkInstallPortFree("cdpPort", CDP_PORT_BRAND);
+    // Task 955 — ACCOUNT_ID stamped into the brand unit so the writeNodeWithEdges
+    // gate at platform/lib/graph-write/src/index.ts:170 has a real identity to
+    // compare against (instead of process.env.ACCOUNT_ID === undefined). Resolved
+    // here AFTER setupAccount() ran upstream — seed-neo4j.sh wrote account.json,
+    // so an empty resolution at this point is a corrupted install (e.g. the seed
+    // failed silently, or accounts/ was wiped between setup and unit-write).
+    const installAccountId = resolveInstallAccountId();
+    if (!installAccountId) {
+        throw new Error(`installService: no account discovered at ${INSTALL_DIR}/data/accounts/<uuid>/account.json — ` +
+            `setupAccount() (seed-neo4j.sh) should have created one. Refusing to write a systemd unit ` +
+            `without ACCOUNT_ID; the boot validator would FATAL on every restart (Task 955).`);
+    }
     const serviceFile = buildMaxyUnitFile({
         productName: BRAND.productName,
         brandHostname: BRAND.hostname,
@@ -2653,6 +2686,7 @@ function installService() {
         websockifyPort: WEBSOCKIFY_PORT_BRAND,
         cdpPort: CDP_PORT_BRAND,
         chromiumBin: RESOLVED_CHROMIUM_BIN, // Task 929
+        accountId: installAccountId, // Task 955
     });
     writeFileSync(join(serviceDir, BRAND.serviceName), serviceFile);
     // Task 647 — the edge service: always-on front door that owns the public

package/dist/port-resolution.js

@@ -70,6 +70,14 @@ export function resolveInstallPortFromFs(opts) {
     });
 }
 export function buildMaxyUnitFile(o) {
+    if (!o.accountId) {
+        // Caller (installService) must resolve the on-disk accountId before
+        // calling. Falling through with an empty value would emit a unit file
+        // with no Environment=ACCOUNT_ID line — bootValidator would FATAL on
+        // every restart with reason=missing. Throw at build time so the install
+        // aborts loudly instead of bricking the boot loop.
+        throw new Error("buildMaxyUnitFile: accountId is required — caller must resolve the on-disk account UUID before stamping the systemd unit (Task 955).");
+    }
     const neo4jServiceDep = o.neo4jDedicated
         ? `neo4j-${o.brandHostname}.service`
         : "neo4j.service";
@@ -91,6 +99,7 @@ WatchdogSec=30
 TimeoutStartSec=60
 TimeoutStopSec=10
 Environment=NODE_ENV=production
+Environment=ACCOUNT_ID=${o.accountId}
 Environment=PORT=${o.port}
 Environment=MAXY_UI_INTERNAL_PORT=${o.maxyUiInternalPort}
 Environment=HOSTNAME=127.0.0.1

package/package.json

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

package/payload/platform/lib/account-enumeration/dist/__tests__/validate-env.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validate-env.test.d.ts.map

package/payload/platform/lib/account-enumeration/dist/__tests__/validate-env.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-env.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/validate-env.test.ts"],"names":[],"mappings":""}

package/payload/platform/lib/account-enumeration/dist/__tests__/validate-env.test.js

@@ -0,0 +1,55 @@
+"use strict";
+// Task 955 — acceptance gate for the env-vs-disk validator. Pure-function
+// shape (no I/O, no env read, no exit) keeps the test fast and lets the
+// caller (platform/ui/server/index.ts) own the side-effects (console.error +
+// process.exit). The four cases cover every observable boot state — missing,
+// no-on-disk-account, mismatch, ok — with no fallback path.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const index_js_1 = require("../index.js");
+const UUID_A = "11111111-2222-3333-4444-555555555555";
+const UUID_B = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+(0, node_test_1.default)("validateAccountIdEnv ok when env matches a disk account", () => {
+    const result = (0, index_js_1.validateAccountIdEnv)(UUID_A, [UUID_A]);
+    strict_1.default.deepEqual(result, { ok: true, envId: UUID_A, diskIds: [UUID_A] });
+});
+(0, node_test_1.default)("validateAccountIdEnv FATAL reason=missing when env is undefined", () => {
+    const result = (0, index_js_1.validateAccountIdEnv)(undefined, [UUID_A]);
+    strict_1.default.equal(result.ok, false);
+    strict_1.default.equal(result.ok ? null : result.reason, "missing");
+    strict_1.default.equal(result.envId, null);
+});
+(0, node_test_1.default)("validateAccountIdEnv FATAL reason=missing when env is the empty string", () => {
+    // Empty string is the systemd shape when `Environment=ACCOUNT_ID=` lands
+    // without a value (e.g. an installer regression that interpolates an empty
+    // template variable). Same FATAL classification as undefined — we never
+    // accept a falsy env value and silently degrade.
+    const result = (0, index_js_1.validateAccountIdEnv)("", [UUID_A]);
+    strict_1.default.equal(result.ok, false);
+    strict_1.default.equal(result.ok ? null : result.reason, "missing");
+});
+(0, node_test_1.default)("validateAccountIdEnv FATAL reason=no-on-disk-account when disk is empty", () => {
+    const result = (0, index_js_1.validateAccountIdEnv)(UUID_A, []);
+    strict_1.default.equal(result.ok, false);
+    strict_1.default.equal(result.ok ? null : result.reason, "no-on-disk-account");
+    strict_1.default.equal(result.envId, UUID_A);
+    strict_1.default.deepEqual(result.diskIds, []);
+});
+(0, node_test_1.default)("validateAccountIdEnv FATAL reason=mismatch when env not in disk list", () => {
+    const result = (0, index_js_1.validateAccountIdEnv)(UUID_A, [UUID_B]);
+    strict_1.default.equal(result.ok, false);
+    strict_1.default.equal(result.ok ? null : result.reason, "mismatch");
+    strict_1.default.equal(result.envId, UUID_A);
+    strict_1.default.deepEqual(result.diskIds, [UUID_B]);
+});
+(0, node_test_1.default)("validateAccountIdEnv ok when env matches one of multiple disk accounts", () => {
+    // Phase 0 invariant is single-account, but the validator is shape-agnostic;
+    // future multi-account expansion should not require a code change here.
+    const result = (0, index_js_1.validateAccountIdEnv)(UUID_B, [UUID_A, UUID_B]);
+    strict_1.default.equal(result.ok, true);
+});
+//# sourceMappingURL=validate-env.test.js.map

package/payload/platform/lib/account-enumeration/dist/__tests__/validate-env.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-env.test.js","sourceRoot":"","sources":["../../src/__tests__/validate-env.test.ts"],"names":[],"mappings":"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"}

package/payload/platform/lib/account-enumeration/dist/index.d.ts

@@ -20,4 +20,30 @@ export declare function getAccountsDirFromEnv(): string;
  * is a deliberate boot-time invariant (see module doc).
  */
 export declare function _resetEnumerationCache(): void;
+/**
+ * Task 955 — boot-time env-vs-disk validator. Compares `process.env.ACCOUNT_ID`
+ * (stamped by the brand systemd unit's `Environment=ACCOUNT_ID=` line) against
+ * the on-disk account set returned by `enumerateValidAccountIds`. The Hono
+ * server calls this once at boot before binding the listener; on FATAL it
+ * emits a structured `[graph-health] account-id-env FATAL` line and exits 1
+ * so systemd's restart loop surfaces the misconfiguration in journalctl.
+ *
+ * Pure function — no I/O, no env reads, no exits — caller passes both inputs.
+ * Reasons enumerate the four observable boot states (success + three failures)
+ * with no fallback path; the writeNodeWithEdges gate cannot trust an env that
+ * does not match disk, and silently degrading would re-create the silent-leak
+ * class the gate exists to close (`.docs/neo4j.md` "Account isolation invariant").
+ */
+export type AccountIdEnvValidationFailureReason = "missing" | "no-on-disk-account" | "mismatch";
+export type AccountIdEnvValidation = {
+    ok: true;
+    envId: string;
+    diskIds: string[];
+} | {
+    ok: false;
+    reason: AccountIdEnvValidationFailureReason;
+    envId: string | null;
+    diskIds: string[];
+};
+export declare function validateAccountIdEnv(envValue: string | undefined, diskIds: string[]): AccountIdEnvValidation;
 //# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/account-enumeration/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6BA;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAgCtE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAS9C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6BA;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAgCtE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAS9C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,mCAAmC,GAC3C,SAAS,GACT,oBAAoB,GACpB,UAAU,CAAC;AAEf,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GAC9C;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,mCAAmC,CAAC;IAC5C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEN,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,MAAM,EAAE,GAChB,sBAAsB,CAWxB"}

package/payload/platform/lib/account-enumeration/dist/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enumerateValidAccountIds = enumerateValidAccountIds;
 exports.getAccountsDirFromEnv = getAccountsDirFromEnv;
 exports._resetEnumerationCache = _resetEnumerationCache;
+exports.validateAccountIdEnv = validateAccountIdEnv;
 /**
  * account-enumeration — single source of truth for "which accountIds are
  * provisioned on disk for this install?".
@@ -93,4 +94,16 @@ function getAccountsDirFromEnv() {
 function _resetEnumerationCache() {
     cache.clear();
 }
+function validateAccountIdEnv(envValue, diskIds) {
+    if (!envValue) {
+        return { ok: false, reason: "missing", envId: null, diskIds };
+    }
+    if (diskIds.length === 0) {
+        return { ok: false, reason: "no-on-disk-account", envId: envValue, diskIds };
+    }
+    if (!diskIds.includes(envValue)) {
+        return { ok: false, reason: "mismatch", envId: envValue, diskIds };
+    }
+    return { ok: true, envId: envValue, diskIds };
+}
 //# sourceMappingURL=index.js.map

package/payload/platform/lib/account-enumeration/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAoCA,4DAgCC;AAUD,sDASC;AAMD,wDAEC;AA/FD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qCAAoD;AACpD,yCAAoC;AAEpC,MAAM,OAAO,GACX,iEAAiE,CAAC;AAEpE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;AAE1C;;;;;;GAMG;AACH,SAAgB,wBAAwB,CAAC,WAAmB;IAC1D,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACtC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IAExC,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,IAAA,qBAAW,EAAC,WAAW,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrD,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;YAC3B,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QAClC,MAAM,UAAU,GAAG,IAAA,mBAAO,EAAC,WAAW,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QAC9D,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,IAAA,sBAAY,EAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;YAC9C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;YACjD,IAAI,IAAI,KAAK,QAAQ;gBAAE,SAAS;YAChC,kEAAkE;YAClE,kCAAkC;QACpC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAC9B,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,qBAAqB;IACnC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAC5C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACb,4EAA4E;YAC1E,kFAAkF,CACrF,CAAC;IACJ,CAAC;IACD,OAAO,IAAA,mBAAO,EAAC,IAAI,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,SAAgB,sBAAsB;IACpC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/payload/platform/lib/account-enumeration/src/__tests__/validate-env.test.ts

@@ -0,0 +1,57 @@
+// Task 955 — acceptance gate for the env-vs-disk validator. Pure-function
+// shape (no I/O, no env read, no exit) keeps the test fast and lets the
+// caller (platform/ui/server/index.ts) own the side-effects (console.error +
+// process.exit). The four cases cover every observable boot state — missing,
+// no-on-disk-account, mismatch, ok — with no fallback path.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { validateAccountIdEnv } from "../index.js";
+
+const UUID_A = "11111111-2222-3333-4444-555555555555";
+const UUID_B = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+
+test("validateAccountIdEnv ok when env matches a disk account", () => {
+  const result = validateAccountIdEnv(UUID_A, [UUID_A]);
+  assert.deepEqual(result, { ok: true, envId: UUID_A, diskIds: [UUID_A] });
+});
+
+test("validateAccountIdEnv FATAL reason=missing when env is undefined", () => {
+  const result = validateAccountIdEnv(undefined, [UUID_A]);
+  assert.equal(result.ok, false);
+  assert.equal(result.ok ? null : result.reason, "missing");
+  assert.equal(result.envId, null);
+});
+
+test("validateAccountIdEnv FATAL reason=missing when env is the empty string", () => {
+  // Empty string is the systemd shape when `Environment=ACCOUNT_ID=` lands
+  // without a value (e.g. an installer regression that interpolates an empty
+  // template variable). Same FATAL classification as undefined — we never
+  // accept a falsy env value and silently degrade.
+  const result = validateAccountIdEnv("", [UUID_A]);
+  assert.equal(result.ok, false);
+  assert.equal(result.ok ? null : result.reason, "missing");
+});
+
+test("validateAccountIdEnv FATAL reason=no-on-disk-account when disk is empty", () => {
+  const result = validateAccountIdEnv(UUID_A, []);
+  assert.equal(result.ok, false);
+  assert.equal(result.ok ? null : result.reason, "no-on-disk-account");
+  assert.equal(result.envId, UUID_A);
+  assert.deepEqual(result.diskIds, []);
+});
+
+test("validateAccountIdEnv FATAL reason=mismatch when env not in disk list", () => {
+  const result = validateAccountIdEnv(UUID_A, [UUID_B]);
+  assert.equal(result.ok, false);
+  assert.equal(result.ok ? null : result.reason, "mismatch");
+  assert.equal(result.envId, UUID_A);
+  assert.deepEqual(result.diskIds, [UUID_B]);
+});
+
+test("validateAccountIdEnv ok when env matches one of multiple disk accounts", () => {
+  // Phase 0 invariant is single-account, but the validator is shape-agnostic;
+  // future multi-account expansion should not require a code change here.
+  const result = validateAccountIdEnv(UUID_B, [UUID_A, UUID_B]);
+  assert.equal(result.ok, true);
+});

package/payload/platform/lib/account-enumeration/src/index.ts

@@ -94,3 +94,47 @@ export function getAccountsDirFromEnv(): string {
 export function _resetEnumerationCache(): void {
   cache.clear();
 }
+
+/**
+ * Task 955 — boot-time env-vs-disk validator. Compares `process.env.ACCOUNT_ID`
+ * (stamped by the brand systemd unit's `Environment=ACCOUNT_ID=` line) against
+ * the on-disk account set returned by `enumerateValidAccountIds`. The Hono
+ * server calls this once at boot before binding the listener; on FATAL it
+ * emits a structured `[graph-health] account-id-env FATAL` line and exits 1
+ * so systemd's restart loop surfaces the misconfiguration in journalctl.
+ *
+ * Pure function — no I/O, no env reads, no exits — caller passes both inputs.
+ * Reasons enumerate the four observable boot states (success + three failures)
+ * with no fallback path; the writeNodeWithEdges gate cannot trust an env that
+ * does not match disk, and silently degrading would re-create the silent-leak
+ * class the gate exists to close (`.docs/neo4j.md` "Account isolation invariant").
+ */
+export type AccountIdEnvValidationFailureReason =
+  | "missing"
+  | "no-on-disk-account"
+  | "mismatch";
+
+export type AccountIdEnvValidation =
+  | { ok: true; envId: string; diskIds: string[] }
+  | {
+      ok: false;
+      reason: AccountIdEnvValidationFailureReason;
+      envId: string | null;
+      diskIds: string[];
+    };
+
+export function validateAccountIdEnv(
+  envValue: string | undefined,
+  diskIds: string[],
+): AccountIdEnvValidation {
+  if (!envValue) {
+    return { ok: false, reason: "missing", envId: null, diskIds };
+  }
+  if (diskIds.length === 0) {
+    return { ok: false, reason: "no-on-disk-account", envId: envValue, diskIds };
+  }
+  if (!diskIds.includes(envValue)) {
+    return { ok: false, reason: "mismatch", envId: envValue, diskIds };
+  }
+  return { ok: true, envId: envValue, diskIds };
+}

package/payload/platform/plugins/cloudflare/references/manual-setup.md

@@ -43,6 +43,8 @@ Mode B skips Steps 1–5 of this runbook entirely — the user receives a token
 
 The manual walkthrough below exists so an operator can execute every step by hand when the system is broken or the automation is absent. For a normal setup — and for validating that the runbook's steps produce a working tunnel end-to-end — use the two scripts at `platform/plugins/cloudflare/scripts/`:
 
+> **Task 954 — `list-cf-domains` is brand-arg + brand.json driven.** `list-cf-domains.sh` requires the brand name as `$1`; the .ts helper reads `cdpPort` from `${MAXY_PLATFORM_ROOT}/config/brand.json` (no silent default). Missing brand arg, missing brand.json, or missing `cdpPort` field each exit 1 with a named `reason=` token, and the route maps them to `field=config` (no Retry button — fix the install instead).
+
 ```
 setup-tunnel.sh <brand> <port> <hostname> [<hostname> ...]
 ```

package/payload/platform/plugins/cloudflare/scripts/list-cf-domains.sh

@@ -5,11 +5,19 @@
 # token on stderr tagged `[list-cf-domains]`.
 #
 # Usage:
-#   list-cf-domains.sh [<brand>]
+#   list-cf-domains.sh <brand>
 #
-# The brand arg (default: maxy) names the `${HOME}/.${BRAND}/logs/` directory
-# where selector-drift body dumps land. The script does not read brand.json —
-# the directory is the only brand-derived path it needs.
+# Task 954: brand arg is REQUIRED — the prior silent default (string
+# fallback to "maxy" when $1 was empty) made every non-Maxy brand's CF
+# setup form fail on first use because the wrapper's child node helper
+# read the Maxy CDP port from a hardcoded fallback. Missing arg now exits
+# 1 with `phase=error reason=brand-arg-missing`.
+#
+# The wrapper also resolves and exports MAXY_PLATFORM_ROOT from its own
+# script location so the .ts helper can read `<root>/config/brand.json` for
+# the brand's `cdpPort` (Task 924's source of truth). Direct-SSH invocation
+# works because the script lives at `<install>/platform/plugins/cloudflare/
+# scripts/`, making platform root three dirs up from the resolved script.
 #
 # Runtime: Node 22's `--experimental-strip-types` runs the .ts helper
 # directly, so no tsx / playwright / ws dependency exists.
@@ -24,16 +32,29 @@ set -euo pipefail
 # Resolve symlinks before dirname — ~/list-cf-domains.sh is installed as a
 # symlink into $HOME, so the raw BASH_SOURCE[0] points at $HOME, not the
 # scripts directory where _stream-log.sh lives.
-source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/_stream-log.sh"
+SCRIPT_DIR="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")"
+source "${SCRIPT_DIR}/_stream-log.sh"
 require_stream_log_path list-cf-domains
 
-BRAND="${1:-maxy}"
+if [ "$#" -lt 1 ] || [ -z "${1:-}" ]; then
+  phase_line list-cf-domains phase=error reason=brand-arg-missing
+  exit 1
+fi
+
+BRAND="${1}"
 CONFIG_DIR=".${BRAND}"
 mkdir -p "${HOME}/${CONFIG_DIR}/logs"
 
+# MAXY_PLATFORM_ROOT is set by the systemd service when the admin server
+# spawns this script via runFormSpawn. Direct-SSH invocation has no such env
+# so derive it from the resolved script location: scripts/ → cloudflare/ →
+# plugins/ → platform → install root (three dirs up).
+if [ -z "${MAXY_PLATFORM_ROOT:-}" ]; then
+  MAXY_PLATFORM_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+fi
+
 phase_line list-cf-domains phase=script-start brand="${BRAND}" config_dir="${CONFIG_DIR}"
 
-SCRIPT_DIR="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")"
 TS_ENTRY="${SCRIPT_DIR}/list-cf-domains.ts"
 
 if [ ! -f "${TS_ENTRY}" ]; then
@@ -47,15 +68,23 @@ fi
 # (124) from a helper-reported failure (1).
 HARD_TIMEOUT_SECS=30
 
-# CONFIG_DIR is consumed by the node helper when writing selector-drift dumps
-# to ~/.${BRAND}/logs/list-cf-domains-<ts>.html.
+# Env passed through:
+#  - CONFIG_DIR    — consumed by the node helper when writing selector-drift
+#                    dumps to ~/.${BRAND}/logs/list-cf-domains-<ts>.html.
+#  - BRAND         — names the brand for log lines naming the brand on
+#                    config-class failures (helper does not derive it from
+#                    CONFIG_DIR to keep the two concerns independent).
+#  - MAXY_PLATFORM_ROOT — install root the helper reads `config/brand.json`
+#                    from for `cdpPort`. Resolved above so direct-SSH
+#                    invocation matches the systemd-spawned path.
 #
 # `node --experimental-strip-types` (stable in Node 22.22) runs the .ts file
 # natively: type annotations are stripped, no enums / decorators are used, so
 # no TS type-transform is needed. `--no-warnings` suppresses the experimental
 # banner which would otherwise leak into stderr and confuse the route parser.
 set +e
-CONFIG_DIR="${CONFIG_DIR}" timeout --preserve-status --signal=TERM "${HARD_TIMEOUT_SECS}" \
+CONFIG_DIR="${CONFIG_DIR}" BRAND="${BRAND}" MAXY_PLATFORM_ROOT="${MAXY_PLATFORM_ROOT}" \
+  timeout --preserve-status --signal=TERM "${HARD_TIMEOUT_SECS}" \
   node --experimental-strip-types --no-warnings "${TS_ENTRY}"
 EXIT_CODE=$?
 set -e