@bitkyc08/opencodex 2.7.28 → 2.7.29

package/src/cli/account.ts

@@ -0,0 +1,265 @@
+/** `ocx account` — list and switch provider credentials (issue #180). */
+import { loadConfig } from "../config";
+import { providerCodexAccountMode } from "../providers/registry";
+import type { OcxConfig } from "../types";
+import { cmdAddKey, cmdAutoSwitch, cmdRefresh, cmdRemove } from "./account-extended";
+import { apiError, apiJson, classifyAccount, fetchRows, proxyUnreachable, resolveBaseUrl, type AccountDeps, type AccountRow, type AccountType, type ApiResult }
+  from "./account-api";
+
+export { classifyAccount } from "./account-api";
+export type { AccountDeps, AccountRow, AccountType, ClassifyResult } from "./account-api";
+type TargetProvenance = "live-oauth-list" | "config" | "codex";
+
+const MAIN_ALIAS = "main";
+const MAIN_CODEX_ID = "__main__";
+/** Replacement-style single-slot OAuth (no stable identity; not HTTP-derivable). */
+const REPLACEMENT_STYLE_OAUTH = new Set(["kiro"]);
+
+const ACCOUNT_USAGE = `Usage:
+  ocx account list [provider] [--json] [--all]
+  ocx account current <provider> [--json]
+  ocx account use <provider> <account-or-key-id|main> [--json]
+  ocx account refresh <provider> [--json]
+  ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]
+  ocx account remove <provider> <account-or-key-id|main> --yes [--json]
+  ocx account add-key <provider> [--label <label>] [--json]
+
+List and switch provider accounts and API-key pools (masked output only).
+'main' selects the Codex App login for the openai account pool.`;
+
+function consumeFlag(args: string[], flag: string): boolean {
+  const idx = args.indexOf(flag);
+  if (idx === -1) return false;
+  args.splice(idx, 1);
+  return true;
+}
+
+/** Returns an error message for leftover args, or null when clean. */
+function leftoverArgsError(args: string[]): string | null {
+  if (args.length === 0) return null;
+  const unknown = args.filter(a => a.startsWith("-"));
+  return unknown.length > 0
+    ? `Unknown flag(s): ${unknown.join(", ")}`
+    : `Unexpected argument(s): ${args.join(", ")}`;
+}
+
+function candidateNames(config: OcxConfig): string {
+  const names = new Set<string>(["openai"]);
+  for (const n of Object.keys(config.providers ?? {})) names.add(n);
+  return [...names].join(", ");
+}
+
+function displayId(id: string): string {
+  return id === MAIN_CODEX_ID ? MAIN_ALIAS : id;
+}
+
+function statusText(row: AccountRow): string {
+  const parts: string[] = [];
+  if (row.active) parts.push(row.type === "codex" ? "next session" : "active");
+  if (row.needsReauth) parts.push("needs-reauth");
+  return parts.join(" ");
+}
+
+export function formatAccountTable(rows: AccountRow[]): string {
+  const header = ["PROVIDER", "TYPE", "ID", "PLAN/LABEL", "STATUS"];
+  const data = rows.map(r => {
+    const keyLabel = r.masked && r.label !== r.masked ? `${r.masked} (${r.label})` : r.masked;
+    return [r.provider, r.type, displayId(r.id), r.type === "api-key" ? keyLabel ?? "-" : r.label ?? "-", statusText(r)];
+  });
+  const widths = header.map((h, i) => Math.max(h.length, ...data.map(d => d[i]!.length)));
+  const line = (cols: string[]) => cols.map((c, i) => c.padEnd(widths[i]!)).join("  ").trimEnd();
+  return [line(header), ...data.map(line)].join("\n");
+}
+
+async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = consumeFlag(rest, "--json");
+  const showAll = consumeFlag(rest, "--all");
+  const name = rest.shift();
+  const leftover = leftoverArgsError(rest);
+  if (leftover) {
+    console.error(leftover);
+    console.error(ACCOUNT_USAGE);
+    return 1;
+  }
+  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+
+  const targets: { name: string; type: AccountType; provenance: TargetProvenance }[] = [];
+  if (name) {
+    const c = classifyAccount(config, name);
+    if ("error" in c) {
+      console.error(`Error: ${c.error}. Known candidates: ${candidateNames(config)}`);
+      return 1;
+    }
+    targets.push({ name, type: c.type, provenance: "config" });
+  } else {
+    const seen = new Set<string>();
+    const push = (n: string, provenance: TargetProvenance) => {
+      if (seen.has(n)) return;
+      seen.add(n);
+      const c = classifyAccount(config, n);
+      if ("error" in c) return; // fan-out silently skips no-credential providers
+      targets.push({ name: n, type: c.type, provenance });
+    };
+    push("openai", "codex");
+    const providersRes = await apiJson(deps, baseUrl, "GET", "/api/oauth/providers");
+    if (providersRes.status === 0) return proxyUnreachable();
+    if (providersRes.status !== 200) return apiError(providersRes.json, "failed to list OAuth providers");
+    if (Array.isArray(providersRes.json.providers)) {
+      for (const p of providersRes.json.providers) {
+        if (typeof p === "string") push(p, "live-oauth-list");
+      }
+    }
+    for (const n of Object.keys(config.providers ?? {})) push(n, "config");
+  }
+
+  const rows: AccountRow[] = [];
+  const notes: string[] = [];
+  for (const t of targets) {
+    const r = await fetchRows(deps, baseUrl, t.name, t.type);
+    if (r.networkDown) return proxyUnreachable();
+    if (r.errorJson) {
+      if (name) return apiError(r.errorJson, `failed to list ${t.name}`);
+      const errorText = typeof r.errorJson.error === "string" ? r.errorJson.error : "";
+      const skipUnknownKey = t.type === "api-key"
+        && r.status === 404
+        && errorText.includes("unknown provider");
+      const skipConfigOAuth = t.type === "oauth"
+        && t.provenance === "config"
+        && r.status === 400
+        && errorText.includes("unknown oauth provider");
+      if (skipUnknownKey || skipConfigOAuth) continue;
+      return apiError(r.errorJson, `failed to list ${t.name}`);
+    }
+    if (r.rows.length === 0) {
+      if (showAll) notes.push(`${t.name}: no stored accounts or keys`);
+      continue;
+    }
+    rows.push(...r.rows);
+    if (t.type === "codex") {
+      if (r.activeId === null) notes.push("openai: auto (no pin — lowest-usage account is selected per request)");
+      if (providerCodexAccountMode("openai", config.providers?.openai) === "direct") {
+        notes.push("openai is in direct mode — the selection takes effect when pool mode is enabled");
+      }
+    }
+    if (t.type === "oauth" && REPLACEMENT_STYLE_OAUTH.has(t.name)) {
+      notes.push(`${t.name}: single login slot — re-login replaces the current account`);
+    }
+  }
+
+  if (wantsJson) {
+    console.log(JSON.stringify({ accounts: rows, notes }, null, 2));
+    return 0;
+  }
+  if (rows.length > 0) console.log(formatAccountTable(rows));
+  for (const n of notes) console.log(n);
+  if (rows.length === 0 && notes.length === 0) console.log("No stored accounts or keys.");
+  return 0;
+}
+
+async function cmdCurrent(rest: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = consumeFlag(rest, "--json");
+  const name = rest.shift();
+  const leftover = leftoverArgsError(rest);
+  if (!name || leftover) {
+    if (leftover) console.error(leftover);
+    console.error(ACCOUNT_USAGE);
+    return 1;
+  }
+  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  const c = classifyAccount(config, name);
+  if ("error" in c) {
+    console.error(`Error: ${c.error}. Known candidates: ${candidateNames(config)}`);
+    return 1;
+  }
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+  const r = await fetchRows(deps, baseUrl, name, c.type);
+  if (r.networkDown) return proxyUnreachable();
+  if (r.errorJson) return apiError(r.errorJson, `failed to read ${name}`);
+
+  const activeRow = r.rows.find(row => row.active) ?? null;
+  if (wantsJson) {
+    console.log(JSON.stringify({
+      provider: name,
+      type: c.type,
+      activeId: r.activeId,
+      autoSwitchThreshold: r.autoSwitchThreshold,
+      account: activeRow,
+    }, null, 2));
+    return 0;
+  }
+  if (activeRow) {
+    console.log(formatAccountTable([activeRow]));
+  } else if (c.type === "codex" && r.activeId === null) {
+    console.log("openai: auto (no pin — lowest-usage account is selected per request)");
+  } else {
+    console.log(`${name}: no active account or key`);
+  }
+  return 0;
+}
+
+async function cmdUse(rest: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = consumeFlag(rest, "--json");
+  const name = rest.shift();
+  const id = rest.shift();
+  const leftover = leftoverArgsError(rest);
+  if (!name || !id || leftover) {
+    if (leftover) console.error(leftover);
+    console.error(ACCOUNT_USAGE);
+    return 1;
+  }
+  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  const c = classifyAccount(config, name);
+  if ("error" in c) {
+    console.error(`Error: ${c.error}. Known candidates: ${candidateNames(config)}`);
+    return 1;
+  }
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+
+  let res: ApiResult;
+  let activeId: string;
+  if (c.type === "codex") {
+    activeId = id === MAIN_ALIAS ? MAIN_CODEX_ID : id;
+    res = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/active", { accountId: activeId });
+  } else if (c.type === "oauth") {
+    activeId = id;
+    res = await apiJson(deps, baseUrl, "PUT", "/api/oauth/accounts/active", { provider: name, accountId: id });
+  } else {
+    activeId = id;
+    res = await apiJson(deps, baseUrl, "PUT", "/api/providers/keys/active", { name, id });
+  }
+  if (res.status === 0) return proxyUnreachable();
+  if (res.status !== 200) return apiError(res.json, `failed to switch ${name}`);
+
+  if (wantsJson) console.log(JSON.stringify({ ok: true, provider: name, type: c.type, activeId }, null, 2));
+  else console.log(`${name}: active ${c.type === "api-key" ? "key" : "account"} is now ${displayId(activeId)}`);
+  if (c.type === "codex") {
+    console.error("Applies to new Codex sessions; running threads keep their current account.");
+    const active = await apiJson(deps, baseUrl, "GET", "/api/codex-auth/active");
+    if (active.status === 200 && typeof active.json.autoSwitchThreshold === "number" && active.json.autoSwitchThreshold > 0) {
+      console.error(`Note: auto-switch (threshold ${active.json.autoSwitchThreshold}%) may override this pin.`);
+    }
+  }
+  return 0;
+}
+
+export async function cmdAccount(args: string[], deps: AccountDeps = {}): Promise<number> {
+  const [sub, ...rest] = args;
+  try {
+    if (sub === "list") return await cmdList(rest, deps);
+    if (sub === "current") return await cmdCurrent(rest, deps);
+    if (sub === "use") return await cmdUse(rest, deps);
+    if (sub === "refresh") return await cmdRefresh(rest, deps);
+    if (sub === "auto-switch") return await cmdAutoSwitch(rest, deps);
+    if (sub === "remove") return await cmdRemove(rest, deps);
+    if (sub === "add-key") return await cmdAddKey(rest, deps);
+    console.error(ACCOUNT_USAGE);
+    return 1;
+  } catch (err) {
+    console.error(`account: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/cli/claude.ts

@@ -135,7 +135,9 @@ export async function fetchClaudeContextWindows(config: OcxConfig, port: number,
 async function ensureProxyForClaude(): Promise<number | null> {
   const live = await findLiveProxy();
   if (live) return live.port;
-  const child = spawn(process.execPath, [process.argv[1], "start"], {
+  const cfgPort = loadConfig().port;
+  const pinPort = typeof cfgPort === "number" && cfgPort > 0 ? cfgPort : 10100;
+  const child = spawn(process.execPath, [process.argv[1], "start", "--port", String(pinPort)], {
     detached: true,
     stdio: "ignore",
     windowsHide: true,

package/src/cli/help.ts

@@ -79,6 +79,20 @@ const helpEntries: Record<string, HelpEntry> = {
       "Run `ocx provider --help` for full usage and examples.",
     ],
   },
+  account: {
+    usage: "ocx account <list|current|use|refresh|auto-switch|remove|add-key> ...",
+    summary: "List and switch provider accounts and API-key pools (GUI parity).",
+    details: [
+      "list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).",
+      "current <provider>  Show the active account or key.",
+      "use <provider> <id> Switch the active credential; 'main' selects the Codex App login.",
+      "refresh <provider>  Force-refresh Codex or provider quota reports.",
+      "auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.",
+      "remove <provider> <id> --yes  Remove a stored account or key after an existence check.",
+      "add-key <provider> [--label <label>]  Add a key read only from piped stdin.",
+      "Codex pool switches apply to new sessions; running threads keep their account.",
+    ],
+  },
   models: {
     usage: "ocx models [--provider <name>] [--json]",
     summary: "List available models from configured providers.",
@@ -144,6 +158,7 @@ Usage:
   ocx restart                  Stop and restart the proxy
   ocx health [--json]          Check proxy health (exit 0=healthy, 1=not)
   ocx provider <sub>          Manage providers (list|add|remove|show|set-default)
+  ocx account <sub>           Accounts/keys (list|current|use|refresh|auto-switch|remove|add-key)
   ocx models [--json]         List available models from configured providers
   ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx help [command]          Show help

package/src/cli/index.ts

@@ -22,7 +22,7 @@ import {
 import { collectStatus } from "./status";
 import { installCrashGuards } from "../lib/crash-guard";
 import { hasHelpFlag, printSubcommandUsage, printUsage, printVersion } from "./help";
-import { findAvailablePort, isAddrInUse, shouldPersistSelectedPort } from "../server/ports";
+import { findAvailablePort, isAddrInUse, PortUnavailableError, shouldPersistSelectedPort, waitForPortAvailable } from "../server/ports";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import { stopProxy } from "../lib/process-control";
 import { loadServiceTokenFromFile } from "../lib/service-secrets";
@@ -85,23 +85,43 @@ async function waitForProxy(timeoutMs = 8_000): Promise<LiveProxy | null> {
   return null;
 }
 
+/** Argv for detached `start`, optionally hard-pinning the listen port. */
+function startArgv(port?: number): string[] {
+  const args = [process.argv[1], "start"];
+  if (typeof port === "number" && Number.isFinite(port) && port > 0 && port <= 65535) {
+    args.push("--port", String(Math.trunc(port)));
+  }
+  return args;
+}
+
 async function chooseListenPort(requestedPort?: number): Promise<number> {
   const config = loadConfig();
   const preferred = requestedPort ?? config.port ?? 10100;
-  // Brief prefer-retry covers stop→start races (update restart, `ocx restart`) where the
-  // old process has exited but the listen socket is still draining.
-  const selected = await findAvailablePort(preferred, config.hostname ?? "127.0.0.1", {
-    preferRetryMs: 750,
-    preferRetryIntervalMs: 50,
-  });
-  if (selected !== preferred) {
-    console.log(`⚠️  Port ${preferred} is busy; starting opencodex on ${selected}.`);
-  }
-  if (shouldPersistSelectedPort(config.port, selected, preferred)) {
-    config.port = selected;
-    saveConfig(config);
+  const hardPin = requestedPort !== undefined && requestedPort > 0;
+  // Soft start: brief prefer-retry then ephemeral hop.
+  // Explicit `--port` (service wrappers / update restart): longer prefer-retry, never hop.
+  try {
+    const selected = await findAvailablePort(preferred, config.hostname ?? "127.0.0.1", {
+      preferRetryMs: hardPin ? 8_000 : 750,
+      preferRetryIntervalMs: 50,
+      allowEphemeralFallback: !hardPin,
+    });
+    if (selected !== preferred) {
+      console.log(`⚠️  Port ${preferred} is busy; starting opencodex on ${selected}.`);
+    }
+    if (shouldPersistSelectedPort(config.port, selected, preferred)) {
+      config.port = selected;
+      saveConfig(config);
+    }
+    return selected;
+  } catch (err) {
+    if (err instanceof PortUnavailableError) {
+      console.error(`❌ ${err.message}`);
+      console.error("   Stop whatever holds that port, or change config.port, then retry.");
+      process.exit(1);
+    }
+    throw err;
   }
-  return selected;
 }
 
 async function handleStart(options: { block?: boolean } = {}) {
@@ -128,7 +148,8 @@ async function handleStart(options: { block?: boolean } = {}) {
   await maybeShowUpdatePrompt();
 
   // Port selection is check-then-bind: a concurrent `ocx start`/`ensure` can win the port
-  // between the probe and Bun.serve. Retry the pick instead of dying on EADDRINUSE.
+  // between the probe and Bun.serve. Soft starts may re-pick; hard-pinned `--port` retries
+  // the same port only (never hop — that was the remaining PR #152 gap).
   let port = await chooseListenPort(requestedPort);
   let server: ReturnType<typeof startServer>;
   for (let attempt = 0; ; attempt++) {
@@ -137,6 +158,16 @@ async function handleStart(options: { block?: boolean } = {}) {
       break;
     } catch (err) {
       if (!isAddrInUse(err) || attempt >= 2) throw err;
+      if (requestedPort !== undefined) {
+        console.log(`⚠️  Port ${port} was taken while starting; waiting to retry the same port...`);
+        const hostname = loadConfig().hostname ?? "127.0.0.1";
+        const freed = await waitForPortAvailable(port, hostname, { timeoutMs: 3_000, intervalMs: 50 });
+        if (!freed) {
+          console.error(`❌ Port ${port} stayed busy; refusing to hop to an ephemeral port.`);
+          process.exit(1);
+        }
+        continue;
+      }
       console.log(`⚠️  Port ${port} was taken while starting; picking another...`);
       port = await chooseListenPort(requestedPort);
     }
@@ -249,7 +280,8 @@ async function handleEnsure() {
       return;
     }
 
-  const child = spawn(process.execPath, [process.argv[1], "start"], {
+  const pinPort = config.port ?? 10100;
+  const child = spawn(process.execPath, startArgv(pinPort > 0 ? pinPort : undefined), {
     detached: true,
     stdio: "ignore",
     windowsHide: true,
@@ -537,7 +569,7 @@ switch (command) {
     let live = await findLiveProxy();
     if (!live) {
       console.log("Proxy not running. Starting...");
-      const child = spawn(process.execPath, [process.argv[1], "start"], {
+      const child = spawn(process.execPath, startArgv((config.port ?? 10100) > 0 ? (config.port ?? 10100) : undefined), {
         detached: true,
         stdio: "ignore",
         windowsHide: true,
@@ -545,6 +577,10 @@ switch (command) {
       });
       child.unref();
       live = await waitForProxy();
+      if (!live) {
+        console.error("❌ Proxy did not become healthy after starting. Not opening the GUI.");
+        process.exit(1);
+      }
     }
     // Open the host the proxy actually binds — `localhost` only answers for
     // loopback/wildcard binds, not a concrete LAN/IPv6 hostname.
@@ -628,6 +664,11 @@ switch (command) {
     await handleProviderCommand(args.slice(1));
     break;
   }
+  case "account": {
+    const { cmdAccount } = await import("./account");
+    process.exitCode = await cmdAccount(args.slice(1));
+    break;
+  }
   case "models": {
     const { handleModels } = await import("./models");
     handleModels(args.slice(1));

package/src/cli/init.ts

@@ -82,6 +82,16 @@ export async function runInit(): Promise<void> {
     } else {
       // key + local: collect a key (local usually blank).
       if (p.dashboardUrl) console.log(`   🔑 Get your key: ${p.dashboardUrl}`);
+      // Template URL with placeholders (e.g. Cloudflare's {account_id}) needs a resolved value.
+      let baseUrl = p.baseUrl;
+      if (/\{[^}]*\}/.test(baseUrl)) {
+        const resolved = (await prompt.ask(`   Your endpoint URL (${baseUrl}): `)).trim();
+        if (!resolved) {
+          console.error("   A resolved URL is required — replace the {placeholder} with your actual value.");
+          process.exit(1);
+        }
+        baseUrl = resolved;
+      }
       const env = envKeyFor(p.id);
       const hint = p.kind === "local" ? "API key (usually blank — press Enter): " : `API key (paste, or env var $${env}): `;
       const apiKey = (await prompt.ask(`\n${hint}`)).trim();
@@ -89,7 +99,7 @@ export async function runInit(): Promise<void> {
       const defaultModel = modelChoice || p.defaultModel;
       providerConfig = {
         adapter: p.adapter,
-        baseUrl: p.baseUrl,
+        baseUrl,
         ...(p.kind === "key" ? { apiKey: apiKey || `\${${env}}` } : apiKey ? { apiKey } : {}),
         ...(defaultModel ? { defaultModel } : {}),
       };

package/src/lib/winsw.ts

@@ -18,7 +18,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { expandUserPath, getConfigDir } from "../config";
+import { expandUserPath, getConfigDir, loadConfig } from "../config";
 import { durableBunPath } from "./bun-runtime";
 import { serviceApiTokenFilePath } from "./service-secrets";
 
@@ -72,9 +72,20 @@ export interface WinswEntry {
  * Task Scheduler wrapper / launchd / systemd: the SCM service environment lacks the
  * user's interactive PATH, which provider subprocesses may need.
  */
-export function buildWinswXml(entry: WinswEntry, env: NodeJS.ProcessEnv = process.env): string {
+export function buildWinswXml(entry: WinswEntry, env: NodeJS.ProcessEnv = process.env, port?: number): string {
   const domain = env.USERDOMAIN?.trim() || ".";
   const user = env.USERNAME?.trim() || "";
+  const listenPort = (() => {
+    if (typeof port === "number" && Number.isFinite(port) && port > 0 && port <= 65535) return Math.trunc(port);
+    const baked = env.OCX_BAKE_PORT?.trim();
+    if (baked && /^\d+$/.test(baked)) {
+      const n = Number(baked);
+      if (n > 0 && n <= 65535) return n;
+    }
+    return loadConfig().port ?? 10100;
+  })();
+  // Services never bake `--port 0` (parsePortOption rejects it); treat as default.
+  const safeListenPort = listenPort > 0 && listenPort <= 65535 ? listenPort : 10100;
   const envLines = [
     `  <env name="OCX_SERVICE" value="1"/>`,
     `  <env name="OCX_API_TOKEN_FILE" value="${xmlEscape(serviceApiTokenFilePath())}"/>`,
@@ -88,7 +99,7 @@ export function buildWinswXml(entry: WinswEntry, env: NodeJS.ProcessEnv = proces
   <name>OpenCodex Proxy (native)</name>
   <description>OpenCodex proxy running as a native Windows service (windowless, starts at boot).</description>
   <executable>${xmlEscape(entry.bun)}</executable>
-  <arguments>${xmlEscape(`"${entry.cli}" start`)}</arguments>
+  <arguments>${xmlEscape(`"${entry.cli}" start --port ${safeListenPort}`)}</arguments>
 ${envLines.join("\n")}
   <logpath>${xmlEscape(winswLogDir())}</logpath>
   <log mode="roll-by-size">

package/src/oauth/login-cli.ts

@@ -62,10 +62,10 @@ async function handleOAuthLogin(name: string): Promise<void> {
   console.log(`\n✅ Logged in to ${name}. Try: ocx sync`);
 }
 
-export function providerConfigFromKeyLoginProvider(def: KeyLoginProvider, key: string): OcxProviderConfig {
+export function providerConfigFromKeyLoginProvider(def: KeyLoginProvider, key: string, baseUrlOverride?: string): OcxProviderConfig {
   return {
     adapter: def.adapter,
-    baseUrl: def.baseUrl,
+    baseUrl: baseUrlOverride ?? def.baseUrl,
     apiKey: key,
     ...(def.defaultModel ? { defaultModel: def.defaultModel } : {}),
     ...(def.models ? { models: [...def.models] } : {}),
@@ -94,19 +94,30 @@ async function handleKeyLogin(name: string): Promise<void> {
   openUrl(def.dashboardUrl);
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   const key = (await new Promise<string>((res) => rl.question(`Paste your ${def.label} API key: `, res))).trim();
+  // Template URL with placeholders needs resolution before saving.
+  let baseUrl = def.baseUrl;
+  if (/\{[^}]*\}/.test(baseUrl)) {
+    const resolved = (await new Promise<string>((res) => rl.question(`Your endpoint URL (${baseUrl}): `, res))).trim();
+    if (!resolved) {
+      rl.close();
+      console.error("A resolved URL is required — replace the {placeholder} with your actual value.");
+      process.exit(1);
+    }
+    baseUrl = resolved;
+  }
   rl.close();
   if (!key) {
     console.error("No key entered.");
     process.exit(1);
   }
   process.stdout.write("   validating… ");
-  const valid = await validateApiKey(def, key);
+  const valid = await validateApiKey({ ...def, baseUrl }, key);
   console.log(valid === true ? "valid ✅" : valid === false ? "INVALID ❌" : "couldn't validate (may still work)");
   if (valid === false) {
     console.error("Provider rejected the key. Not saved.");
     process.exit(1);
   }
-  const provider = providerConfigFromKeyLoginProvider(def, key);
+  const provider = providerConfigFromKeyLoginProvider(def, key, baseUrl);
   const config = loadConfig();
   config.providers[name] = provider;
   saveConfig(config);

package/src/providers/registry.ts

@@ -691,6 +691,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     id: "alibaba-token-plan",
     label: "Alibaba Token Plan (Beijing)",
     baseUrl: "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
+    allowBaseUrlOverride: true,
     adapter: "openai-chat",
     authKind: "key",
     dashboardUrl: "https://bailian.console.aliyun.com/cn-beijing?tab=plan",
@@ -706,7 +707,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     },
     modelReasoningEffortMap: { "deepseek-v4-pro": DEEPSEEK_THINKING_REASONING_MAP },
     thinkingBudgetModels: ALIBABA_TOKEN_PLAN_QWEN_MODELS,
-    preserveReasoningContentModels: ["glm-5.2", "deepseek-v4-pro"],
+    preserveReasoningContentModels: ["glm-5.2", "deepseek-v4-pro", "qwen3.8-max-preview"],
   },
   // NEEDS_HUMAN 2026-07-10: kept for config compatibility, but this is a dashboard URL,
   // no /models endpoint is documented, and tools are silently ignored upstream per docs.parallel.ai.
@@ -816,6 +817,25 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     note: "No key needed — uses Xiaomi MiMo's free public tier (limited-time offer). A JWT is bootstrapped automatically with an anonymous random client id stored locally. The endpoint contract mirrors the official MiMoCode client and is not publicly documented — Xiaomi may change or restrict it at any time. Prompts may be processed/retained by Xiaomi; do not send confidential material.",
   },
   { id: "cloudflare-ai-gateway", label: "Cloudflare AI Gateway", baseUrl: "https://gateway.ai.cloudflare.com/v1/{account-id}/{gateway}/anthropic", adapter: "anthropic", authKind: "key", dashboardUrl: "https://dash.cloudflare.com/?to=/:account/ai/ai-gateway" },
+  {
+    // Cloudflare Workers AI: OpenAI-compatible endpoint. The base URL contains {account_id}
+    // which must be resolved by the user at setup time. Model IDs use the @cf/ prefix.
+    // Live-verified 2026-07-21 against https://developers.cloudflare.com/workers-ai/models/
+    id: "cloudflare-workers-ai", label: "Cloudflare Workers AI",
+    baseUrl: "https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1",
+    adapter: "openai-chat", authKind: "key", freeTier: true,
+    dashboardUrl: "https://dash.cloudflare.com/?to=/:account/ai/workers-ai",
+    defaultModel: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+    models: [
+      "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+      "@cf/qwen/qwq-32b",
+      "@cf/deepseek-ai/deepseek-r1-distill-qwen-32b",
+      "@cf/moonshotai/kimi-k2.7-code",
+      "@cf/zai-org/glm-5.2",
+      "@cf/mistralai/mistral-small-3.1-24b-instruct",
+    ],
+    note: "Workers AI · Free tier included · Account ID required in base URL",
+  },
   // FREEZE 2026-07-10: /models was auth-gated under key login. OAuth device-flow + copilot_internal
   // exchange (issue #151) unlocks live discovery; static seed is a cold-start fallback only.
   {

package/src/server/index.ts

@@ -54,6 +54,7 @@ export {
 } from "./lifecycle";
 import {
   addFinalRequestLog,
+  hydrateRequestLogsFromDisk,
   httpStatusForRequestLogTerminal,
   httpStatusForTerminalStatus,
   inspectResponseLogSsePayload,
@@ -65,6 +66,7 @@ import {
 export {
   addFinalRequestLog,
   filterRequestLogs,
+  hydrateRequestLogsFromDisk,
   httpStatusForTerminalStatus,
   httpStatusFromTerminalError,
   nextRequestLogId,
@@ -175,6 +177,9 @@ export function startServer(port?: number) {
     }
   }
   invalidateCodexModelsCache();
+  // usage.jsonl already persists every request; rehydrate the in-memory Logs ring so
+  // /api/logs (and the GUI) survive `ocx stop` / `ocx start` process restarts.
+  hydrateRequestLogsFromDisk();
 
   const listenPort = port ?? config.port ?? 10100;
   setCorsOrigin(listenPort);

package/src/server/ports.ts

@@ -49,14 +49,30 @@ export type FindAvailablePortOptions = {
   /** How long to keep retrying the preferred port before falling back to an ephemeral port. */
   preferRetryMs?: number;
   preferRetryIntervalMs?: number;
+  /**
+   * When false, never bind `port: 0` — prefer-retry then throw if the preferred port
+   * stays busy. Used for explicit `ocx start --port N` and service-baked pins so an
+   * update restart cannot hop to a random ephemeral listener (PR #152 gap).
+   */
+  allowEphemeralFallback?: boolean;
 };
 
+export class PortUnavailableError extends Error {
+  readonly port: number;
+  constructor(port: number, hostname: string) {
+    super(`Port ${port} on ${hostname} is still busy after prefer-retry; refusing ephemeral fallback.`);
+    this.name = "PortUnavailableError";
+    this.port = port;
+  }
+}
+
 export async function findAvailablePort(
   preferredPort: number,
   hostname = "127.0.0.1",
   opts: FindAvailablePortOptions = {},
 ): Promise<number> {
   const preferRetryMs = opts.preferRetryMs ?? 0;
+  const allowEphemeral = opts.allowEphemeralFallback !== false;
   if (preferRetryMs > 0) {
     if (await waitForPortAvailable(preferredPort, hostname, {
       timeoutMs: preferRetryMs,
@@ -68,6 +84,10 @@ export async function findAvailablePort(
     return preferredPort;
   }
 
+  if (!allowEphemeral) {
+    throw new PortUnavailableError(preferredPort, hostname);
+  }
+
   return await new Promise((resolve, reject) => {
     const server = createServer();
     server.once("error", reject);