@bitkyc08/opencodex 2.52.0 → 2.53.0

package/src/cli/account.ts

@@ -41,6 +41,7 @@ const REPLACEMENT_STYLE_OAUTH = new Set<string>();
 
 const ACCOUNT_USAGE = `Usage:
   ocx account list [provider] [--json] [--all] [--quota [--refresh]]
+  ocx account history openai <pool-account-id> [--limit <1-200>] [--json]
   ocx account current <provider> [--json]
   ocx account use <provider> <account-or-key-id|main> [--json]
   ocx account refresh <provider> [--json]
@@ -50,7 +51,7 @@ const ACCOUNT_USAGE = `Usage:
   ocx account pause <provider> <account-id|main> [--json]
   ocx account resume <provider> <account-id|main> [--json]
   ocx account pause-exhausted <provider> [--json]
-  ocx account strategy <provider> [<quota|round-robin|fill-first>] [--json]
+  ocx account strategy <provider> [<quota|round-robin|fill-first|reset-first>] [--json]
   ocx account sticky <provider> [<1-100>] [--json]
   ocx account remove <provider> <account-or-key-id|main> --yes [--json]
   ocx account clear-cooldown <provider> <account-id|main> [--json]
@@ -61,7 +62,7 @@ const ACCOUNT_USAGE = `Usage:
   ocx account cancel <provider> [--flow <flow-id>] [--json]
   ocx account reset-credits <account-id|main> [--consume --yes] [--json]
   ocx account grok-reset-coupons [<account-id>] [--consume --yes] [--token-id <token-id>] [--json]
-  ocx account main <doctor|list|register|add|switch|recover> ...
+  ocx account main <doctor|list|register|add|reauth|switch|recover> ...
 
 List and switch provider accounts and API-key pools (masked output only).
 'main' selects the Codex App login for the openai account pool.`;
@@ -101,6 +102,9 @@ function statusText(row: AccountRow): string {
   if (row.active) parts.push(row.type === "codex" ? "selected" : "active");
   if (row.needsReauth) parts.push("needs-reauth");
   if (row.validationPending) parts.push("validation-pending");
+  if (row.selectionExcludedReason === "plan_excluded") {
+    parts.push(`not-auto-selected(plan=${row.selectionExcludedPlan ?? row.plan ?? "unknown"})`);
+  }
   return parts.join(" ");
 }
 
@@ -115,7 +119,7 @@ function priorityText(row: AccountRow): string {
  * decides on before a long session. The full breakdown stays in `--json`.
  */
 function quotaText(row: AccountRow): string {
-  if ((row as { quotaUnavailable?: boolean }).quotaUnavailable) return "unavailable";
+  if (row.quotaUnavailable) return row.quotaFailure ? `unavailable (${row.quotaFailure})` : "unavailable";
   const quota = row.quota;
   if (!quota) return "-";
   const parts: string[] = [];
@@ -335,6 +339,10 @@ export async function cmdAccount(args: string[], deps: AccountDeps = {}): Promis
   const [sub, ...rest] = args;
   try {
     if (sub === "list") return await cmdList(rest, deps);
+    if (sub === "history") {
+      const { cmdAccountHistory } = await import("./account-history");
+      return await cmdAccountHistory(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);

package/src/cli/capabilities.ts

@@ -95,6 +95,85 @@ export const HEAD_CAPABILITIES: readonly HeadCapability[] = [
  * A capability must not name a route the command does not actually fetch.
  */
 export const CAPABILITIES: readonly Capability[] = [
+  {
+    "command": [
+      "remote-workspace",
+      "pair"
+    ],
+    "summary": "Enroll this executor with one Hub using a one-time code from stdin and locally approved roots.",
+    "routes": [],
+    "flags": [
+      {
+        "name": "--json",
+        "value": "boolean",
+        "summary": "Emit the public local executor status."
+      },
+      {
+        "name": "--pairing-code-stdin",
+        "value": "boolean",
+        "summary": "Read the one-time pairing code from stdin."
+      },
+      {
+        "name": "--root",
+        "value": "string",
+        "summary": "Approve an absolute workspace directory; repeatable."
+      },
+      {
+        "name": "--toolchain-root",
+        "value": "string",
+        "summary": "Approve a read-only toolchain directory; repeatable."
+      },
+      {
+        "name": "--executor-helper",
+        "value": "string",
+        "summary": "Select a reviewed native helper file."
+      },
+      {
+        "name": "--name",
+        "value": "string",
+        "summary": "Name this executor."
+      }
+    ],
+    "mutates": true,
+    "json": "payload",
+    "details": [
+      "Executor-local operation; Hub consent and session control stay in the dashboard."
+    ]
+  },
+  {
+    "command": [
+      "remote-workspace",
+      "agent"
+    ],
+    "summary": "Keep the paired executor connected to its Hub.",
+    "routes": [],
+    "flags": [],
+    "mutates": true,
+    "json": "none",
+    "details": [
+      "Executor-local operation; Hub consent and session control stay in the dashboard."
+    ]
+  },
+  {
+    "command": [
+      "remote-workspace",
+      "status"
+    ],
+    "summary": "Read local executor enrollment and available capabilities without printing credentials.",
+    "routes": [],
+    "flags": [
+      {
+        "name": "--json",
+        "value": "boolean",
+        "summary": "Emit the public local executor status."
+      }
+    ],
+    "mutates": false,
+    "json": "payload",
+    "details": [
+      "Executor-local operation; Hub consent and session control stay in the dashboard."
+    ]
+  },
   {
     command: ["models", "price"],
     summary: "Read the saved manual price for an exact provider/model selector.",
@@ -235,6 +314,40 @@ export const CAPABILITIES: readonly Capability[] = [
       "Headless services usually have no unlocked keychain session; prefer ${ENV_VAR} references there.",
     ],
   },
+  {
+    command: ["account", "history"],
+    summary: "Cached quota observations for one stored Codex pool account.",
+    routes: [{ method: "GET", path: "/api/codex-auth/quota/history" }],
+    flags: [
+      { name: "--json", value: "boolean", summary: "Emit the bounded observation history." },
+      { name: "--limit", value: "number", summary: "Return the newest 1 to 200 observations." },
+    ],
+    mutates: false,
+    json: "payload",
+    details: ["Use account history openai <pool-account-id>. Reads cached observations only; no refresh or warmup. Native main is not included."],
+  },
+  {
+    command: ["account", "main", "reauth"],
+    summary: "Reauthenticate the native main Codex login with a device code (#3898); headless hubs need no Codex App or keyring.",
+    routes: [
+      { method: "POST", path: "/api/codex-auth/main/reauth-device" },
+      { method: "GET", path: "/api/codex-auth/main/reauth-device" },
+      { method: "DELETE", path: "/api/codex-auth/main/reauth-device" },
+    ],
+    flags: [
+      { name: "--device", value: "boolean", summary: "Run the device-code flow (the only reauth mode)." },
+      { name: "--no-wait", value: "boolean", summary: "Print the flow handle and code without waiting for completion." },
+      { name: "--flow", value: "string", summary: "Flow id for status and cancel." },
+      { name: "--json", value: "boolean", summary: "Emit the flow status as JSON." },
+    ],
+    mutates: true,
+    json: "payload",
+    details: [
+      "Same-identity reauth only: the device login must complete for the ChatGPT account that already holds the native main slot, and the commit is fenced by the exclusive claim plus a path/hash/inode snapshot.",
+      "/api/codex-auth/login stays pool-only and keeps rejecting __main__; this namespace is the only device-reauth surface for the native main slot.",
+      "Payloads carry only flowId, status, the verification URL, the device code, and a closed set of failure codes -- never tokens, emails, or raw account ids.",
+    ],
+  },
   {
     command: ["account", "list"],
     summary: "Codex OAuth accounts with pool priority and pause state.",

package/src/cli/catalog.ts

@@ -0,0 +1,109 @@
+import { afterCatalogWriteHandleAppServers } from "../codex/app-server-processes";
+import { pullRemoteCatalog, RemoteCatalogError } from "../codex/catalog/remote";
+import { hasHelpFlag, printSubcommandUsage } from "./help";
+
+export interface CatalogPullEnvelope {
+  schemaVersion: 1;
+  ok: boolean;
+  status: "updated" | "unchanged" | "failed";
+  catalogWritten: boolean;
+  cacheSynced: boolean;
+  codexRestarted: boolean;
+  modelCount?: number;
+  code?: string;
+}
+
+function optionValue(args: string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+export async function handleCatalogCommand(args: string[]): Promise<number> {
+  if (hasHelpFlag(args)) { printSubcommandUsage("catalog"); return 0; }
+  const json = args.includes("--json");
+  const restartCodex = args.includes("--restart-codex");
+  const authEnv = optionValue(args, "--auth-env");
+  const positionals = args.filter((arg, index) => {
+    if (arg === "--auth-env") return false;
+    if (index > 0 && args[index - 1] === "--auth-env") return false;
+    return !arg.startsWith("-");
+  });
+  const knownFlags = new Set(["--json", "--restart-codex", "--auth-env"]);
+  const unknown = args.find((arg, index) => arg.startsWith("-") && !knownFlags.has(arg) && args[index - 1] !== "--auth-env");
+  const validEnvName = authEnv === undefined || /^[A-Za-z_][A-Za-z0-9_]*$/.test(authEnv);
+  if (positionals[0] !== "pull" || positionals.length !== 2 || unknown || !validEnvName
+    || args.includes("--auth-env") !== (authEnv !== undefined)) {
+    const envelope: CatalogPullEnvelope = {
+      schemaVersion: 1, ok: false, status: "failed", catalogWritten: false,
+      cacheSynced: false, codexRestarted: false, code: "usage",
+    };
+    if (json) console.log(JSON.stringify(envelope));
+    else console.error("Usage: ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex]");
+    return 2;
+  }
+  let token: string | undefined;
+  if (authEnv !== undefined) {
+    token = process.env[authEnv];
+    if (token === undefined) {
+      const envelope: CatalogPullEnvelope = {
+        schemaVersion: 1, ok: false, status: "failed", catalogWritten: false,
+        cacheSynced: false, codexRestarted: false, code: "auth_env_missing",
+      };
+      if (json) console.log(JSON.stringify(envelope));
+      else console.error(`Catalog authentication environment variable ${authEnv} is not set.`);
+      return 1;
+    }
+  }
+  try {
+    const result = await pullRemoteCatalog(positionals[1]!, { token });
+    let codexRestarted = false;
+    let restartIncomplete = false;
+    if (result.catalogWritten) {
+      const processLog = json
+        ? { log: (...values: unknown[]) => console.error(...values), error: (...values: unknown[]) => console.error(...values) }
+        : console;
+      const processResult = afterCatalogWriteHandleAppServers({ restart: restartCodex, log: processLog });
+      const restart = processResult.restart;
+      if (restart) {
+        // A partial stop is not a restart. `restartCodexAppServers` reports failures and
+        // survivors without throwing, so counting `stopped` alone reported success while a
+        // stale app-server was still serving the previous catalog from memory.
+        codexRestarted = restart.failed.length === 0
+          && restart.surviving.length === 0
+          && restart.stopped.length === processResult.processes.length;
+        restartIncomplete = !codexRestarted;
+      }
+    }
+    if (restartIncomplete) {
+      // The catalog and cache landed; only the restart did not finish. Saying the pull failed
+      // and wrote nothing would be a second false report, so the envelope keeps the real
+      // write state and `ok` carries the failure.
+      const envelope: CatalogPullEnvelope = {
+        schemaVersion: 1, ok: false, status: result.status,
+        catalogWritten: result.catalogWritten, cacheSynced: result.cacheSynced,
+        codexRestarted: false, modelCount: result.modelCount, code: "restart_incomplete",
+      };
+      if (json) console.log(JSON.stringify(envelope));
+      else console.error("Remote Codex catalog installed, but a Codex app-server is still running the previous catalog.");
+      return 1;
+    }
+    const envelope: CatalogPullEnvelope = {
+      schemaVersion: 1, ok: true, status: result.status,
+      catalogWritten: result.catalogWritten, cacheSynced: result.cacheSynced,
+      codexRestarted, modelCount: result.modelCount,
+    };
+    if (json) console.log(JSON.stringify(envelope));
+    else if (result.status === "unchanged") console.log("Remote Codex catalog is unchanged; no files or processes were touched.");
+    else console.log(`Remote Codex catalog installed (${result.modelCount} models) and models_cache.json synchronized.`);
+    return 0;
+  } catch (error) {
+    const code = error instanceof RemoteCatalogError ? error.code : "write_failed";
+    const envelope: CatalogPullEnvelope = {
+      schemaVersion: 1, ok: false, status: "failed", catalogWritten: false,
+      cacheSynced: false, codexRestarted: false, code,
+    };
+    if (json) console.log(JSON.stringify(envelope));
+    else console.error(error instanceof RemoteCatalogError ? error.message : "Remote catalog installation failed");
+    return code === "lock_busy" ? 3 : 1;
+  }
+}

package/src/cli/dispatch.ts

@@ -424,6 +424,7 @@ const commandRunners: Record<string, CommandRunner> = {
       // Explicit sync with the integration OFF still refreshes the catalog/cache
       // for side profiles that consume the proxy without injection.
       console.log(synced.message ?? "Codex integration is OFF; catalog refreshed, Codex config untouched.");
+      if (!synced.ok) code = 1;
     } else if (!synced.ok) {
       code = 1;
       console.error("Codex sync did not complete. Fix the reported Codex config issue and retry.");
@@ -481,10 +482,18 @@ const commandRunners: Record<string, CommandRunner> = {
     const { handleConnectCommand } = await import("./connect");
     return await handleConnectCommand(deps.args.slice(1));
   },
+  "remote-workspace": async deps => {
+    const { runRemoteWorkspaceCommand } = await import("./remote-workspace");
+    return await runRemoteWorkspaceCommand(deps.args.slice(1));
+  },
   disconnect: async deps => {
     const { handleDisconnectCommand } = await import("./connect");
     return await handleDisconnectCommand(deps.args.slice(1));
   },
+  catalog: async deps => {
+    const { handleCatalogCommand } = await import("./catalog");
+    return await handleCatalogCommand(deps.args.slice(1));
+  },
   "sync-cache": async deps => {
     const cacheArgs = deps.args.slice(1);
     const restartCodex = cacheArgs.includes("--restart-codex");

package/src/cli/help.ts

@@ -41,10 +41,12 @@ Usage:
   ocx tray <sub>              Windows status tray (install|start|stop|status|uninstall)
   ocx ensure                  Ensure the proxy is running and Codex config/cache are current
   ocx connect <url>           Connect this machine to a remote OpenCodex hub (credential via stdin)
+  ocx remote-workspace <sub>  Pair/run an OCX-only remote execution computer
   ocx disconnect              Restore local state and clear the hub connection
   ocx sync [--restart-codex]  Fetch models from providers and inject into Codex config
   ocx sync-cache [--restart-codex]
                               Refresh Codex's model cache from the active catalog
+  ocx catalog pull <https-url> Install a validated remote catalog and refresh the Codex cache
   ocx status                  Check proxy server status (on a hub: one block with its ports and token source)
   ocx doctor                  Diagnose environment/network issues (WSL, proxy, ChatGPT reachability)
   ocx doctor --reclaim-response-temps

package/src/cli/index.ts

@@ -63,7 +63,7 @@ import {
 import { requestBoundSystemRestart } from "./system-restart-client";
 import { installCrashGuards } from "../lib/crash-guard";
 import { dispatchCommand , decideStartWithLiveOwner } from "./dispatch";
-import { findAvailablePort, isAddrInUse, PortUnavailableError, shouldPersistSelectedPort, waitForPortAvailable } from "../server/ports";
+import { AuxiliaryListenerBindError, 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";
@@ -391,7 +391,7 @@ async function handleStart(options: { block?: boolean } = {}) {
       scheduleCatalogPrewarm();
       break;
     } catch (err) {
-      if (!isAddrInUse(err) || attempt >= 2) throw err;
+      if (err instanceof AuxiliaryListenerBindError || !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";

package/src/cli/observe.ts

@@ -14,6 +14,10 @@ import { formatUsageReport } from "./usage-report";
 import { USAGE_RANGES, USAGE_SURFACES, type UsageSummary } from "../usage/summary";
 import { parseUsageTimeWindow, type UsageTimeWindow } from "../usage/time-range";
 import { redactSecretString } from "../lib/redact";
+import { readClientConnectionState, sameClientConnectionOwner } from "../client/state";
+import { readServiceApiTokenState } from "../lib/service-secrets";
+import { fetchHubUsage } from "../client/hub-client";
+import type { HubUsageReport } from "../remote/hub-usage";
 
 const USAGE = `Usage:
   ocx observe logs [--provider <name>] [--model <id>] [--status <code>]
@@ -175,7 +179,30 @@ async function usage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     throw new CliUsageError(`--surface must be one of ${USAGE_SURFACES.join(", ")}`, USAGE);
   }
   rejectArgs(args.map(redactSecretString), USAGE);
-  const result = await runtimeRequest<UsageSummary>(`/api/usage${query({ range, surface, provider, model, since: window?.since, until: window?.until })}`, {}, deps);
+  const suffix = query({ range, surface, provider, model, since: window?.since, until: window?.until });
+  const connection = readClientConnectionState();
+  let result: UsageSummary | HubUsageReport;
+  if (connection.kind === "invalid" || connection.kind === "mismatched") {
+    throw new Error(`Client usage unavailable: ${connection.reason}`);
+  }
+  if (connection.kind === "connected") {
+    const token = readServiceApiTokenState();
+    if (token.kind !== "present" || token.fingerprint !== connection.value.tokenFingerprint) {
+      throw new Error("Client usage unavailable: the enrolled data key is missing or changed; repair the client connection");
+    }
+    result = await fetchHubUsage(connection.value.serverUrl, token.token, new URLSearchParams(suffix), {
+      fetchImpl: deps.fetchImpl, timeoutMs: 60_000,
+    });
+    const current = readClientConnectionState();
+    const currentToken = readServiceApiTokenState();
+    if (current.kind !== "connected" || !sameClientConnectionOwner(current.value, connection.value)
+      || current.value.tokenFingerprint !== token.fingerprint
+      || currentToken.kind !== "present" || currentToken.fingerprint !== token.fingerprint) {
+      throw new Error("Client connection changed while reading usage; retry for the current connection");
+    }
+  } else {
+    result = await runtimeRequest<UsageSummary>(`/api/usage${suffix}`, {}, deps);
+  }
   // Older daemons ignore custom bounds and return successful preset reports.
   if (window && (result?.customWindow !== true || result.since !== window.since || result.until !== window.until)) {
     throw new Error("The server did not confirm the requested custom usage window. Upgrade and restart the proxy, then retry.");

package/src/cli/opencode.ts

@@ -41,6 +41,9 @@ import type {
 } from "../clients/config-export";
 import { filterCatalogVisibleModels, visibleNativeSlugs } from "../codex/catalog";
 import { commandInvocation } from "../lib/win-exec";
+import { configuredAdminToken } from "../lib/admin-secrets";
+import { localManagementOrigin } from "../lib/local-destinations";
+import { directLocalHttpFetch } from "../server/direct-local-http";
 import { loadServiceTokenFromFile, serviceApiTokenFilePath } from "../lib/service-secrets";
 import { providerCodexAccountMode } from "../providers/registry";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
@@ -306,17 +309,38 @@ function opencodeBlocks(
 /** Default deadline for authenticated GET /api/models during `ocx opencode` launch. */
 export const OPENCODE_PROXY_MODELS_TIMEOUT_MS = 8_000;
 
+function opencodeManagementOrigin(live: LiveProxy, override?: string): string {
+  if (!override && (!Number.isInteger(live.port) || live.port < 1 || live.port > 65535)) {
+    throw new Error("The local management port is invalid.");
+  }
+  let url: URL;
+  try { url = new URL(override ?? `http://${probeHostname(live.hostname)}:${live.port}`); }
+  catch { throw new Error("The local management address is invalid."); }
+  if (url.protocol !== "http:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new Error("The catalog requires a local HTTP management origin without credentials or a path.");
+  }
+  const host = url.hostname.toLowerCase();
+  if (["localhost", "localhost.", "127.0.0.1", "0.0.0.0", "[::]"].includes(host)) url.hostname = "127.0.0.1";
+  else if (host !== "[::1]") {
+    throw new Error("The catalog requires a loopback management listener. On a hub, enable hub.managementIngress.");
+  }
+  const port = Number(url.port || 80);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("The local management port is invalid.");
+  return url.origin;
+}
+
 /** Fetch the live model catalog from a running proxy's management API. */
 export async function fetchOpencodeProxyModels(
   live: LiveProxy,
-  apiKey: string,
-  deps: { fetchImpl?: typeof fetch; timeoutMs?: number } = {},
+  managementToken: string,
+  deps: { fetchImpl?: typeof fetch; timeoutMs?: number; managementOrigin?: string } = {},
 ): Promise<OpencodeProxyModelRow[]> {
-  const baseUrl = `http://${probeHostname(live.hostname)}:${live.port}`;
-  const fetchImpl = deps.fetchImpl ?? fetch;
+  const baseUrl = opencodeManagementOrigin(live, deps.managementOrigin);
+  const fetchImpl = deps.fetchImpl ?? directLocalHttpFetch;
   const headers = new Headers({ Accept: "application/json" });
-  const token = apiKey.trim();
-  if (token) headers.set("X-OpenCodex-API-Key", token);
+  const token = managementToken.trim();
+  if (!token) throw new Error("No local admin token is available for the model catalog.");
+  headers.set("X-OpenCodex-API-Key", token);
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), deps.timeoutMs ?? OPENCODE_PROXY_MODELS_TIMEOUT_MS);
   const abortIfTimedOut = (): Promise<never> => new Promise((_, reject) => {
@@ -337,10 +361,16 @@ export async function fetchOpencodeProxyModels(
     response = await Promise.race([
       fetchImpl(`${baseUrl}/api/models`, {
         headers,
+        redirect: "error",
+        cache: "no-store",
         signal: controller.signal,
       }),
       abortIfTimedOut(),
     ]);
+    if (response.status >= 300 && response.status < 400) {
+      void response.body?.cancel().catch(() => {});
+      throw new Error("Management catalog redirects are refused.");
+    }
     text = await Promise.race([response.text(), abortIfTimedOut()]);
   } catch (error) {
     const timedOut = error instanceof Error && error.name === "AbortError";
@@ -584,7 +614,7 @@ export function buildOpencodeEnv(
   const runtimeConfig = mergeOpencodeRuntimeConfig(base[OPENCODE_CONFIG_CONTENT_ENV], blocks);
   if (isOpencodeRuntimeConfigError(runtimeConfig)) return runtimeConfig;
   return {
-    ...base,
+    ...Object.fromEntries(Object.entries(base).filter(([name]) => name.toUpperCase() !== "OPENCODEX_ADMIN_AUTH_TOKEN")),
     [OPENCODE_CONFIG_CONTENT_ENV]: serializeOpencodeRuntimeConfig(runtimeConfig),
     [OPENCODE_API_KEY_ENV]: apiKey,
   };
@@ -652,7 +682,11 @@ export async function cmdOpencode(args: string[]): Promise<number> {
   const apiKey = opencodeApiKey(startupConfig);
   let proxyModels: OpencodeProxyModelRow[];
   try {
-    proxyModels = await fetchOpencodeProxyModels(live, apiKey);
+    const managementToken = configuredAdminToken();
+    if (!managementToken) throw new Error("No local admin token is available; check the running proxy's home.");
+    proxyModels = await fetchOpencodeProxyModels(live, managementToken, {
+      managementOrigin: localManagementOrigin({ ...startupConfig, hostname: live.hostname }, live.port),
+    });
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error);
     console.error(`❌ Could not fetch the model catalog from the proxy: ${reason}`);

package/src/cli/provider-runtime.ts

@@ -1,3 +1,4 @@
+import { modelCapabilitiesConfigError } from "../config/provider-validation";
 import {
   CliUsageError,
   csv,
@@ -39,7 +40,7 @@ const USAGE = `Usage:
       [--auth-mode <key|forward|oauth|local|->] [--note <text|->]
       [--api-key-transport <x-api-key|bearer|->]
       [--headers <json>] [--enabled <on|off>] [--live-models <on|off>]
-      [--retain-models <id,id|->]
+      [--retain-models <id,id|->] [--model <id> --text-only]
       [--xai-chat <on|off>]
       [--allow-private-network <on|off>] [--json]
   ocx provider test <name> [--json]
@@ -72,7 +73,16 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const liveModels = takeBooleanOption(args, "--live-models");
   const allowPrivateNetwork = takeBooleanOption(args, "--allow-private-network");
   const xaiChat = takeBooleanOption(args, "--xai-chat");
+  const textOnly = takeFlag(args, "--text-only");
+  const capabilityModel = takeOption(args, "--model");
   rejectArgs(args, USAGE);
+  if (textOnly || capabilityModel !== undefined) {
+    if (!textOnly || capabilityModel === undefined) throw new CliUsageError("--text-only and --model must be supplied together", USAGE);
+    const declaration = { [capabilityModel]: { inputModalities: ["text"] } };
+    const error = modelCapabilitiesConfigError(declaration);
+    if (error) throw new CliUsageError(error, USAGE);
+    patch.modelCapabilities = declaration;
+  }
   if (xaiChat !== undefined) {
     if (name !== "xai") throw new CliUsageError("--xai-chat is valid only for provider xai", USAGE);
     patch.xaiResponsesOptIn = !xaiChat;

package/src/cli/provider.ts

@@ -9,7 +9,7 @@
  *   set-default <name>  Change the default provider
  */
 import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig } from "../config";
-import { apiKeyTransportConfigError } from "../config/provider-validation";
+import { apiKeyTransportConfigError, modelCapabilitiesConfigError, mergeModelCapabilities } from "../config/provider-validation";
 import { hasHelpFlag } from "./help";
 import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
 import { providerConfigSeed } from "../providers/derive";
@@ -139,7 +139,7 @@ function handleList(args: string[]): void {
 // provider add
 // ---------------------------------------------------------------------------
 
-const ADD_USAGE = "Usage: ocx provider add <name> [--adapter <adapter>] [--base-url <url>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <model>] [--allow-private-network] [--set-default] [--force] [--json] [--sync]";
+const ADD_USAGE = "Usage: ocx provider add <name> [--adapter <adapter>] [--base-url <url>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <model>] [--model <id> --text-only] [--allow-private-network] [--set-default] [--force] [--json] [--sync]";
 
 async function handleAdd(args: string[]): Promise<void> {
   const name = args[0];
@@ -164,7 +164,13 @@ async function handleAdd(args: string[]): Promise<void> {
   const adapter = consumeFlagValue(restArgs, "--adapter");
   const baseUrl = consumeFlagValue(restArgs, "--base-url");
   const defaultModel = consumeFlagValue(restArgs, "--default-model");
+  const textOnly = consumeFlag(restArgs, "--text-only");
+  const capabilityModel = consumeFlagValue(restArgs, "--model");
   rejectUnknownArgs(restArgs, ADD_USAGE);
+  if (capabilityModel !== undefined && !textOnly) {
+    console.error("Error: --model requires --text-only for provider add.");
+    process.exit(1);
+  }
 
   const config = loadConfig();
 
@@ -224,6 +230,20 @@ async function handleAdd(args: string[]): Promise<void> {
   }
 
   const existingProvider = config.providers[name];
+  if (existingProvider?.modelCapabilities !== undefined && provConfig.modelCapabilities === undefined) {
+    provConfig.modelCapabilities = structuredClone(existingProvider.modelCapabilities);
+  }
+  if (textOnly) {
+    const modelId = capabilityModel ?? defaultModel ?? provConfig.defaultModel;
+    if (!modelId) {
+      console.error("Error: --text-only requires --model or a default model.");
+      process.exit(1);
+    }
+    const declaration = { [modelId]: { inputModalities: ["text"] } };
+    const error = modelCapabilitiesConfigError(declaration);
+    if (error) { console.error(`Error: ${error}.`); process.exit(1); }
+    provConfig.modelCapabilities = mergeModelCapabilities(provConfig.modelCapabilities, declaration);
+  }
   const { initializeProviderModelSelection } = await import("../providers/initial-model-selection");
   initializeProviderModelSelection(name, provConfig, existingProvider, config);
   config.providers[name] = provConfig;

package/src/cli/registry.ts

@@ -107,6 +107,17 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "Credentials are accepted only through stdin; argv and environment credential forms are not supported.",
     ],
   },
+  {
+    name: "remote-workspace",
+    usage: "ocx remote-workspace <pair|agent|status>",
+    summary: "Pair this OCX-only computer with a hub and run its remote workspace executor.",
+    details: [
+      "Pair: ocx remote-workspace pair <hub-url> --pairing-code-stdin --root <absolute-path> [--toolchain-root <absolute-directory>] [--executor-helper <absolute-file>] [--name <device-name>]",
+      "Agent: ocx remote-workspace agent",
+      "Status: ocx remote-workspace status [--json]",
+      "Codex, Claude Code, Pi, provider logins, and API keys remain on the hub; only workspace tools execute here.",
+    ],
+  },
   {
     name: "disconnect",
     usage: "ocx disconnect [--keep-catalog] [--json]",
@@ -132,6 +143,16 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "--restart-desktop-app (Windows only, opt-in) fully restarts the Codex desktop app so its model picker re-reads the catalog. Never implied by --restart-codex: it ends live conversations.",
     ],
   },
+  {
+    name: "catalog",
+    usage: "ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex]",
+    summary: "Install a validated remote /v1/catalog snapshot into Codex.",
+    details: [
+      "Authentication is read only from the named environment variable and sent as a Bearer token.",
+      "HTTPS is required except for loopback HTTP; redirects are refused.",
+      "The catalog and models_cache.json are coordinated under the Codex catalog write lock.",
+    ],
+  },
   { name: "status", usage: "ocx status", summary: "Check proxy server status." },
   {
     name: "doctor",