ima2-gen 2.0.14 → 2.0.15

package/CHANGELOG.md

@@ -29,7 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Release builds now pin Node `24.17.0`, npm `11.18.0`, and `@openai/codex` `0.144.1`; CI also performs clean npm 12 installs on Ubuntu and Windows.
 - npm 12 install-script approvals are explicit for root/UI lockfiles and one-click installers verify the installed native runtime with `ima2 doctor`.
 - GitHub Actions are pinned to full commit SHAs, Windows runs the installed-tarball smoke, and UI build dependencies are audited at high severity (`vite` 7.3.6, `esbuild` 0.28.1).
-- Test suite grew to **1087** cases across **206** files (72 runtime-importing, 134 contract-only).
+- Test suite grew to **1094** cases across **207** files (73 runtime-importing, 134 contract-only).
 
 ### Fixed
 
@@ -43,6 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Packaged `openai-oauth` now has its required `zod` peer available in consumer installs; package smoke executes both bundled CLIs from the installed tarball.
 - npm 12 keyed-object `npm pack --json` output is normalized alongside npm 11 array output, so package smoke and release packing share one cross-version artifact contract.
 - Windows npm subprocesses execute `npm-cli.js` through Node with preserved arguments, and packaged CLI smoke executes declared JS bins instead of fragile `.cmd` shell shims.
+- Windows OAuth discovery now executes the package-local `@openai/codex` and bundled `openai-oauth` JavaScript entrypoints through the current Node runtime instead of relying on global PATH, `npx`, or direct `.cmd` spawning. Codex login explicitly uses file-backed credential storage required by the proxy, while keyring-only sessions receive a precise re-login diagnosis. Release publishing is gated by npm 11/12 Windows global-update smokes of the exact tarball.
 
 ## [2.0.4] - 2026-06-27
 

package/bin/commands/doctor.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "url";
 import { buildHardeningDoctorLines } from "../lib/doctor-checks.js";
 import { buildStorageDoctorLines } from "../lib/storage-doctor.js";
 import { detectCodexAuth } from "../../lib/codexDetect.js";
+import { resolvePackageBin } from "../../lib/packageCli.js";
 import { runImageDoctorProbe } from "../../lib/responsesDoctor.js";
 import { config as runtimeConfig } from "../../config.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -30,8 +31,8 @@ function loadConfig() {
     return {};
 }
 function missingRuntimeDeps() {
-    const deps = ["express", "better-sqlite3", "openai", "openai-oauth", "progrok/package.json"];
-    return deps.filter((dep) => {
+    const deps = ["express", "better-sqlite3", "openai", "openai-oauth", "progrok/package.json", "@openai/codex/package.json", "zod"];
+    const missing = deps.filter((dep) => {
         try {
             requireFromRoot.resolve(dep);
             return false;
@@ -39,7 +40,17 @@ function missingRuntimeDeps() {
         catch {
             return true;
         }
-    }).map((dep) => dep === "progrok/package.json" ? "progrok" : dep);
+    }).map((dep) => dep.endsWith("/package.json") ? dep.slice(0, -"/package.json".length) : dep);
+    for (const [packageName, binName] of [["openai-oauth", "openai-oauth"], ["@openai/codex", "codex"]]) {
+        try {
+            resolvePackageBin(packageName, binName);
+        }
+        catch {
+            if (!missing.includes(packageName))
+                missing.push(packageName);
+        }
+    }
+    return missing;
 }
 function valueAfter(args, name) {
     const index = args.indexOf(name);
@@ -181,8 +192,16 @@ async function standardDoctor() {
     for (const line of storageLines)
         console.log(line);
     const auth = detectCodexAuth();
-    if (auth.platform === "win32")
-        console.log("  ℹ Windows GPT OAuth note: use WSL2 for Codex login.");
+    if (fileConfig.provider === "oauth" && !auth.proxyReady) {
+        console.log(auth.authed
+            ? "  ✗ Codex is keyring-authenticated, but GPT OAuth needs a file-backed session; run 'ima2 login'"
+            : "  ✗ GPT OAuth has no file-backed Codex session; run 'ima2 login'");
+        fail++;
+    }
+    else if (auth.proxyReady) {
+        console.log("  ✓ GPT OAuth file-backed Codex session is ready");
+        ok++;
+    }
     console.log(`\n  ${ok} passed, ${fail} failed\n`);
     process.exit(fail > 0 ? 1 : 0);
 }

package/bin/ima2.js

@@ -3,13 +3,14 @@ import { createInterface } from "readline/promises";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
-import { spawn, execSync } from "child_process";
+import { spawn, execFileSync } from "child_process";
 import { confirmDestructiveAction } from "./lib/destructive-confirm.js";
 import { doctor } from "./commands/doctor.js";
-import { openUrl, resolveBin, killProcessTree } from "./lib/platform.js";
+import { openUrl, killProcessTree } from "./lib/platform.js";
 import { maybePromptGithubStar } from "./lib/star-prompt.js";
 import { ensureFreshUiDist } from "./lib/ui-build.js";
-import { detectCodexAuth } from "../lib/codexDetect.js";
+import { codexFileLoginArgs, detectCodexAuth } from "../lib/codexDetect.js";
+import { packageCliCommand } from "../lib/packageCli.js";
 import { config as runtimeConfig } from "../config.js";
 import { errInfo } from "../lib/errInfo.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -20,6 +21,16 @@ const ROOT = join(__dirname, "..");
 const CONFIG_DIR = runtimeConfig.storage.configDir;
 const CONFIG_FILE = runtimeConfig.storage.configFile;
 const LEGACY_CONFIG_FILE = join(ROOT, ".ima2", "config.json");
+function runSelf(args) {
+    execFileSync(process.execPath, [join(ROOT, "bin", "ima2.js"), ...args], { stdio: "inherit" });
+}
+function runCodexLogin() {
+    const codex = packageCliCommand("@openai/codex", "codex", codexFileLoginArgs());
+    execFileSync(codex.command, codex.args, { stdio: "inherit", windowsHide: true });
+    if (!detectCodexAuth().proxyReady) {
+        throw new Error("Codex login completed without a file-backed session for the GPT OAuth proxy");
+    }
+}
 // Load package.json for version
 let pkg = { version: "?", name: "ima2-gen" };
 try {
@@ -83,7 +94,7 @@ async function setup() {
         saveConfig(config);
         console.log("\n  Starting Grok OAuth login...\n");
         try {
-            execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login --manual-paste`, { stdio: "inherit" });
+            runSelf(["grok", "login", "--manual-paste"]);
         }
         catch {
             console.log("\n  Grok login failed or cancelled. You can retry with 'ima2 grok login'.\n");
@@ -101,10 +112,13 @@ async function setup() {
         console.log("\n  Setting up both GPT OAuth + Grok OAuth...\n");
         // GPT OAuth
         const auth = detectCodexAuth();
-        if (!auth.authed) {
+        if (!auth.proxyReady) {
+            if (auth.authed) {
+                console.log("  Codex is signed in through the OS keyring; ima2 needs a file-backed session.\n");
+            }
             console.log("  Running GPT OAuth login...\n");
             try {
-                execSync(`${resolveBin("npx")} @openai/codex login`, { stdio: "inherit" });
+                runCodexLogin();
             }
             catch {
                 console.log("\n  GPT login failed. Continuing with Grok...\n");
@@ -116,7 +130,7 @@ async function setup() {
         // Grok OAuth
         console.log("  Running Grok OAuth login...\n");
         try {
-            execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login --manual-paste`, { stdio: "inherit" });
+            runSelf(["grok", "login", "--manual-paste"]);
         }
         catch {
             console.log("\n  Grok login failed. You can retry with 'ima2 grok login'.\n");
@@ -132,14 +146,14 @@ async function setup() {
         saveConfig(config);
         console.log("\n  Starting GPT OAuth login...\n");
         const auth = detectCodexAuth();
-        const hasAuth = auth.authed;
+        const hasAuth = auth.proxyReady;
         if (!hasAuth) {
-            if (auth.platform === "win32") {
-                console.log("  Windows note: OpenAI Codex has no documented native installer. Use WSL2 for best results.\n");
+            if (auth.authed) {
+                console.log("  Codex is signed in through the OS keyring; ima2 needs a file-backed session.\n");
             }
             console.log("  Running 'codex login' — follow the browser prompt.\n");
             try {
-                execSync(`${resolveBin("npx")} @openai/codex login`, { stdio: "inherit" });
+                runCodexLogin();
             }
             catch {
                 console.log("\n  Login failed or cancelled. You can retry with 'ima2 serve'.\n");
@@ -187,7 +201,7 @@ async function serve(serveArgs = []) {
         env.OPENAI_API_KEY = config.apiKey;
     }
     const serverPath = join(ROOT, "server.js");
-    const child = spawn("node", [serverPath], {
+    const child = spawn(process.execPath, [serverPath], {
         stdio: "inherit",
         env,
         cwd: ROOT,
@@ -232,10 +246,14 @@ async function showStatus() {
     }
     const probeLabel = auth.probe === "authed" ? "✓ authed"
         : auth.probe === "unauthed" ? "✗ not logged in"
-            : "– codex CLI not found";
+            : auth.probe === "error" ? "✗ codex CLI failed"
+                : "– codex CLI not found";
     console.log(`    codex login status           ${probeLabel}`);
-    if (auth.platform === "win32") {
-        console.log("    (Windows: no native codex installer — use WSL2)");
+    if (auth.authed && !auth.proxyReady) {
+        console.log("    GPT OAuth proxy             ✗ keyring-only; run 'ima2 login'");
+    }
+    else if (auth.proxyReady) {
+        console.log("    GPT OAuth proxy             ✓ file-backed session ready");
     }
     console.log("");
 }

package/docs/migration/runtime-test-inventory.md

@@ -4,7 +4,7 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 206 (runtime: 72, contract: 134)
+Total: 207 (runtime: 73, contract: 134)
 
 ## Runtime-importing tests
 - `tests/agent-mode-auto-planner-contract.test.ts`
@@ -55,6 +55,7 @@ Total: 206 (runtime: 72, contract: 134)
 - `tests/node-route-refs.test.ts`
 - `tests/node-streaming-sse.test.ts`
 - `tests/node-validation-error-contract.test.ts`
+- `tests/oauth-cli-dependencies.test.ts`
 - `tests/oauth-normalize.test.ts`
 - `tests/oauth-proxy-error-safety.test.ts`
 - `tests/open-directory.test.ts`

package/lib/codexDetect.js

@@ -3,13 +3,23 @@
 // - OpenAI Codex stores auth under CODEX_HOME (default ~/.codex/auth.json).
 // - Legacy chatgpt-local stores auth under ~/.chatgpt-local/auth.json.
 // - Auth may live in OS keyring instead of a file (file absence ≠ unauth).
-// - Windows has no documented native install path; WSL is the supported path.
+// - openai-oauth can only consume a file-backed Codex session.
 import { existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { errInfo } from "./errInfo.js";
+import { resolvePackageBin } from "./packageCli.js";
 const HOME = homedir();
+export const CODEX_FILE_AUTH_CONFIG = 'cli_auth_credentials_store="file"';
+export function codexFileLoginArgs(options = {}) {
+    return [
+        "login",
+        ...(options.deviceAuth ? ["--device-auth"] : []),
+        "-c",
+        CODEX_FILE_AUTH_CONFIG,
+    ];
+}
 export function codexAuthPaths() {
     const codexHome = process.env.CODEX_HOME || join(HOME, ".codex");
     return {
@@ -22,31 +32,62 @@ export function hasAuthFile() {
     const p = codexAuthPaths();
     return existsSync(p.codex) || existsSync(p.chatgpt) || existsSync(p.xdgCodex);
 }
+function commandErrorText(error) {
+    if (!error || typeof error !== "object")
+        return String(error || "");
+    const value = error;
+    return [value.message, value.stdout, value.stderr]
+        .map((part) => Buffer.isBuffer(part) ? part.toString("utf8") : typeof part === "string" ? part : "")
+        .filter(Boolean)
+        .join("\n");
+}
 // Non-invasive probe: `codex login status` returns 0 when authed (file OR keyring).
-// Returns: "authed" | "unauthed" | "missing" (codex binary not found)
-export function codexLoginStatus(timeoutMs = 2000) {
-    const candidates = process.platform === "win32"
+// "error" means the wrapper was found but failed before reporting auth state.
+function probeCodex(command, args, timeoutMs, execFileSyncImpl, shell = false) {
+    try {
+        execFileSyncImpl(command, args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: timeoutMs,
+            windowsHide: true,
+            shell,
+        });
+        return "authed";
+    }
+    catch (e) {
+        const err = errInfo(e);
+        if (err.code === "ENOENT")
+            return "missing";
+        if (typeof err.status === "number" && /not logged in/i.test(commandErrorText(e))) {
+            return "unauthed";
+        }
+        return "error";
+    }
+}
+export function codexLoginStatus(timeoutMs = 2000, options = {}) {
+    const platform = options.platform || process.platform;
+    const execPath = options.execPath || process.execPath;
+    const execFileSyncImpl = options.execFileSyncImpl || execFileSync;
+    let sawError = false;
+    try {
+        const codexBin = (options.resolveCodexBin || (() => resolvePackageBin("@openai/codex", "codex")))();
+        const bundled = probeCodex(execPath, [codexBin, "login", "status"], timeoutMs, execFileSyncImpl, false);
+        if (bundled === "authed" || bundled === "unauthed")
+            return bundled;
+        sawError ||= bundled === "error";
+    }
+    catch {
+        // Fall through to a user-managed Codex CLI when the package dependency is unavailable.
+    }
+    const candidates = platform === "win32"
         ? ["codex.cmd", "codex.exe", "codex"]
         : ["codex"];
     for (const bin of candidates) {
-        try {
-            execFileSync(bin, ["login", "status"], {
-                stdio: "ignore",
-                timeout: timeoutMs,
-                windowsHide: true,
-            });
-            return "authed";
-        }
-        catch (e) {
-            const err = errInfo(e);
-            if (err.raw && err.code === "ENOENT")
-                continue;
-            // non-zero exit = binary exists but not authed
-            if (err.raw && typeof err.status === "number")
-                return "unauthed";
-        }
+        const result = probeCodex(bin, ["login", "status"], timeoutMs, execFileSyncImpl, platform === "win32" && bin.endsWith(".cmd"));
+        if (result === "authed" || result === "unauthed")
+            return result;
+        sawError ||= result === "error";
     }
-    return "missing";
+    return sawError ? "error" : "missing";
 }
 export function detectCodexAuth() {
     const files = codexAuthPaths();
@@ -55,14 +96,22 @@ export function detectCodexAuth() {
         chatgpt: existsSync(files.chatgpt),
         xdgCodex: existsSync(files.xdgCodex),
     };
+    const proxyAuthFile = fileHits.codex
+        ? files.codex
+        : fileHits.chatgpt
+            ? files.chatgpt
+            : fileHits.xdgCodex
+                ? files.xdgCodex
+                : null;
     const probe = codexLoginStatus();
-    const authed = probe === "authed" || fileHits.codex || fileHits.chatgpt || fileHits.xdgCodex;
+    const authed = probe === "authed" || proxyAuthFile !== null;
     return {
         authed,
+        proxyReady: proxyAuthFile !== null,
+        proxyAuthFile,
         probe,
         files,
         fileHits,
         platform: process.platform,
-        wslHint: process.platform === "win32",
     };
 }

package/lib/oauthLauncher.js

@@ -1,7 +1,7 @@
-import { isWin } from "../bin/lib/platform.js";
 import { config } from "../config.js";
 import { parseLocalhostPortFromUrl, parseOAuthReadyUrl } from "./runtimePorts.js";
-import { hasAuthFile } from "./codexDetect.js";
+import { detectCodexAuth } from "./codexDetect.js";
+import { resolvePackageBin } from "./packageCli.js";
 import { spawn } from "node:child_process";
 export function startOAuthProxy(options = {}) {
     const oauthPort = options.oauthPort ?? config.oauth.proxyPort;
@@ -12,19 +12,39 @@ export function startOAuthProxy(options = {}) {
     let hasBeenReady = false;
     let restartCount = 0;
     const MAX_RESTARTS = 3;
+    const detectAuth = options.detectAuth ?? detectCodexAuth;
+    const execPath = options.execPath ?? process.execPath;
+    const resolveOAuthBin = options.resolveOAuthBin ?? (() => resolvePackageBin("openai-oauth", "openai-oauth"));
+    const spawnImpl = options.spawnImpl ?? spawn;
     const spawnProxy = () => {
         // Guard: don't start if no auth file exists (avoids pointless crash loops
         // and prevents openai-oauth from corrupting state on refresh failure)
-        if (!hasAuthFile()) {
-            console.log("[gpt-oauth] No Codex auth file found. Skipping GPT OAuth proxy.");
-            options.onExit?.({ code: 0 });
+        const auth = detectAuth();
+        if (!auth.proxyReady || typeof auth.proxyAuthFile !== "string") {
+            console.log("[gpt-oauth] No file-backed Codex session found. Run `ima2 login` to enable GPT OAuth.");
+            options.onExit?.({ code: 0, reason: "missing-auth-file" });
             return;
         }
         console.log(`Starting GPT OAuth proxy (openai-oauth) on port ${oauthPort}...`);
         const spawnedAt = Date.now();
-        const child = spawn("npx", ["openai-oauth", "--port", String(oauthPort)], {
+        let oauthBin;
+        try {
+            oauthBin = resolveOAuthBin();
+        }
+        catch (error) {
+            console.error(`[gpt-oauth] failed to resolve bundled proxy: ${error.message}`);
+            options.onExit?.({ code: 1 });
+            return;
+        }
+        const child = spawnImpl(execPath, [
+            oauthBin,
+            "--port",
+            String(oauthPort),
+            "--oauth-file",
+            auth.proxyAuthFile,
+        ], {
             stdio: ["ignore", "pipe", "pipe"],
-            shell: isWin,
+            shell: false,
             windowsHide: true,
             env: { ...process.env },
         });

package/lib/packageCli.js

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+const requireFromPackage = createRequire(import.meta.url);
+function readManifest(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function resolvePackageManifest(packageName) {
+    try {
+        return requireFromPackage.resolve(`${packageName}/package.json`);
+    }
+    catch (error) {
+        if (error.code !== "ERR_PACKAGE_PATH_NOT_EXPORTED")
+            throw error;
+    }
+    let current = dirname(requireFromPackage.resolve(packageName));
+    while (true) {
+        const candidate = join(current, "package.json");
+        if (existsSync(candidate) && readManifest(candidate).name === packageName)
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            throw new Error(`Could not locate ${packageName}/package.json`);
+        current = parent;
+    }
+}
+export function resolvePackageBin(packageName, binName) {
+    const manifestPath = resolvePackageManifest(packageName);
+    const manifest = readManifest(manifestPath);
+    const entry = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.[binName];
+    if (!entry)
+        throw new Error(`${packageName} does not declare the ${binName} CLI`);
+    const binPath = resolve(dirname(manifestPath), entry);
+    if (!existsSync(binPath))
+        throw new Error(`${packageName} CLI entry is missing: ${binPath}`);
+    return binPath;
+}
+export function packageCliCommand(packageName, binName, args = [], options = {}) {
+    return {
+        command: options.execPath || process.execPath,
+        args: [resolvePackageBin(packageName, binName), ...args],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "2.0.14",
+  "version": "2.0.15",
   "packageManager": "npm@11.18.0",
   "description": "Local OAuth image generation studio with classic and node workflows",
   "type": "module",
@@ -20,6 +20,7 @@
     "test:install-policy": "node scripts/check-install-policy.mjs",
     "test:install-policy:npm12": "node scripts/check-install-policy.mjs --npm-pending",
     "test:package-install": "node --test tests/package-install-smoke.mjs",
+    "test:package-global-update": "node scripts/package-global-update-smoke.mjs",
     "test:inventory": "node scripts/classify-tests.mjs --check --fail-js-runtime",
     "setup": "node bin/ima2.js setup",
     "prepack": "npm run ui:build && npm run build:server && npm run build:cli",
@@ -104,5 +105,5 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
-  "gitHead": "bea7ae5b5ea0a6e9039732794d2bdeb939e429b3"
+  "gitHead": "ab86116ee1d23040e7ab63e49d8a6d4e19eddabd"
 }

package/routes/auth.js

@@ -2,15 +2,13 @@ import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { writeFileSync, renameSync, mkdirSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { codexFileLoginArgs, detectCodexAuth } from "../lib/codexDetect.js";
+import { packageCliCommand } from "../lib/packageCli.js";
 const GROK_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
 const GROK_SCOPE = "openid profile email offline_access grok-cli:access api:access";
 const GROK_TOKEN_URL = "https://auth.x.ai/oauth2/token";
 const CODEX_DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
-// Bundled @openai/codex binary (npm dependency), resolved relative to this
-// module so device-auth login works even when `codex` is not on the user's PATH.
-const CODEX_BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "node_modules", ".bin", process.platform === "win32" ? "codex.cmd" : "codex");
 const MAX_CONCURRENT_SESSIONS = 20;
 const sessions = new Map();
 function sid() {
@@ -129,9 +127,12 @@ function startCodexDeviceCode() {
         for (const k of ["OPENAI_API_KEY", "XAI_API_KEY", "GEMINI_API_KEY", "ANTHROPIC_API_KEY", "VERTEX_SERVICE_ACCOUNT_JSON"]) {
             delete childEnv[k];
         }
-        const child = spawn(CODEX_BIN, ["login", "--device-auth"], {
+        const codex = packageCliCommand("@openai/codex", "codex", codexFileLoginArgs({ deviceAuth: true }));
+        const child = spawn(codex.command, codex.args, {
             stdio: ["ignore", "pipe", "pipe"],
             env: childEnv,
+            shell: false,
+            windowsHide: true,
         });
         let stdout = "";
         let resolved = false;
@@ -180,9 +181,12 @@ function startCodexDeviceCode() {
                 reject(new Error(`codex login exited with code ${code} before providing device code`));
                 return;
             }
-            session.status = code === 0 ? "complete" : "error";
+            const proxyReady = code === 0 && detectCodexAuth().proxyReady;
+            session.status = proxyReady ? "complete" : "error";
             if (code !== 0)
                 session.error = `codex exited with code ${code}`;
+            else if (!proxyReady)
+                session.error = "Codex login did not create a file-backed GPT OAuth session";
             cleanup(id);
         });
         child.on("error", (err) => {

package/server.js

@@ -181,6 +181,10 @@ function runtimeHostUrl(host) {
     return host;
 }
 function advertise(ctx) {
+    // Proxy readiness can arrive before the backend has bound. Publishing that
+    // intermediate state makes consumers treat the configured port as live.
+    if (!ctx.serverActualPort)
+        return;
     try {
         mkdirSync(dirname(ctx.config.storage.advertiseFile), { recursive: true });
         writeFileSync(ctx.config.storage.advertiseFile, JSON.stringify({