@bitkyc08/opencodex 2.80.0 → 2.81.0

package/src/cli/integration-plan-dto.ts

@@ -23,6 +23,7 @@ export const FILE_INTEGRATION_CLIENTS = [
   "raycast",
   "omo",
   "cline",
+  "commandcode",
   "kilo",
   "droid",
 ] as const;

package/src/cli/integration-preview.ts

@@ -1,5 +1,6 @@
 /** Preview and explicitly bound mutations use the existing management authority. */
 import type { IntegrationMutationPlan, IntegrationPlanOperation } from "../integrations/mutation-plan";
+import type { IntegrationClientId } from "../integrations/registry";
 import { redactSecretString, redactUserPath } from "../lib/redact";
 import {
   CliUsageError, RuntimeApiError, printData, runtimeRequest, terminalSafeText,
@@ -186,9 +187,15 @@ function reportError(error: unknown): number {
   return 1;
 }
 
-export async function handleIntegrationPreviewCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+export async function handleIntegrationPreviewCommand(argv: string[], deps: RuntimeApiDeps = {}, expectedClientId?: IntegrationClientId): Promise<number> {
   try {
     const intent = parseIntent(argv);
+    if (expectedClientId !== undefined && intent.operation === "restore") {
+      if (intent.client !== undefined || intent.profile !== undefined) throw new CliUsageError("client-specific restore does not accept --client or --profile", USAGE);
+      intent.client = expectedClientId;
+      intent.path = `${clientIntegrationPath(expectedClientId)}/restore${intent.preview ? "/preview" : ""}`;
+      intent.body.expectedClientId = expectedClientId;
+    }
     const result = await runtimeRequest(intent.path, {
       method: intent.preview || intent.operation === "restore" ? "POST" : "PUT",
       redirect: "error", body: JSON.stringify(intent.body),

package/src/cli/integrations.ts

@@ -13,6 +13,7 @@ import {
   type RuntimeApiDeps,
 } from "./runtime-api";
 import { clientIntegrationPath, validateAsideProfile } from "./integration-input";
+import type { IntegrationClientId } from "../integrations/registry";
 
 const CLAUDE_USAGE = `Usage:
   ocx claude config [status] [--json]
@@ -215,7 +216,11 @@ function singleClientStatusLines(result: unknown): string[] {
 export async function handleClientIntegrationCommand(
   argv: string[],
   deps: RuntimeApiDeps = {},
+  expectedClientId?: IntegrationClientId,
 ): Promise<number> {
+  if (expectedClientId !== undefined && argv.some(arg => ["--client", "--profile"].some(flag => arg === flag || arg.startsWith(`${flag}=`)))) {
+    return runCliAction(async () => { throw new CliUsageError("client-specific restore does not accept --client or --profile", CLIENT_USAGE); });
+  }
   if ((argv[0] === "history" || argv[0] === "journal") && argv[1] === "remove") {
     const { handleIntegrationJournalRemove } = await import("./integration-journal");
     return handleIntegrationJournalRemove(argv.slice(2), deps);
@@ -227,7 +232,7 @@ export async function handleClientIntegrationCommand(
   if (argv[0] === "preview" || argv.some(arg => ["--preview", "--plan-fingerprint", "--reasoning-default", "--clear-reasoning-defaults"]
     .some(flag => arg === flag || arg.startsWith(`${flag}=`)))) {
     const { handleIntegrationPreviewCommand } = await import("./integration-preview");
-    return handleIntegrationPreviewCommand(argv, deps);
+    return handleIntegrationPreviewCommand(argv, deps, expectedClientId);
   }
   return runCliAction(async () => {
     const args = [...argv];
@@ -289,9 +294,12 @@ export async function handleClientIntegrationCommand(
       if (client !== undefined && profile === undefined) throw new CliUsageError("restore --client requires --profile", CLIENT_USAGE);
       rejectArgs(args, CLIENT_USAGE);
       if (!opId) throw new CliUsageError("--op <opId> is required", CLIENT_USAGE);
-      const result = await runtimeRequest(profile === undefined ? "/api/client-integrations/restore" : `${clientIntegrationPath("aside", profile)}/restore`, {
+      const restorePath = expectedClientId !== undefined ? `${clientIntegrationPath(expectedClientId)}/restore`
+        : profile === undefined ? "/api/client-integrations/restore" : `${clientIntegrationPath("aside", profile)}/restore`;
+      const result = await runtimeRequest(restorePath, {
         method: "POST",
-        body: JSON.stringify({ opId, confirmDrift }),
+        ...(expectedClientId === undefined ? {} : { redirect: "error" as const }),
+        body: JSON.stringify({ opId, confirmDrift, ...(expectedClientId === undefined ? {} : { expectedClientId }) }),
       }, deps);
       printData(result, wantsJson, [String((result as Record<string, unknown>).message ?? "Restored.")]);
       return;
@@ -387,3 +395,24 @@ export async function handleClaudeInterceptCommand(argv: string[], deps: Runtime
     printData(result, wantsJson, summaryLines(result));
   });
 }
+
+const COMMANDCODE_USAGE = "Usage: ocx commandcode [status|show|list|enable|disable|history|journal|restore] [--json]";
+
+export async function handleCommandcodeCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  const args = [...argv];
+  const verbIndex = args.findIndex(arg => !arg.startsWith("-"));
+  const action = (verbIndex === -1 ? "status" : args[verbIndex]).toLowerCase();
+  const known = ["status", "show", "list", "enable", "disable", "history", "journal", "restore"];
+  if (!known.includes(action)) {
+    console.error(`unknown commandcode command ${action}`);
+    console.error(COMMANDCODE_USAGE);
+    return 2;
+  }
+  const rest = verbIndex === -1 ? args : [...args.slice(0, verbIndex), ...args.slice(verbIndex + 1)];
+  const forwarded = action === "restore" ? [action, ...rest] : [action, ...rest, "--client", "commandcode"];
+  const code = await handleClientIntegrationCommand(forwarded, deps, action === "restore" ? "commandcode" : undefined);
+  if (code === 0 && (action === "enable" || action === "disable")) {
+    console.error("Command Code reads providers on startup.");
+  }
+  return code;
+}

package/src/cli/message-args.ts

@@ -0,0 +1,34 @@
+import type { MessageKind } from "../messaging/envelope";
+import { isThreadId } from "../messaging/types";
+
+export type MessageArgs = { action: "sessions"; json: boolean }
+  | { action: "send"; json: boolean; kind: MessageKind; thread?: string; name?: string; inReplyTo?: string };
+
+/** Pure pre-parse: unknown/duplicate options and unsupported remote surfaces fail closed. */
+export function parseMessageArgs(argv: readonly string[]): MessageArgs | null {
+  const action = argv[0];
+  if (action !== "sessions" && action !== "send") return null;
+  const seen = new Set<string>();
+  const values: Record<string, string> = {};
+  for (let index = 1; index < argv.length; index++) {
+    const flag = argv[index]!;
+    if (seen.has(flag)) return null;
+    seen.add(flag);
+    if (flag === "--json" || (action === "send" && flag === "--stdin")) continue;
+    if (action !== "send" || !["--thread", "--name", "--kind", "--in-reply-to"].includes(flag)) return null;
+    const value = argv[++index];
+    if (!value || value.startsWith("--")) return null;
+    values[flag] = value;
+  }
+  const json = seen.has("--json");
+  if (action === "sessions") return { action, json };
+  const thread = values["--thread"], name = values["--name"], inReplyTo = values["--in-reply-to"];
+  const kind = values["--kind"] ?? "request";
+  if (!seen.has("--stdin") || (thread !== undefined) === (name !== undefined)
+    || (thread !== undefined && !isThreadId(thread))
+    || (name !== undefined && (!name.trim() || name.length > 4096 || /[\x00-\x1f\x7f-\x9f]/.test(name)))
+    || !["request", "response", "notification"].includes(kind)
+    || (kind === "response" ? !isThreadId(inReplyTo) : inReplyTo !== undefined)) return null;
+  return { action, json, kind: kind as MessageKind, ...(thread ? { thread } : {}),
+    ...(name ? { name } : {}), ...(inReplyTo ? { inReplyTo } : {}) };
+}

package/src/cli/message-command.ts

@@ -0,0 +1,43 @@
+import { MessageBudget } from "../messaging/budget";
+import { readMessageInput } from "../messaging/input";
+import { localSessions, messageFailure, sendLocalMessage } from "../messaging/send";
+import { parseMessageArgs } from "./message-args";
+import { terminalSafeText } from "./runtime-api";
+
+/** Run one local messaging operation after pure syntax validation, then release owned resources. */
+export async function runMessageCommand(argv: readonly string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
+  const args = parseMessageArgs(argv);
+  if (!args) {
+    console.error("Usage: ocx message sessions [--json] | send (--thread <uuid> | --name <exact-name>) --stdin [--kind request|response|notification] [--in-reply-to <uuid>] [--json]");
+    return 64;
+  }
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  process.once("SIGINT", cancel); process.once("SIGTERM", cancel);
+  const budget = new MessageBudget(30_000, controller.signal);
+  try {
+    // Keep home selection on this command path and after syntax validation.
+    const { messageCodexHome } = await import("./message-runtime");
+    const home = messageCodexHome(env);
+    if (args.action === "sessions") {
+      const sessions = await localSessions(home, budget);
+      if (args.json) console.log(JSON.stringify({ schema: "ocx-message-sessions/1", sessions }));
+      else for (const session of sessions) console.log(terminalSafeText(`${session.id}\t${session.status}\t${session.name ?? "(unnamed)"}`));
+      return 0;
+    }
+    const body = await readMessageInput(Bun.stdin.stream(), budget);
+    const receipt = await sendLocalMessage({ ...args, body },
+      { home, senderId: env.CODEX_THREAD_ID }, budget);
+    if (args.json) console.log(JSON.stringify(receipt));
+    else console.log(terminalSafeText(`${receipt.status}: ${receipt.messageId}${receipt.error ? ` — ${receipt.error.message}` : " (submitted, not proof of processing)"}`));
+    return receipt.status === "queued" ? 0 : receipt.status === "unknown" ? 3 : 1;
+  } catch (error) {
+    const failure = { schema: "ocx-message-error/1", ...(args.action === "send" ? { status: "not_sent" } : {}), error: messageFailure(error) };
+    if (args.json) console.log(JSON.stringify(failure));
+    else console.error(failure.error.message);
+    return 1;
+  } finally {
+    budget.dispose();
+    process.removeListener("SIGINT", cancel); process.removeListener("SIGTERM", cancel);
+  }
+}

package/src/cli/message-runtime.ts

@@ -0,0 +1,6 @@
+import { resolveCodexHomeDir } from "../codex/home";
+
+/** Resolve the effective existing Codex home using the shared policy, without creating it. */
+export function messageCodexHome(env: NodeJS.ProcessEnv): string {
+  return resolveCodexHomeDir({ env });
+}

package/src/cli/observe.ts

@@ -129,7 +129,9 @@ async function explain(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   rejectArgs(args, USAGE);
   const encoded = encodeURIComponent(requestId);
   const result = await runtimeRequest(`/api/request-history/${encoded}/route-decision`, {}, deps);
-  printData(result, wantsJson, wantsJson ? undefined : [JSON.stringify(result, null, 2)]);
+  // One entry per line: printData escapes control characters per entry, so a single
+  // pretty-printed string would print its line breaks as literal `\x0a`.
+  printData(result, wantsJson, wantsJson ? undefined : JSON.stringify(result, null, 2).split("\n"));
 }
 
 async function rebuildIndex(argv: string[], deps: RuntimeApiDeps): Promise<void> {

package/src/cli/provider.ts

@@ -8,11 +8,12 @@
  *   show <name>   Show provider config details (secrets masked)
  *   set-default <name>  Change the default provider
  */
-import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig, validateConfigCandidate } from "../config";
+import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig, validateConfigCandidate, withConfigMutationLockSync } from "../config";
 import { apiKeyTransportConfigError, modelCapabilitiesConfigError, mergeModelCapabilities } from "../config/provider-validation";
 import { hasHelpFlag, printSubcommandUsage } from "./help";
 import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
 import { providerConfigSeed } from "../providers/derive";
+import { assertAnthropicInstanceLoginConfig } from "../oauth/store-anthropic-instance";
 import { dropProviderCustomModels } from "../providers/provider-id-rewrite";
 import type { OcxProviderConfig } from "../types";
 import { findLiveProxy } from "../server/proxy-liveness";
@@ -249,6 +250,17 @@ async function handleAdd(args: string[], deps: ProviderCommandDeps): Promise<voi
 
   if (responsesPath !== undefined) provConfig.responsesPath = responsesPath;
   if (authMode !== undefined) provConfig.authMode = authMode as OcxProviderConfig["authMode"];
+  if (name === "anthropic2") {
+    if (provConfig.adapter !== "anthropic" || provConfig.authMode !== "oauth") delete provConfig.anthropicOAuthInstance;
+    if (provConfig.anthropicOAuthInstance) {
+      try { assertAnthropicInstanceLoginConfig(config, name); }
+      catch {
+        console.error("Error: cannot add Pool 2 over an existing custom or unreadable provider configuration; resolve it first.");
+        process.exitCode = 2;
+        return;
+      }
+    }
+  }
   if (name === "openai" && (authMode !== undefined || responsesPath !== undefined)
     && !isCanonicalOpenAiForwardProvider(provConfig)) {
     console.error("Error: Canonical OpenAI must keep its built-in forward destination and authentication. Use a separate provider name for a custom endpoint.");
@@ -315,11 +327,22 @@ async function handleAdd(args: string[], deps: ProviderCommandDeps): Promise<voi
     return;
   }
   const { initializeProviderModelSelection } = await import("../providers/initial-model-selection");
-  initializeProviderModelSelection(name, provConfig, existingProvider, config);
-  config.providers[name] = provConfig;
-  if (setDefault) config.defaultProvider = name;
-
-  validateAndSave(config);
+  let markerCollision = false;
+  withConfigMutationLockSync(() => {
+    if (provConfig.anthropicOAuthInstance) {
+      try { assertAnthropicInstanceLoginConfig(config, name); }
+      catch { markerCollision = true; return; }
+    }
+    initializeProviderModelSelection(name, provConfig, existingProvider, config);
+    config.providers[name] = provConfig;
+    if (setDefault) config.defaultProvider = name;
+    validateAndSave(config);
+  });
+  if (markerCollision) {
+    console.error("Error: provider configuration changed while adding Pool 2; resolve the ownership collision first.");
+    process.exitCode = 2;
+    return;
+  }
 
   let sync: LocalSyncResult | undefined;
   if (wantsSync) {

package/src/cli/registry.ts

@@ -8,6 +8,12 @@ export interface CliCommandEntry {
 }
 
 export const CLI_COMMANDS: CliCommandEntry[] = [
+  {
+    name: "message",
+    usage: "ocx message <sessions|send> [options]",
+    summary: "Discover loaded local Codex sessions and submit one queued peer message.",
+    details: ["Local Unix transport only; starts no daemon. queued is submission, not processing; never replay an unknown send."],
+  },
   {
     name: "chatgpt",
     usage: "ocx chatgpt <launch|restore|status>",
@@ -467,8 +473,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "export",
-    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo|cline|kilo|droid> [--json] [--out <path>] [--force]",
-    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside, Raycast, omo, Cline, Kilo, Factory Droid) wired to the running proxy.",
+    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|commandcode|prime|aside|raycast|omo|cline|kilo|droid> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Command Code, Prime Agent, Aside, Raycast, omo, Cline, Kilo, Factory Droid) wired to the running proxy.",
     details: [
       "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
       "--out <path> writes the native config there and refuses to replace an existing file without --force.",
@@ -598,6 +604,22 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "Select OpenCodex Proxy/<provider>/<model> from ZCode's model picker.",
     ],
   },
+  {
+    name: "commandcode",
+    usage: "ocx commandcode [status|show|list|enable|disable|history|journal|restore --op <opId>] [--json]",
+    summary: "Connect Command Code CLI to the proxy via its managed provider.",
+    details: [
+      "Alias of ocx integration client <sub> --client commandcode.",
+      "enable manages the opencodex block under the existing provider or providers root in ~/.commandcode/providers.json; disable removes only that block.",
+      "Command Code reads providers on startup.",
+      "`restore --op <opId>` replays the exact previous managed block; take the id from `ocx commandcode history`.",
+    ],
+  },
+  {
+    name: "cmd",
+    usage: "ocx cmd [status|show|list|enable|disable|history|journal|restore --op <opId>] [--json]",
+    summary: "Alias of ocx commandcode.",
+  },
   {
     name: "restart",
     usage: "ocx restart",

package/src/clients/config-export/commandcode.ts

@@ -0,0 +1,131 @@
+// Command Code config export.
+import type { ExportContext, ManagedContribution } from "./contracts";
+import { normalizeExportModels, authoritativeContextWindow, singleFragment } from "./model-metadata";
+import { OPENCODE_PROVIDER_ID, LOOPBACK_API_KEY_PLACEHOLDER } from "./constants";
+import { sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
+
+export interface CommandCodeModelEntry {
+  reasoningEfforts?: string[];
+  contextWindow?: number;
+}
+
+export interface CommandCodeProviderBlock {
+  name: "OpenCodex";
+  api: "openai-completions";
+  baseURL: string;
+  apiKey: string | boolean;
+  models: Record<string, CommandCodeModelEntry>;
+}
+
+export interface CommandCodeGeneratedConfig {
+  provider: Record<string, CommandCodeProviderBlock>;
+  /** The root a pre-existing target already uses; see {@link commandCodeProviderRoot}. */
+  providers?: Record<string, CommandCodeProviderBlock>;
+}
+
+/**
+ * LOSSY spelling-collision key for a routed selector — not model identity.
+ *
+ * One provider model reaches this exporter under interchangeable spellings: the raw
+ * selector keeps inner slashes (`command-code/deepseek/deepseek-v4.1-flash`, what
+ * `/v1/models` publishes) while the Codex-facing form encodes them as dashes
+ * (`command-code/deepseek-deepseek-v4.1-flash`, what `~/.codex/config.toml` stores and
+ * what an operator typing `--model` copies). Command Code addresses models by exact key,
+ * so a catalog that carries both spellings can resolve the active model against one and
+ * miss it in the other.
+ *
+ * The slash is meaningful: it separates the provider from the model id, and a provider id
+ * never contains one. But the encoding is NOT bijective — `p/a/b` and `p/a-b` are
+ * different model ids that encode to the same string. That is the same lossy relation
+ * `slugEquivalenceKey` documents in src/providers/slug-codec.ts and the same ambiguity
+ * `resolveSlugAliasCollisions` guards in the catalog. Callers must therefore never drop
+ * a row on this key alone; buildCommandCodeClientConfig additionally compares provider
+ * and id before folding two rows into one.
+ */
+function canonicalSpellingOf(namespaced: string): string {
+  const slash = namespaced.indexOf("/");
+  if (slash <= 0) return namespaced;
+  return namespaced.slice(0, slash) + "/" + namespaced.slice(slash + 1).replaceAll("/", "-");
+}
+
+export function buildCommandCodeClientConfig(ctx: ExportContext): CommandCodeGeneratedConfig {
+  const models: Record<string, CommandCodeModelEntry> = {};
+  // Fold interchangeable spellings of one model onto a single key. The first
+  // occurrence wins per provider+id identity; distinct model ids that happen to
+  // share a lossy spelling collision must both remain addressable.
+  const emittedIdentitiesByCollision = new Map<string, Set<string>>();
+  for (const model of normalizeExportModels(ctx.models)) {
+    const emittedKey = model.namespaced;
+    const collisionKey = canonicalSpellingOf(model.namespaced);
+    const identity = `${model.provider}\u0000${model.id}`;
+    const identities = emittedIdentitiesByCollision.get(collisionKey) ?? new Set<string>();
+    if (identities.has(identity)) continue;
+    identities.add(identity);
+    emittedIdentitiesByCollision.set(collisionKey, identities);
+    const entry: CommandCodeModelEntry = {};
+    const context = authoritativeContextWindow(model.contextWindow);
+    if (context !== undefined) {
+      entry.contextWindow = context;
+    }
+    const efforts = sanitizeCodexReasoningEfforts(model.reasoningEfforts)
+      ?.filter(effort => ["low", "medium", "high", "xhigh", "max"].includes(effort));
+    if (efforts && efforts.length > 0) {
+      entry.reasoningEfforts = efforts;
+    }
+    models[emittedKey] = entry;
+  }
+  return {
+    provider: {
+      [OPENCODE_PROVIDER_ID]: {
+        name: "OpenCodex",
+        api: "openai-completions",
+        baseURL: ctx.baseUrl.replace(/\/v1\/?$/, "") + "/v1",
+        apiKey: false,
+        models,
+      },
+    },
+  };
+}
+
+/**
+ * The root key Command Code actually reads: `provider`, else `providers`.
+ *
+ * Verified against the published client (`command-code@1.66.0`, `dist/cli.mjs`):
+ * `const o = e.provider ?? e.providers;` — singular wins, and the plural branch is
+ * only reached when the singular root is nullish (`null` or `undefined`). Adding a
+ * singular root to a document that already carries a plural one therefore does not
+ * merge the two: the old entries stay on disk, byte for byte, and become invisible
+ * to the consumer.
+ *
+ * Evaluates nullish precedence before container validation so that non-nullish
+ * invalid singular values (such as strings or arrays) remain selected and are refused
+ * by the container guard rather than falling through to write an unreachable plural block.
+ */
+export function commandCodeProviderRoot(document: unknown): "provider" | "providers" {
+  const doc = document as { provider?: unknown; providers?: unknown } | null | undefined;
+  if (doc?.provider !== undefined && doc?.provider !== null) return "provider";
+  if (doc?.providers !== undefined && doc?.providers !== null) return "providers";
+  // Nothing established yet: the singular root is the one this exporter writes.
+  return "provider";
+}
+
+export function summarizeCommandCode(document: unknown): { modelCount: number; modelsWithoutLimits: number } {
+  const doc = document as CommandCodeGeneratedConfig | undefined;
+  const root = commandCodeProviderRoot(document);
+  const models = Object.values(doc?.[root]?.[OPENCODE_PROVIDER_ID]?.models ?? {}) as CommandCodeModelEntry[];
+  return { modelCount: models.length, modelsWithoutLimits: models.filter(model => model.contextWindow === undefined).length };
+}
+
+/**
+ * The provider block, written under whichever root the target document already uses.
+ *
+ * `ExportContext` carries the parsed target document so the root can be chosen from
+ * what is on disk rather than assumed. A fresh file gets the singular root this
+ * exporter has always written; a document that already carries a plural root keeps
+ * it, so enabling OpenCodex never makes the user's other providers unreadable.
+ */
+export function buildCommandCodeContribution(ctx: ExportContext): ManagedContribution {
+  const doc = buildCommandCodeClientConfig(ctx);
+  const root = commandCodeProviderRoot(ctx.document);
+  return singleFragment("commandcode", [root, OPENCODE_PROVIDER_ID], doc.provider[OPENCODE_PROVIDER_ID]);
+}

package/src/clients/config-export/contracts.ts

@@ -185,6 +185,17 @@ export interface ExportContext {
    */
   config?: OcxConfig;
   droidReasoningDefaults?: DroidReasoningDefaults;
+  /**
+   * The parsed target document, when the caller has one in hand.
+   *
+   * A client whose reader picks between two roots needs the bytes on disk to
+   * choose: Command Code resolves `document.provider ?? document.providers`, so
+   * writing the singular root into a document that already carries the plural one
+   * leaves the user's providers unreadable rather than merging with them. Absent
+   * for `ocx export`, which has no target file — the builder then writes its
+   * default root, exactly as before.
+   */
+  document?: unknown;
 }
 
 /** Namespaced model selector to one of that model's declared reasoning efforts. */
@@ -206,6 +217,7 @@ export type ExportClientId =
   | "raycast"
   | "omo"
   | "cline"
+  | "commandcode"
   | "kilo"
   | "droid";
 

package/src/clients/config-export.ts

@@ -21,7 +21,7 @@
  */
 import { homedir } from "node:os";
 import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, win32 } from "node:path";
 import { shouldInjectApiAuthHeader, standaloneCodexRoutingTarget } from "../codex/inject";
 import { FORMAT_MEDIA_TYPE, serializeDocument, type ConfigFormat } from "../integrations/serialize";
 import { canonicalizeReasoningEfforts } from "../reasoning-effort";
@@ -69,6 +69,18 @@ import { buildKiloClientConfig, summarizeKilo, buildKiloContribution, kiloConfig
 export { kiloConfigPath, kiloHomeDir, kiloCandidatePath, KILO_CONFIG_CANDIDATES } from "./config-export/kilo";
 export type { KiloGeneratedConfig, KiloProviderBlock, KiloModelEntry } from "./config-export/kilo";
 import { droidConfigPath, buildDroidClientConfig, summarizeDroid, buildDroidContribution } from "./config-export/droid";
+import {
+  buildCommandCodeClientConfig,
+  summarizeCommandCode,
+  buildCommandCodeContribution,
+  commandCodeProviderRoot,
+  type CommandCodeGeneratedConfig,
+  type CommandCodeModelEntry,
+  type CommandCodeProviderBlock,
+} from "./config-export/commandcode";
+
+export type { CommandCodeGeneratedConfig, CommandCodeModelEntry, CommandCodeProviderBlock };
+export { buildCommandCodeClientConfig, summarizeCommandCode, buildCommandCodeContribution, commandCodeProviderRoot };
 
 
 
@@ -474,6 +486,43 @@ export function zcodeConfigPath(env: OpencodeLaunchEnv = process.env, home: stri
   return join(zcodeHomeDir(env, home), "v2", "config.json");
 }
 
+/**
+ * The home directory Command Code itself resolves: `env.HOME ?? env.USERPROFILE`
+ * (`homeDir15` in the published `command-code@1.66.0` bundle).
+ *
+ * On POSIX `os.homedir()` already reads `$HOME`, so the two agree and `home` is
+ * returned as is. On Windows `os.homedir()` reads `%USERPROFILE%` and ignores
+ * `HOME`, which Git for Windows, MSYS2 and Cygwin set, so a user whose `HOME` differs
+ * would get a provider block in a store Command Code never opens. Only the OS-default
+ * home is replaced: a caller that injects a different root (a test, the writer's
+ * `input.home`) keeps it, and a blank or relative value falls back to `home`.
+ */
+export function commandCodeUserHome(env: OpencodeLaunchEnv = process.env, home: string = homedir(), platform: NodeJS.Platform = process.platform): string {
+  if (platform !== "win32" || home !== homedir()) return home;
+  const value = env.HOME ?? env.USERPROFILE;
+  return typeof value === "string" && value.trim() && win32.isAbsolute(value) ? value : home;
+}
+
+/**
+ * Command Code's provider store directory — `.commandcode` under the home the client
+ * resolves (see {@link commandCodeUserHome}), with no override.
+ *
+ * There is deliberately no `COMMANDCODE_HOME` here, unlike the other clients in this
+ * file: `grep -c COMMANDCODE_HOME` over the shipped `dist/cli.mjs` and
+ * `dist/index.mjs` returns 0. An override we honour but the client ignores is worse
+ * than none: `enable` would report success and write a provider block at a path no
+ * Command Code process ever opens, and the user would see an empty model list with no
+ * error anywhere. An apply against a relocated home is instead refused by `detectDir`
+ * not existing.
+ */
+export function commandCodeHomeDir(env: OpencodeLaunchEnv = process.env, home: string = homedir(), platform: NodeJS.Platform = process.platform): string {
+  return join(commandCodeUserHome(env, home, platform), ".commandcode");
+}
+
+export function commandCodeConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir(), platform: NodeJS.Platform = process.platform): string {
+  return join(commandCodeHomeDir(env, home, platform), "providers.json");
+}
+
 /**
  * The provider store a current ZCode reads, which is NOT the file above.
  *
@@ -1487,6 +1536,20 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     // remote binds refuse — same reasoning as MCode.
     loopbackOnly: true,
   },
+  commandcode: {
+    id: "commandcode",
+    filename: "providers.json",
+    destination: env => commandCodeConfigPath(env),
+    // No env var exists behind this integration: buildCommandCodeClientConfig
+    // writes `apiKey: false`, the documented keyless form for a loopback endpoint.
+    apiKeyEnv: "",
+    exportHint: "The provider is written with `apiKey: false` — Command Code treats a keyless loopback endpoint as already authenticated. No key is stored or referenced.",
+    build: buildCommandCodeClientConfig,
+    format: "json",
+    summarize: summarizeCommandCode,
+    buildContribution: buildCommandCodeContribution,
+    loopbackOnly: true,
+  },
   prime: {
     id: "prime",
     filename: "prime-models.json",

package/src/codex/auth-api/account-list.ts

@@ -252,6 +252,13 @@ export function reconcileFreshPoolAccountPlans(runtimeConfig: OcxConfig, updates
   }
 }
 
+export interface CodexAuthAccountsListOptions {
+  /** Finish deferred registration; only a dashboard session carries that inference consent. */
+  validatePending?: boolean;
+  /** An operator's explicit refresh command, which may retry a grant already recorded as dead. */
+  explicitRefresh?: boolean;
+}
+
 export interface CodexAuthAccountsSnapshot {
   accounts: CodexAuthAccountDto[];
   mainIdentityGeneration: number;
@@ -260,7 +267,7 @@ export interface CodexAuthAccountsSnapshot {
 export async function listCodexAuthAccountsSnapshot(
   config: OcxConfig,
   forceRefresh = false,
-  options: { validatePending?: boolean } = {},
+  options: CodexAuthAccountsListOptions = {},
 ): Promise<CodexAuthAccountsSnapshot> {
   const runtimeConfig = getRuntimeConfig(config);
   const poolAccounts = (runtimeConfig.codexAccounts ?? []).filter(isSelectableCodexPoolAccount);
@@ -281,7 +288,8 @@ export async function listCodexAuthAccountsSnapshot(
         // identity when the switch is on and nothing has been observed yet.
         const creditsIdentity = runtimeConfig.showCodexCredits === true ? poolQuotaHistoryIdentity(account.id) ?? null : null;
         const creditsUnobserved = creditsIdentity !== null && !hasCodexCreditsObservation(account.id, creditsIdentity);
-        quotaResult = await fetchPoolAccountQuota(account.id, forceRefresh || creditsUnobserved, account.plan, getValidCodexToken, options.validatePending === true);
+        quotaResult = await fetchPoolAccountQuota(account.id, forceRefresh || creditsUnobserved, account.plan, getValidCodexToken,
+          options.validatePending === true, undefined, undefined, options.explicitRefresh === true);
       } catch (error) {
         if (!(error instanceof PoolQuotaProbeBusyError)) throw error;
         quotaResult = {
@@ -447,7 +455,7 @@ export async function refreshCodexQuotaForActivation(config: OcxConfig, accountI
 export async function listCodexAuthAccounts(
   config: OcxConfig,
   forceRefresh = false,
-  options: { validatePending?: boolean } = {},
+  options: CodexAuthAccountsListOptions = {},
 ): Promise<CodexAuthAccountDto[]> {
   return (await listCodexAuthAccountsSnapshot(config, forceRefresh, options)).accounts;
 }