@bitkyc08/opencodex 2.50.0 → 2.52.0-preview.20260911

package/src/cli/index.ts

@@ -48,7 +48,7 @@ import {
   pendingTeardownPathFor,
   quarantinePendingTeardown,
 } from "../config/pending-teardown";
-import { collectStatus, unusedProxyWarningLines } from "./status";
+import { collectStatus, hubStatusLines, remoteHubBannerLine, remoteHubStatusLines, unusedProxyWarningLines } from "./status";
 import { endpointsToProve, everyEndpointProvenDown, sharedTeardownAuthorized, type UninstallObservation } from "./uninstall-plan";
 import { takeFlag } from "./runtime-api";
 
@@ -66,10 +66,11 @@ import { dispatchCommand , decideStartWithLiveOwner } from "./dispatch";
 import { findAvailablePort, isAddrInUse, PortUnavailableError, shouldPersistSelectedPort, waitForPortAvailable } from "../server/ports";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import { createReadinessGate } from "../server/readiness";
+import { isApiAuthRequired } from "../server/auth-cors";
 import { runReady, type ReadyArgs } from "./ready";
 import { runCli } from "./root";
-import { isProcessAlive, ProxyOwnershipRefusedError, stopProxy } from "../lib/process-control";
-import { loadServiceTokenFromFile } from "../lib/service-secrets";
+import { isProcessAlive, ProxyOwnershipRefusedError, refusalNextStep, stopProxy } from "../lib/process-control";
+import { startupDataPlaneToken } from "../lib/service-secrets";
 import { assertNotAdminToken, diagnoseService, isServiceOwnershipError, proxyStillLiveAfterStop, serviceCommand, serviceEnvironmentOwnedHere, serviceStartableFromTray, serviceStatusSummary, stopServiceIfInstalledDetailed, uninstallServiceIfInstalled, uninstallServiceDetailed } from "../service";
 import { formatStartupRoutingDetail, startupHealthSummary } from "../codex/autostart-health";
 import { injectSystemEnv, reconcileShellHook, revertSystemEnv, uninstallShellHook } from "../server/system-env";
@@ -81,8 +82,11 @@ import { scheduleCatalogPrewarm } from "./catalog-prewarm";
 import { maybeShowUpdatePrompt } from "../update/notify";
 import { syncModelsToCodex } from "../codex/sync";
 import {
+  HUB_GATED_SKIP_MESSAGE,
+  localClientSkipReason,
   shouldSyncGrokOnStart,
   syncCodexOnStartIfEnabled,
+  type LocalClientSkipReason,
 } from "../codex/desired-state";
 import {
   reconcileClientStartupBeforeReady,
@@ -174,6 +178,19 @@ async function waitForProxy(timeoutMs = 8_000): Promise<LiveProxy | null> {
   return null;
 }
 
+/**
+ * The one startup line for "nothing was written to Codex".
+ *
+ * Two very different facts reached it: the user's own OFF switch, and a hub declining to
+ * rewrite its own local clients. Printing the toggle's wording for the gate is what made
+ * operators hunt for a switch they never set (#4236).
+ */
+function startupLeftCodexNativeLine(reason: LocalClientSkipReason): string {
+  return reason === "hub-gated"
+    ? `   ${HUB_GATED_SKIP_MESSAGE} Startup left Codex native.`
+    : "   Codex integration OFF; startup left Codex native.";
+}
+
 /** Argv for detached `start`, optionally hard-pinning the listen port. */
 function startArgv(port?: number): string[] {
   const args = ["start"];
@@ -190,6 +207,10 @@ async function chooseListenPort(
   const config = loadConfig();
   const preferred = requestedPort ?? config.port ?? 10100;
   const hardPin = requestedPort !== undefined && requestedPort > 0;
+  // Only an EXPLICITLY ported listener reserves a port. The companion form (`{enabled:true}`
+  // with no port) deliberately shares the public port on 127.0.0.1, so treating it as a
+  // reservation — via `effectiveLoopbackListenerPort` — would refuse every start on a
+  // one-port hub and hop the public listener onto an ephemeral port (#4236).
   const reservedLoopbackPort = config.unauthenticatedLoopbackListener?.enabled
     ? config.unauthenticatedLoopbackListener.port
     : undefined;
@@ -271,10 +292,16 @@ async function findProxyOwnerBeforeJournalRecovery(
 }
 
 async function handleStart(options: { block?: boolean } = {}) {
-  // Native (WinSW) service mode has no batch wrapper to read the service token file
-  // into the environment, so the app loads it here before the server binds. The server
+  // Native (WinSW) service mode has no batch wrapper to read the service token file into
+  // the environment, and a FOREGROUND `ocx start` has no wrapper at all — so the app loads
+  // the token here, before the server binds, with the same precedence the launchd plist and
+  // the systemd unit use when they cat the file into the environment. Without the second
+  // source, `ocx start` refused to bind a non-loopback hostname (assertServerAuthConfig)
+  // that the installed service on the same machine was serving happily (#4236). The server
   // auth path reads OPENCODEX_API_AUTH_TOKEN from the environment.
-  const serviceToken = loadServiceTokenFromFile(process.env);
+  const serviceToken = startupDataPlaneToken(process.env, {
+    authRequired: isApiAuthRequired(loadConfig()),
+  });
   if (serviceToken) process.env.OPENCODEX_API_AUTH_TOKEN = serviceToken;
   // The service wrapper (and WinSW via OCX_API_TOKEN_FILE) can still export a colliding
   // token that install now refuses to write. Refuse it here too, before bind, so an
@@ -513,7 +540,7 @@ async function handleStart(options: { block?: boolean } = {}) {
       }
     },
   );
-  if (!startupSync.ran) console.log("   Codex integration OFF; startup left Codex native.");
+  if (!startupSync.ran) console.log(startupLeftCodexNativeLine(localClientSkipReason(config)));
   await refreshOwnedRaycastCatalog(config, port);
   // #1046: one warning per startup, after BOTH writes. The server's cache
   // invalidation happens first and the catalog sync second, so the mtime is only
@@ -579,7 +606,9 @@ async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Prom
         console.error(`⚠️  Model sync skipped: ${e instanceof Error ? e.message : String(e)}`);
         return null;
       });
-      if (synced?.status === "skipped") console.log("   Codex integration OFF; startup left Codex native.");
+      if (synced?.status === "skipped") {
+        console.log(startupLeftCodexNativeLine(synced.skippedReason ?? "desired_disabled"));
+      }
       // Do not refresh Raycast from saved config here: live bind/admission and
       // secondary-listener settings may differ. Explicit sync or server startup
       // owns catalog refresh; ensure must not overwrite a working destination.
@@ -626,7 +655,9 @@ async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Prom
     console.error(`⚠️  Model sync skipped: ${e instanceof Error ? e.message : String(e)}`);
     return null;
   });
-  if (synced?.status === "skipped") console.log("   Codex integration OFF; startup left Codex native.");
+  if (synced?.status === "skipped") {
+    console.log(startupLeftCodexNativeLine(synced.skippedReason ?? "desired_disabled"));
+  }
   // The child performs Raycast refresh with its actual startup config. The
   // parent's pre-spawn snapshot is not authoritative for a client-file write.
   // The child opens /healthz before its best-effort roster reconcile. Await the same idempotent
@@ -952,7 +983,12 @@ async function handleStop() {
       if (detail) console.error(`   ${detail}`);
       if (err instanceof ProxyOwnershipRefusedError) {
         ownershipBlocked = true;
-        console.error("   Skipping shared teardown (native Codex restore, Grok config): the foreign proxy is still running.");
+        // Every refusal `POST /api/stop` produces is written for an API client, so it
+        // recommends `ocx stop` — the command printing it. Following that advice returns
+        // the operator to this exact message, which is the loop #4169 was filed for. The
+        // service manager was already asked to stop above, so name what is actually left.
+        console.error(`   ${refusalNextStep(err.code)}`);
+        console.error("   Skipping shared teardown (native Codex restore, Grok config): the refusing proxy is still running.");
       }
     }
   } else {
@@ -979,7 +1015,9 @@ async function handleStop() {
         if (detail) console.error(`   ${detail}`);
         if (err instanceof ProxyOwnershipRefusedError) {
           ownershipBlocked = true;
-          console.error("   Skipping shared teardown (native Codex restore, Grok config): the foreign proxy is still running.");
+          // Same loop as the tracked-pid path above: the refusal recommends this command.
+          console.error(`   ${refusalNextStep(err.code)}`);
+          console.error("   Skipping shared teardown (native Codex restore, Grok config): the refusing proxy is still running.");
         }
       }
     } else if (live) {
@@ -1345,12 +1383,22 @@ async function handleStatus() {
     return;
   }
 
+  // First line of the report, above the proxy line, deliberately (#4236): on a connected client
+  // the provider/login/model lines describe the HUB, and the lines that describe this machine
+  // are tagged `(local)`. A reader who sees neither draws the wrong conclusion from a correct
+  // report — an agent read `xai ✗ not logged in` off a client and decided the hub could not
+  // serve grok.
+  const remoteHubBanner = remoteHubBannerLine(status.json.remoteHub);
+  if (remoteHubBanner) console.log(remoteHubBanner);
+  // `(local)` only while connected: on a standalone install every line is local, and tagging
+  // them all would be noise that trains the reader to skip the tag.
+  const local = status.json.remoteHub.connected ? " (local)" : "";
   if (status.json.proxy.pid || status.json.proxy.health.ok) {
-    console.log(`✅ Proxy: ${status.proxyLabel}`);
+    console.log(`✅ Proxy: ${status.proxyLabel}${local}`);
   } else {
-    console.log(`❌ Proxy: ${status.proxyLabel}`);
+    console.log(`❌ Proxy: ${status.proxyLabel}${local}`);
   }
-  console.log(`   Health: ${status.healthLabel}`);
+  console.log(`   Health: ${status.healthLabel}${local}`);
   if (status.json.claudeDesktop.desiredEnabled && !status.json.claudeDesktop.policy.ok) {
     console.log(`   ⚠️  Claude Desktop 3P health: ${status.json.claudeDesktop.policy.status}`);
     console.log(`      ${status.json.claudeDesktop.policy.message}`);
@@ -1390,25 +1438,31 @@ async function handleStatus() {
       ? "     Restart with 'ocx start', or refresh the installed service: 'ocx service repair'."
       : "     Restart with 'ocx start', or install the persistent service: 'ocx service install'.");
   }
-  console.log(`   Dashboard: ${status.json.dashboard.url}`);
-  console.log(`   Config: ${status.json.paths.config}`);
-  console.log(`   PID file: ${status.json.paths.pid}`);
-  console.log(`   Runtime: ${status.json.paths.runtime}`);
-  console.log(`   Runtime source: ${status.json.runtime.source}${status.json.runtime.overrideEnv ? ` (${status.json.runtime.overrideEnv})` : ""}`);
-  console.log(`   Default provider: ${status.json.defaultProvider}`);
+  console.log(`   Dashboard: ${status.json.dashboard.url}${local}`);
+  console.log(`   Config: ${status.json.paths.config}${local}`);
+  console.log(`   PID file: ${status.json.paths.pid}${local}`);
+  console.log(`   Runtime: ${status.json.paths.runtime}${local}`);
+  console.log(`   Runtime source: ${status.json.runtime.source}${status.json.runtime.overrideEnv ? ` (${status.json.runtime.overrideEnv})` : ""}${local}`);
+  // On a client this is the local default, which routing does not use — the hub applies its own.
+  console.log(`   Default provider: ${status.json.defaultProvider}${local}`);
+  // One block rather than six scattered lines, and only on a hub: `hubStatusLines` owns the
+  // sentences so they are testable without spawning the CLI. It prints no token value.
+  if (status.json.hub) {
+    for (const line of hubStatusLines(status.json.hub)) console.log(`   ${line}`);
+  }
   console.log(`   Remote hub: ${status.json.connection.state}${status.json.connection.serverUrl ? ` (${status.json.connection.serverUrl})` : ""}`);
   if (status.json.connection.state === "invalid" || status.json.connection.state === "mismatched") {
     console.log(`   ⚠️  ${status.json.connection.reason}`);
   }
-  console.log(`   Codex autostart: ${status.json.codexAutostart ? "enabled" : "disabled"}`);
-  console.log(`   Restart safety: ${startupHealthSummary(status.json.startup)}`);
-  console.log(`   ${formatStartupRoutingDetail(status.json.startup)}`);
-  console.log(`   Service: ${status.json.service.summary}`);
-  console.log(`   ${status.json.codexShim.summary}`);
-  console.log(`   Codex runtime: ${status.json.codexRuntime.path}`);
-  console.log(`   Codex version: ${status.json.codexRuntime.version ?? "unknown"}`);
-  console.log(`   Codex source: ${status.json.codexRuntime.source}`);
-  console.log(`   Codex home: ${status.json.codexHome.effectiveCodexHome}`);
+  console.log(`   Codex autostart: ${status.json.codexAutostart ? "enabled" : "disabled"}${local}`);
+  console.log(`   Restart safety: ${startupHealthSummary(status.json.startup)}${local}`);
+  console.log(`   ${formatStartupRoutingDetail(status.json.startup)}${local}`);
+  console.log(`   Service: ${status.json.service.summary}${local}`);
+  console.log(`   ${status.json.codexShim.summary}${local}`);
+  console.log(`   Codex runtime: ${status.json.codexRuntime.path}${local}`);
+  console.log(`   Codex version: ${status.json.codexRuntime.version ?? "unknown"}${local}`);
+  console.log(`   Codex source: ${status.json.codexRuntime.source}${local}`);
+  console.log(`   Codex home: ${status.json.codexHome.effectiveCodexHome}${local}`);
   if (status.json.codexHome.warning) {
     console.log(`   ⚠️  ${status.json.codexHome.warning}`);
     console.log(`      Action: ${status.json.codexHome.action}`);
@@ -1430,7 +1484,17 @@ async function handleStatus() {
   const { collectOAuthHealthEntriesForCli, oauthLoginSummary } = await import("../oauth");
   const { emailMaskingEnabled } = await import("../lib/privacy");
   const { formatOAuthHealthForStatus } = await import("./status-oauth");
-  console.log(`   OAuth logins:`);
+  // On a connected client the HUB's providers and logins come first, because they are the ones
+  // that decide what a request can route to. The local block still prints — an operator debugging
+  // a half-migrated machine needs to see it — but under a heading that says it is not in use, and
+  // below the hub's, so the hub's is what a reader (or an agent) encounters first (#4236).
+  for (const line of remoteHubStatusLines(status.json.remoteHub)) console.log(`   ${line}`);
+  if (status.json.remoteHub.connected) {
+    console.log(status.json.remoteHub.stateSource === "unavailable"
+      ? "   Local-only credential state (this is NOT the hub's; the hub's state could not be read):"
+      : "   Local-only (not used for routing while connected):");
+  }
+  console.log(`   OAuth logins${local}:`);
   // The operator's own `privacy.maskEmails` decision applies to the CLI too: `ocx status` is not
   // the dashboard, but it reads the same stored addresses, and a flag that only moved one of the
   // two would leave the operator unable to tell which surface they had configured.

package/src/cli/launcher-context.ts

@@ -1,5 +1,5 @@
 /**
- * Trusted facts captured by the plain-Node npm launcher before Bun auto-loads
+ * Trusted facts captured by the plain-Node package launcher before Bun auto-loads
  * project dotenv files. The random proof travels in argv while the context
  * travels in the environment, so a project `.env` cannot forge the pair during
  * an ordinary `ocx ...` invocation.

package/src/cli/registry.ts

@@ -64,9 +64,17 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     usage: "ocx service [install|repair|restart|start|stop|status|uninstall|remove]",
     summary: "Run as a background service.",
     details: [
-      "With no subcommand, installs when absent or repairs/restarts an existing service.",
-      "`restart` aliases `repair`; healthy Windows tasks are reused, while stale definitions may re-register and elevate.",
-      "Use `ocx service status` to see diagnostics and log paths.",
+      "With no subcommand, installs when absent or repairs an existing service.",
+      "`repair` refreshes the definition and reloads the manager only when something changed, so repairing a healthy service is not an outage.",
+      "`restart` is the same refresh but always restarts: on macOS an unchanged, already-loaded job is kickstarted in place. Healthy Windows tasks are reused, while stale definitions may re-register and elevate.",
+      "Use `ocx service status` to see diagnostics and log paths. On macOS it reports four states:",
+      "loaded from the current plist, loaded from an OLDER plist (repair), not loaded (repair), or",
+      "`launchd state could not be verified` -- which is an unanswerable probe, NOT a down service.",
+      "Data-plane token: nothing has to be exported by hand. On a non-loopback hostname install/repair uses",
+      "OPENCODEX_API_AUTH_TOKEN when set, otherwise reuses the existing owner-only ~/.opencodex/service-api-token,",
+      "otherwise generates one; the launch wrapper reads that file at start and the value never enters a plist,",
+      "a unit file, or argv. An ADMIN token in OPENCODEX_API_AUTH_TOKEN is refused -- unset it and rerun.",
+      "Repair and restart never ask for the environment variable again once the token file exists.",
     ],
   },
   {
@@ -155,6 +163,38 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "The printed grant is secret, single-use, short-lived, and must not be persisted.",
     ],
   },
+  {
+    name: "hub",
+    usage: "ocx hub invite [--json] [--data-url <origin>] [--management-url <origin>] [--clients codex,claude]",
+    summary: "Hub-side commands. `invite` prints a ready-to-run `ocx connect` line for one more machine.",
+    details: [
+      "Topology: a hub serves ONE port. Remote machines dial `hostname:port` with their own per-client",
+      "key; the hub's own local processes dial `127.0.0.1:<same port>` with no credential, through the",
+      "loopback companion listener enabled by `unauthenticatedLoopbackListener: {\"enabled\": true}`.",
+      "The browser-facing management plane is separate: a loopback-only ingress published by an",
+      "operator-owned HTTPS frontend (Tailscale Serve) and advertised as hub.managementPublicOrigin.",
+      "",
+      "Nothing needs to be exported by hand. `ocx service install` provisions an owner-only data-plane",
+      "token at ~/.opencodex/service-api-token and the launch wrapper reads it at start; the value never",
+      "enters a plist, a unit file, argv, or the environment you typed in. Never copy that file to another",
+      "machine -- every client gets its own revocable key from the pairing exchange.",
+      "",
+      "invite requires a running hub and mints a single-use, short-lived pairing code through the same",
+      "attested local route `ocx gui pair` uses, then prints the exact command to run on the other",
+      "machine. The code is bound to hub.managementPublicOrigin and to the connecting machine's local",
+      "browser origin (`http://localhost:10100` unless corsAllowOrigins names another loopback origin);",
+      "the bound origin is always printed, and a different one names the port the client needs.",
+      "--data-url overrides the advertised data origin; hub.dataPublicOrigin is the persistent form, and",
+      "the fallback is http://<bind address>:<port>. A loopback or wildcard bind has no such address, so",
+      "invite refuses instead of advertising http://localhost:<port>, which would tell the other machine",
+      "to dial itself and spend the code.",
+      "--management-url is a CONFIRMATION, not an override: the grant is bound to",
+      "hub.managementPublicOrigin, so a differing value is refused instead of printed.",
+      "--clients chooses which client configs the printed ocx connect line will point at the hub.",
+      "--json emits { code, expiresAt, dataUrl, managementUrl, command }. Do not persist the code.",
+      "Hub state, including the data token and the companion listener, is reported by `ocx status`.",
+    ],
+  },
   {
     name: "update",
     usage: "ocx update [--tag latest|preview]",