fix(server): accept SERVER_PORT alias and fail fast on PORT/SERVER_PORT mismatch

.env.example

@@ -7,15 +7,15 @@ KEY_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
 # one to leave alone until somebody has decided otherwise: the trail is append-only and nothing else
 # can remove a row, so this is the only way it ever shrinks.
 # AUDIT_RETENTION_DAYS=365
-# Two names for one number, and they have to agree.
-#
-# The server reads PORT (server/src/index.ts). scripts/start.sh reads SERVER_PORT, because it also
-# has to know where the app should proxy and which port to report free -- and docs/configuration.md
-# documents SERVER_PORT as the setting. Only PORT shipped here, so moving the server by editing this
-# line left the script still looking at 3001: it found whatever else was there, accepted the first
-# 200 as proof, and failed several stages later parsing that stranger's HTML as JSON.
-#
-# Change both, or neither.
+# Two names for one number, and they must agree when both are set.
+#
+# The server accepts either PORT or SERVER_PORT (server/src/index.ts), preferring PORT when both
+# are present and refusing to start if they disagree, so a single edit is enough. scripts/start.sh
+# and the app's Vite proxy read SERVER_PORT/APP_PORT, and docs/configuration.md documents
+# SERVER_PORT as the setting. Only PORT shipped here historically, so moving the server by
+# editing one line left the script still looking at 3001: it found whatever else was there,
+# accepted the first 200 as proof, and failed several stages later parsing that stranger's
+# HTML as JSON. Setting both to the same value remains valid.
 PORT=3001
 SERVER_PORT=3001
 TENANT_PACKAGE_DIR=../examples/fintech

server/src/index.ts

@@ -143,7 +143,17 @@ const identifyActor: IdentifyActor = async (request) => {
 };
 
 const config = loadConfig();
-const port = Number.parseInt(process.env.PORT ?? "3001", 10);
+const rawPort = process.env.PORT ?? process.env.SERVER_PORT ?? "3001";
+if (
+  process.env.PORT &&
+  process.env.SERVER_PORT &&
+  process.env.PORT !== process.env.SERVER_PORT
+) {
+  throw new Error(
+    `PORT (${process.env.PORT}) and SERVER_PORT (${process.env.SERVER_PORT}) disagree: set one or set both to the same value`,
+  );
+}
+const port = Number.parseInt(rawPort, 10);
 const database = createDatabase(config.databaseUrl);
 await initializeDevActorUser(database, config.singleUser);
 // The vault, built before the agent store because a customer's agent may sit behind a key and that