@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,185 lines • 59.4 kB
text/typescript
import type { ProxyRestartStartOutcome } from "./tray-proxy";
/**
* Registry-driven command dispatch (Phase 3 of the CLI deepening).
*
* The command switch moved out of src/cli/index.ts into a runner table keyed
* by command name. Aliases resolve through the registry's alias pairs
* (init/setup, restore/eject, uninstall/remove, models/model); the registry
* remains the single source of command metadata. index.ts passes its local
* helpers (start/stop/ensure/status/...) through CliDispatchDeps so dispatch
* never needs to import the entry module back (no cycle).
*/
import { CLI_COMMANDS } from "./registry";
import { isValidProviderName } from "../config/provider-name";
import type { CliHead } from "./root";
import type { ReadyArgs } from "./ready";
import type { LivenessIo, LiveProxy } from "../server/proxy-liveness";
import type { OcxConfig } from "../types";
import type { OwnedIntegrationRefreshOutcome } from "../integrations/owned-refresh";
import { hasHelpFlag, printSubcommandUsage, printUsage } from "./help";
import {
HUB_GATED_SKIP_MESSAGE,
localClientSkipMessage,
setIntegrationEnabled,
shouldSyncCodexOnStart,
type LocalClientSkipReason,
} from "../codex/desired-state";
import { siblingSkipMessage } from "../codex/sibling-start";
import { syncModelsToCodex } from "../codex/sync";
import { collectOrcaCodexHomeDiagnostic } from "../codex/home";
import { restoreNativeCodexAsync, type CodexNativeRestoreResult } from "../codex/inject";
import { stripGrokConfig } from "../grok/inject";
import { handleRestartScopeAfterWrite, readRestartScope, type RestartScope } from "./restart-scope";
import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
import { isJsonOption, takeFlag, terminalSafeError } from "./runtime-api";
import { printStopSummary, type StopOutcome } from "./stop-report";
import { parseStopApproval, type StopApproval } from "./stop-approval";
import type { ResolveArgs } from "./resolve";
import type { ClientConnectionState } from "../client/state";
import { OCX_NATIVE_REPLAY_RECOVERY_NOTE } from "../responses/compaction";
export interface CliDispatchDeps {
args: string[];
command: string | undefined;
head: CliHead;
loadConfig: () => OcxConfig;
findLiveProxy: (io?: LivenessIo) => Promise<LiveProxy | null>;
probeHostname: (hostname: string | undefined) => string;
waitForProxy: (timeoutMs?: number) => Promise<LiveProxy | null>;
startArgv: (port?: number) => string[];
/** Spawn a detached proxy child (stdio ignore, unref'd, provenance env). */
spawnDetached: (argv: readonly string[]) => void;
handleStart: () => Promise<void>;
handleStop: (approval?: StopApproval) => Promise<StopOutcome>;
handleEnsure: (options?: { existingIsSuccess?: boolean }) => Promise<boolean>;
handleResolve: (args: ResolveArgs) => Promise<number>;
handleTrayProxyStart: (existingIsSuccess?: boolean) => Promise<boolean>;
handleTrayProxyRestart: () => Promise<void>;
handleRestartStartWhenStopped: (recoveringLiveRestart?: boolean) => Promise<ProxyRestartStartOutcome>;
handleProxyRestart: (startWhenStopped: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>) => Promise<boolean>;
handleUninstall: () => Promise<void>;
handleStatus: () => Promise<void>;
handleRecoverHistory: () => Promise<void>;
handleReady: (args: ReadyArgs) => Promise<number>;
serviceCommand: (...args: string[]) => Promise<void>;
}
type CommandRunner = (deps: CliDispatchDeps) => Promise<number>;
/**
* The hub's management ingress is deliberately loopback-only. Prefer it for
* a browser opened on the hub itself: the proxy listener may be restricted to
* a Tailscale address, while the ingress is the local authenticated dashboard.
*/
export function selectDefaultGuiUrl(
config: Pick<OcxConfig, "port" | "hostname" | "runtimeRole" | "hub">,
live: Pick<LiveProxy, "port" | "hostname"> | null,
probeHostname: (hostname: string | undefined) => string,
): string {
const ingress = config.runtimeRole === "hub" ? config.hub?.managementIngress : undefined;
if (ingress?.enabled) return `http://127.0.0.1:${ingress.port}`;
const guiHost = probeHostname(live?.hostname ?? config.hostname);
const hostname = guiHost === "127.0.0.1" ? "localhost" : guiHost;
return `http://${hostname}:${live?.port ?? config.port ?? 10100}`;
}
const commandRunners: Record<string, CommandRunner> = {
init: async () => {
const { runInit } = await import("./init");
await runInit();
// runInit sets process.exitCode = 1 on stdin EOF/closed; preserve it.
return Number(process.exitCode ?? 0);
},
start: async deps => {
const { readClientConnectionState } = await import("../client/state");
const clientState = readClientConnectionState();
await reconcileClientJournalBeforeLifecycle(clientState);
if (clientState.kind === "invalid" || clientState.kind === "mismatched") {
console.error(`Client state is ${clientState.kind}: ${clientState.reason}`);
return 1;
}
await deps.handleStart();
return Number(process.exitCode ?? 0);
},
stop: async deps => {
const parsed = parseStopApproval(deps.args.slice(1));
if (!parsed.ok) {
console.error("Usage: ocx stop [--json [--expect-pid <pid> --expect-port <port> --expect-hostname <host> --expect-config-home <home> --expect-cli-version <version> --expect-compatibility-token <hex>]]");
return 64;
}
// Downtime warning lives HERE, not in handleStop: `restart`/tray-restart callers
// re-start the proxy immediately, so warning there would contradict the next line.
const warning = "⚠️ Codex/Claude requests through the proxy will fail until it is restarted ('ocx start' or 'ocx service start').";
if (!parsed.json) {
// handleStop returns the structured outcome now; an object is always truthy, so
// the warning must key on .ok — otherwise a failed stop would still claim downtime.
if ((await deps.handleStop()).ok) console.log(warning);
return Number(process.exitCode ?? 0);
}
// --json is a reporting layer over the SAME stop path: the receipt, the drain, the
// respawn verification and the client-config restore run unchanged. Human output
// still prints, but on stderr, so stdout carries exactly one JSON summary document.
// The exit code (0/1/79/80) crosses the process boundary untouched — the shell reads
// it from the child, and the stop-contract codes must survive the JSON mode.
const humanLog = console.log;
console.log = console.error;
let outcome: StopOutcome | undefined;
try {
outcome = await deps.handleStop(parsed.approval ?? undefined);
if (outcome.ok) console.log(warning);
} finally {
console.log = humanLog;
}
// A throw above propagates after the finally restores the console, so reaching here
// with an undefined outcome cannot happen; the guard keeps the assignment provable.
if (outcome) printStopSummary(outcome.summary);
// A guarded refusal never reaches the code that records process.exitCode, so the
// approval-bound form answers with its summary's code; plain stop keeps its contract.
return parsed.approval ? (outcome?.summary.exitCode ?? 1) : Number(process.exitCode ?? 0);
},
resolve: async deps => {
// Same fail-closed shape as `ready`: parseCliHead pre-parsed the verb before any
// preflight side effect, so a missing resolveArgs means dispatch diverged. Refuse
// with code 64 and perform NO I/O.
if (!deps.head.resolveArgs) return 64;
return await deps.handleResolve(deps.head.resolveArgs);
},
restore: async deps => {
const restoreArgs = deps.args.slice(1);
const restoreJson = takeFlag(restoreArgs, "--json");
const removeProviderTable = takeFlag(restoreArgs, "--remove-codex-provider-table");
if (restoreArgs[0] === "back") {
// Reverse switch: re-point plain `codex` at the RUNNING proxy without touching its
// lifecycle — the counterpart of `ocx restore`. Start/stop triggers are unchanged;
// this only re-runs the same inject (config + catalog + history) `ocx start` does.
// takeFlag above makes `ocx restore --json back` restore-back, not eject.
const { skippedRestoreEnvelope } = await import("../codex/inject");
const emitBack = (success: boolean, message: string, code: number): number => {
if (restoreJson) console.log(JSON.stringify(skippedRestoreEnvelope(success, message)));
else if (code === 0) console.log(message);
else console.error(message);
return code;
};
const live = await deps.findLiveProxy();
if (!live) {
return emitBack(false, "No running proxy found. Run 'ocx start' — it injects opencodex automatically.", 1);
}
const desired = setIntegrationEnabled("codex", true);
if (!desired.ok) {
return emitBack(false, `Codex desired state was not saved (${desired.reason}).`, desired.reason === "conflict" ? 2 : 1);
}
const synced = await syncModelsToCodex(live.port);
if (synced.status === "skipped") {
// `setIntegrationEnabled` above just committed ON, so a skip here is NOT the toggle and
// is not a competing writer either — on a hub it is the role gate. Telling the operator
// to "retry after the competing integration change finishes" sent them waiting for a
// writer that does not exist (#4236).
return emitBack(
false,
synced.skippedReason === "hub-gated"
? `${HUB_GATED_SKIP_MESSAGE} restore back did not change Codex.`
: "Codex integration is OFF; restore back did not change Codex. Retry after the competing integration change finishes.",
2,
);
}
if (!synced.ok) {
return emitBack(false, "Plain `codex` was not switched back to opencodex. Fix the reported Codex config issue and retry.", 1);
}
const target = collectOrcaCodexHomeDiagnostic();
return emitBack(true, `Plain \`codex\` now routes through opencodex in ${target.effectiveCodexHome} (undo with: ocx restore).`, 0);
}
if (removeProviderTable && !restoreJson) {
console.log("⚠️ Removing [model_providers.opencodex] means conversations already tagged opencodex will stop opening.");
}
const desired = setIntegrationEnabled("codex", false);
if (!desired.ok) {
if (restoreJson) {
// Machine-readable contract: every restore --json outcome emits one
// schema-complete envelope on stdout, including pre-machinery failures.
const { skippedRestoreEnvelope } = await import("../codex/inject");
console.log(JSON.stringify(skippedRestoreEnvelope(false, `Codex desired state was not saved (${desired.reason}).`)));
} else {
console.error(`Codex desired state was not saved (${desired.reason}).`);
}
return desired.reason === "conflict" ? 2 : 1;
}
// A repeated OFF on an already-clean home is a policy no-op. Do not enter
// restore's native-profile machinery merely to prove there is nothing to
// restore: those locks live in CODEX_HOME and a skip must create nothing.
if (desired.status === "unchanged") {
const { classifyNativeRoutedResidue } = await import("../codex/native-residue");
if (classifyNativeRoutedResidue().kind === "clean") {
// The Codex half being a no-op says nothing about the Grok half. Returning here
// without stripping the fence meant `ocx restore` could report success while Grok
// still pointed at a stopped proxy — and the deferred-teardown recovery path
// (#3008) tells operators to run exactly this command before deleting a receipt,
// so the incomplete teardown would be signed off and the obligation erased.
let grokNote = "";
let grokCode = 0;
try {
const g = stripGrokConfig();
if (g.changed) grokNote = ` ${g.message}`;
else if (!g.ok) { grokNote = ` Grok config cleanup failed: ${g.message}`; grokCode = 1; }
} catch (err) {
grokNote = ` Grok config cleanup failed: ${err instanceof Error ? err.message : String(err)}`;
grokCode = 1;
}
const alreadyOff = `Codex integration is already OFF and native; no Codex files changed.${grokNote}`;
if (restoreJson) {
const { skippedRestoreEnvelope } = await import("../codex/inject");
console.log(JSON.stringify(skippedRestoreEnvelope(grokCode === 0, alreadyOff)));
} else if (grokCode === 0) {
console.log(alreadyOff);
} else {
console.error(alreadyOff);
}
return grokCode;
}
}
let r: CodexNativeRestoreResult | Pick<CodexNativeRestoreResult, "success" | "message">;
try {
r = await restoreNativeCodexAsync({ revalidateDesiredState: true, removeProviderTable });
} catch (err) {
r = { success: false, message: err instanceof Error ? err.message : String(err) };
}
// Grok BEFORE either output. The JSON path used to return here, so `ocx restore --json`
// (and `ocx eject --json`, the same runner) could report success while the fence still
// pointed at the stopped proxy — and the deferred-teardown recovery on this branch
// tells operators to run exactly this before deleting a receipt (#3008).
let grokFailure: string | null = null;
let grokChangedMessage: string | null = null;
try {
const g = stripGrokConfig();
if (g.changed) grokChangedMessage = g.message;
else if (!g.ok) grokFailure = g.message;
} catch (err) {
grokFailure = err instanceof Error ? err.message : String(err);
}
if (restoreJson) {
// Spawned callers need the artifact-level result to distinguish a busy
// history worker from a successful native restore. Keep stdout machine
// readable — the Codex artifact schema is unchanged; the Grok outcome is
// folded into success/message so a caller cannot read a half teardown as done.
const message = grokFailure
? `${r.message} Grok config cleanup failed: ${grokFailure}`
: grokChangedMessage ? `${r.message} ${grokChangedMessage}` : r.message;
console.log(JSON.stringify({ ...r, success: r.success && !grokFailure, message }));
return r.success && !grokFailure ? 0 : 1;
}
if (r.success) console.log(`✅ ${r.message}`);
else {
console.error(`⚠️ ${r.message}`);
}
let code = r.success ? 0 : 1;
if (grokChangedMessage) console.log(`✅ ${grokChangedMessage}`);
if (grokFailure) {
console.error(`⚠️ ${grokFailure}`);
code = 1;
}
if (r.success) {
const retained = "retainedCodexProviderTable" in r ? r.retainedCodexProviderTable : undefined;
if (retained) {
console.log("Codex integration is OFF and plain `codex` now runs natively.");
console.log("The following lines remain in $CODEX_HOME/config.toml because conversations already tagged opencodex resolve their provider only through this table:");
console.log(retained.lines.join("\n"));
console.log(`Follow-up: ${retained.followUp}`);
console.log("Switch back with: ocx restore back");
} else {
console.log("Codex integration is OFF and plain `codex` now runs natively. Switch back with: ocx restore back");
}
console.log(`Note: ${OCX_NATIVE_REPLAY_RECOVERY_NOTE}`);
} else {
console.error("Plain `codex` was not fully restored. Inspect $CODEX_HOME/config.toml before using native Codex.");
}
return code;
},
"recover-history": async deps => {
await deps.handleRecoverHistory();
return Number(process.exitCode ?? 0);
},
uninstall: async deps => {
await deps.handleUninstall();
return Number(process.exitCode ?? 0);
},
status: async deps => {
await deps.handleStatus();
return Number(process.exitCode ?? 0);
},
doctor: async deps => {
const doctorArgs = deps.args.slice(1);
// `--json` was silently ignored here: runDoctor scans for its own flags and prints human
// output regardless, so a caller that asked for JSON got prose and exit 0 -- and the skill
// recipes recommended exactly that invocation. Refusing it is worse than supporting it and
// better than lying about it.
//
// Not implemented rather than deferred silently: runDoctor has no report collection at all
// (a module-level failure bit plus ~90 direct console emissions), and this runner appends
// the Codex Log Guard's human output after it returns, so emitting a JSON document here
// would interleave prose with JSON on one stdout -- unparseable, which is worse than the
// ignored flag. The structured-report refactor is tracked as its own work-phase.
if (doctorArgs.some(isJsonOption)) {
console.error("ocx doctor does not support --json yet. Run `ocx doctor` for the human report, or use `ocx status --json` and `ocx ready --json` for machine-readable health.");
return 2;
}
const { RECOVER_ZERO_BYTE_COORDINATOR_FLAG, runDoctor, doctorFailed } = await import("./doctor");
await runDoctor(doctorArgs);
if (!doctorArgs.includes("--fix-codex-runtime") && !doctorArgs.includes(RECOVER_ZERO_BYTE_COORDINATOR_FLAG)) {
console.log("");
const { printCodexLogGuardDoctor } = await import("./codex-log-guard-doctor");
printCodexLogGuardDoctor();
}
// A diagnostic that always exits 0 cannot gate a script. `runDoctor` reports by direct
// console.log with no checks collection, and signals its own special-flag failures
// through process.exitCode, so honour both: an explicit exitCode wins, otherwise a
// FAIL-level check fails the command. This is a BREAKING change for pipelines that ran
// `ocx doctor` and ignored the result; a diagnostic that cannot fail is worse.
const explicit = Number(process.exitCode ?? 0);
if (explicit !== 0) return explicit;
return doctorFailed() ? 1 : 0;
},
debug: async deps => {
const { handleDebugCommand } = await import("./debug");
await handleDebugCommand(deps.args.slice(1));
return 0;
},
ensure: async deps => {
const { readClientConnectionState } = await import("../client/state");
const clientState = readClientConnectionState();
await reconcileClientJournalBeforeLifecycle(clientState);
if (clientState.kind !== "disconnected") {
console.error(clientState.kind === "connected"
? "Client mode does not start a local provider proxy; use 'ocx sync'."
: `Client state is ${clientState.kind}: ${clientState.reason}`);
return 1;
}
await deps.handleEnsure();
return Number(process.exitCode ?? 0);
},
login: async deps => {
const loginArgs = deps.args.slice(1);
// 'ocx login codex' is the command people type first, and until now it answered with
// the full provider wall because the Codex pool lives behind 'ocx account login'.
// Route the three Codex spellings to that flow instead of making the user discover
// a second noun. Everything else stays on the local OAuth/API-key path.
const { isCodexAccountLoginName, handleAccountAuthCommand } = await import("./account-auth");
if (isCodexAccountLoginName(loginArgs[0] ?? "")) {
// null means "unknown subcommand", which "login" never is; the coalesce exists because
// the shared signature serves callers that do pass an unknown one.
const code = await handleAccountAuthCommand("login", loginArgs, { findLiveProxy: deps.findLiveProxy });
return code ?? 1;
}
const { handleLogin } = await import("../oauth/login-cli");
await handleLogin(loginArgs[0]);
return 0;
},
logout: async deps => {
// Argv is parsed BEFORE any store access, which is the whole point of this shape.
// Previously `args[1]` was taken as the provider name with no parsing, so
// `ocx logout --json` called removeCredential("--json"), printed "Logged out of
// --json." and exited 0 -- a silent false success, the worst outcome for a caller
// that can only see the exit code.
//
// That is not merely a wasted call. `normalizeAuthStore` copies every top-level key
// it finds, so a hand-edited, legacy, or corrupted auth.json containing a `--json`
// key would have its active account deleted -- and the key dropped entirely if that
// was its last account. A flag must never reach the store as a provider name.
const logoutArgs = deps.args.slice(1);
const wantsJson = logoutArgs.includes("--json");
// Any leading dash is an option, not a provider. Matching only `--` left the same defect
// one dash shorter: `ocx logout -j` treated `-j` as the provider name and, with a `-j` key
// present in the store, deleted it and exited 0.
const isOption = (arg: string): boolean => arg.startsWith("-");
const positionals = logoutArgs.filter(arg => !isOption(arg));
const unknownFlags = logoutArgs.filter(arg => isOption(arg) && arg !== "--json");
const name = (positionals[0] ?? "").trim().toLowerCase();
// Usage failures exit 2 and touch nothing. A missing provider is a usage error; a
// provider that simply has no credential is a not-found (4) further down, because the
// vocabulary distinguishes "you called this wrong" from "the thing is not there".
//
// The shape check is `isValidProviderName`, not another dash test. Rejecting a leading
// ASCII `-` fixed `-j` and still let `logout —json` through with a Unicode dash, which is
// the same defect a third time: each patch named one spelling instead of the class. The
// canonical validator states the rule positively -- start and end alphanumeric, internal
// `._-` allowed -- so `github-copilot` and `google-antigravity` pass while every dash
// variant, empty string, and reserved name fails. Anything that is not a possible
// provider id cannot reach the store at all.
const malformedName = Boolean(name) && !isValidProviderName(name);
if (unknownFlags.length > 0 || positionals.length > 1 || !name || malformedName) {
const problem = unknownFlags.length > 0
? `unknown option ${unknownFlags[0]}`
: positionals.length > 1 ? "too many arguments"
: malformedName ? `not a valid provider name: ${name}`
: "missing provider";
console.error(`Usage: ocx logout <provider> [--json] (${problem})`);
return 2;
}
// The disposition comes from inside the store mutation, not from a read-then-remove
// preflight. `mutateStore` serializes writes, so a preflight leaves a window where a
// concurrent logout removes the same account and BOTH callers exit 0 claiming a removal --
// a false success again, just a narrower one than the flag bug above.
const { removeCredential } = await import("../oauth/store");
const outcome = await removeCredential(name);
if (outcome === "not-found") {
if (wantsJson) console.log(JSON.stringify({ schemaVersion: 1, ok: false, provider: name, removed: false, reason: "not_found" }, null, 2));
else console.error(`No stored credential for '${name}'.`);
return 4;
}
if (wantsJson) console.log(JSON.stringify({ schemaVersion: 1, ok: true, provider: name, removed: true }, null, 2));
else console.log(`Logged out of ${name}.`);
return 0;
},
sync: async deps => {
const syncArgs = deps.args.slice(1);
const restartScope = readRestartScope(syncArgs, console);
// The wire field keeps APP-SERVER-ONLY meaning and is deliberately not widened. A
// remote hub must not end a local user's conversations because a field name acquired
// a wider meaning underneath it; the maintainer decision widened a local CLI flag and
// said nothing about remote callers. syncConnectedClient ignores it either way.
const restartCodex = restartScope.appServers;
const { readClientConnectionState } = await import("../client/state");
const clientState = readClientConnectionState();
if (clientState.kind === "invalid" || clientState.kind === "mismatched") {
console.error(`Client state is ${clientState.kind}: ${clientState.reason}`);
return 1;
}
if (clientState.kind === "connected") {
try {
const { syncConnectedClient } = await import("../client/connect");
const result = await syncConnectedClient({ restartCodex });
console.log(result.stale
? "Hub unavailable; retained and applied the last-known-good remote catalog (stale)."
: "Remote hub catalog synchronized.");
await handleConnectedSyncCatalogWrite(result, restartScope);
// `process.exitCode` rather than a literal 0, for the same reason every other
// runner does it (tests/cli/cli-transport-honesty.test.ts): the catalog-write helper
// drives app-server restarts, and one of those recording a failure must not be
// erased by the value this runner returns. It reads 0 on the ordinary path. Node
// types it as `number | string`; only a numeric code means anything here.
return typeof process.exitCode === "number" ? process.exitCode : 0;
} catch (error) {
// The refresh path reaches the same hub catalog `ocx connect` validates, so a rejected
// reasoning level arrives here as hub-supplied text. Rendering it through the shared
// terminal boundary is what keeps the routine refresh from forging output; the domain
// error itself is left alone for callers that inspect it.
console.error(`Connected sync failed without local fallback: ${terminalSafeError(error).message}`);
return 1;
}
}
const live = await deps.findLiveProxy();
const synced = await syncModelsToCodex(
live?.port,
undefined,
undefined,
undefined,
{ catalogEvenWhenNotInjected: true },
);
let code = 0;
if (synced.status === "skipped") {
console.log(synced.skippedReason === "hub-gated"
? `${HUB_GATED_SKIP_MESSAGE} sync skipped and no Codex files changed.`
: "Codex integration is OFF; sync skipped and no Codex files changed.");
} else if (synced.status === "catalog-only") {
// 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.");
}
// Only warn/restart when a catalog or models_cache write actually happened. This is
// deliberately not an `else`: refreshCodexModelCatalog runs before injectCodexConfig,
// so a sync can fail (`ok: false`) after the catalog was already rewritten — which is
// exactly when a long-lived app-server is holding the stale list.
if (synced.catalogWritten || synced.cacheSynced) {
await handleRestartScopeAfterWrite(restartScope, console);
}
// `ocx sync` is a direct CLI path; it does not call the management
// `/api/sync` route. Refresh already-connected file integrations here too,
// after Codex has published the catalog that supplies its capabilities.
if (synced.status !== "refused") {
const results: OwnedIntegrationRefreshOutcome[] = [];
if (live) {
try {
const config = deps.loadConfig();
const { refreshOwnedCatalogIntegrations } = await import("../integrations/catalog-refresh");
results.push(...await refreshOwnedCatalogIntegrations({
models: async () => {
const { loadExportModels } = await import("../server/management/model-rows");
return loadExportModels(config);
},
config,
port: live.port,
}, ["mcode", "pi", "raycast", "omo", "cline", "droid"]));
} catch (error) {
console.warn(`Client integrations were not refreshed: ${error instanceof Error ? error.message : String(error)}`);
}
}
// Even without a live proxy, report why Aside could not sync. Its server
// owner is never bypassed, and another client's failure cannot hide it.
try {
const { refreshAsideProfilesThroughServer } = await import("./aside-profiles");
results.push(...await refreshAsideProfilesThroughServer({ findLiveProxy: async () => live }));
} catch (error) {
console.warn(`Aside profiles were not refreshed: ${error instanceof Error ? error.message : String(error)}`);
}
for (const result of results) {
const label = result.profileId === undefined ? result.client : `${result.client}:${result.profileId}`;
if (result.changed) console.log(`${label} integration refreshed from the current catalog.`);
else if (result.reason) console.warn(`${label} integration was not refreshed: ${result.reason}${result.residual ? " Recovery did not finish." : ""}${result.snapshotPath ? ` Backup: ${result.snapshotPath}` : ""}`);
}
}
return code;
},
v2: async deps => {
const { cmdV2 } = await import("./v2");
return await cmdV2(deps.args.slice(1), {}, async () => (await deps.findLiveProxy())?.port);
},
connect: async deps => {
const { handleConnectCommand } = await import("./connect");
return await handleConnectCommand(deps.args.slice(1));
},
link: async deps => {
const { runLinkCommand } = await import("./link");
return await runLinkCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
},
"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 restartScope = readRestartScope(cacheArgs, console);
const { withCatalogWriteSerialization } = await import("../codex/catalog-write-serialization");
const { invalidateCodexModelsCacheWithPermitOutcome } = await import("../codex/catalog/sync");
const { getCodexHome } = await import("../codex/paths");
const owningCodexHome = getCodexHome();
const cacheGateSnapshot = deps.loadConfig();
const desiredDisabled = !shouldSyncCodexOnStart(cacheGateSnapshot);
const invalidated = withCatalogWriteSerialization(owningCodexHome, permit =>
invalidateCodexModelsCacheWithPermitOutcome(permit, owningCodexHome, { allowWhenDesiredDisabled: true }));
const cacheJson = cacheArgs.includes("--json");
const jsonSafeLog = cacheJson
? { log: (...values: unknown[]) => console.error(...values), error: (...values: unknown[]) => console.error(...values) }
: console;
// Only warn/restart when models_cache was actually rewritten from a readable catalog.
if (invalidated.kind === "completed" && invalidated.value === "written") {
await handleRestartScopeAfterWrite(restartScope, jsonSafeLog);
} else if (!cacheJson && invalidated.kind === "completed" && invalidated.value === "desired_disabled") {
// Only when the OFF gate itself stopped the write does OFF explain the outcome. An
// explicit sync-cache refreshes regardless of the toggle, so an unchanged cache, a
// missing catalog, or a contended writer is reported below on its own terms.
// Under --json this belongs on the envelope, not as a second stdout line.
console.log(localClientSkipMessage(
cacheGateSnapshot,
"Codex integration is OFF; no catalog or cache write resulted.",
"No catalog or cache write resulted.",
));
}
// An identical cache is a successful no-op, not a failed refresh. Only a real write
// should restart Codex; a missing catalog or contended writer is also a benign skip.
//
// Losing the catalog write lock to another process is a skip, not a failure:
// serialization working as designed is the expected outcome under concurrency, and a
// proxy startup holding the permit would otherwise make a perfectly healthy
// `ocx sync-cache` exit 1 and fail the pipeline that called it -- intermittently, so it
// would read as a flake rather than a bug. `codex-retained-root-serialization.test.ts`
// pins exactly that: contended lock, no cache write, exit 0.
//
// `desiredDisabled` is deliberately NOT part of the success test, which is the subtle
// part. This call passes `allowWhenDesiredDisabled: true`, so the OFF gate inside the
// refresh never fires and the work is genuinely attempted -- an explicit `ocx sync-cache`
// means the user asked for it regardless of the toggle. Treating OFF as automatic success
// would report exit 0 and `skipped: true` for a refresh that actually failed.
//
// The detailed outcome distinguishes an unchanged cache from a failed rewrite while
// the boolean wrapper remains available to callers that only care whether bytes changed.
const wrote = invalidated.kind === "completed" && invalidated.value === "written";
const unchanged = invalidated.kind === "completed" && invalidated.value === "unchanged";
const contended = invalidated.kind === "unavailable" && invalidated.reason === "busy";
const noCatalog = invalidated.kind === "completed" && invalidated.value === "missing_catalog";
const ok = wrote || unchanged || contended || noCatalog;
if (cacheJson) {
console.log(JSON.stringify({
schemaVersion: 1,
ok,
wrote,
skipped: unchanged || contended || noCatalog,
outcome: invalidated.kind,
// `outcome` alone cannot separate a contended lock from a hard serialization
// failure -- both are `unavailable`. Carry the reason so a caller can.
reason: invalidated.kind === "unavailable" ? invalidated.reason : undefined,
// Which of the three benign skips this was, so `skipped: true` is never opaque.
skippedReason: unchanged ? "unchanged" : contended ? "contended" : noCatalog ? "no_catalog" : undefined,
desiredDisabled,
codexHome: owningCodexHome,
}, null, 2));
} else if (contended) {
console.log("Another process owns the catalog write; cache sync skipped.");
} else if (noCatalog) {
console.log("No Codex catalog to derive a cache from; nothing to sync.");
} else if (unchanged) {
console.log("Codex model cache is already current; nothing to sync.");
} else if (!ok) {
console.error(`Cache refresh did not complete (${invalidated.kind}). The Codex model cache was not rewritten.`);
}
return ok ? 0 : 1;
},
gui: async deps => {
const { runGuiCommand } = await import("./gui");
return runGuiCommand(deps.args.slice(1), {
loadConfig: deps.loadConfig,
findLiveProxy: deps.findLiveProxy,
openDefaultGui: async () => {
const config = deps.loadConfig();
// Identity-checked liveness (not the pid file + a fixed sleep): finds a fallback-port
// proxy and waits until the spawned one actually answers before opening the browser.
let live = await deps.findLiveProxy();
if (!live) {
console.log("Proxy not running. Starting...");
deps.spawnDetached(deps.startArgv((config.port ?? 10100) > 0 ? (config.port ?? 10100) : undefined));
live = await deps.waitForProxy();
if (!live) {
console.error("❌ Proxy did not become healthy after starting. Not opening the GUI.");
return 1;
}
}
const guiUrl = selectDefaultGuiUrl(config, live, deps.probeHostname);
console.log(`Opening ${guiUrl}`);
const { openUrl } = await import("../lib/open-url");
// Awaited so a launcher that never opened anything is said out loud (#5261). Still exit
// 0: the proxy is serving and the URL above is reachable, only the launch did not happen.
if ((await openUrl(guiUrl)).status === "failed") {
console.error("⚠️ No browser could be opened here; open the URL above yourself.");
}
return 0;
},
});
},
hub: async deps => {
const { runHubCommand } = await import("./hub");
return runHubCommand(deps.args.slice(1), {
loadConfig: deps.loadConfig,
findLiveProxy: deps.findLiveProxy,
});
},
service: async deps => {
process.exitCode = 0;
await deps.serviceCommand(...deps.args.slice(1));
// serviceCommand uses process.exitCode for recoverable install/stop failures
// that must finish cleanup before the single top-level process.exit runs.
return Number(process.exitCode ?? 0);
},
tray: async deps => {
const { windowsTrayCommand } = await import("../tray/windows");
// windowsTrayCommand reports failure through process.exitCode (tray/windows.ts sets
// it for bad usage and for a failed install/start/stop/uninstall) and returns void,
// so a literal 0 here made `ocx tray install` print an error and exit 0 (#2697).
process.exitCode = 0;
await windowsTrayCommand(deps.args.slice(1));
return Number(process.exitCode ?? 0);
},
"codex-shim": async deps => {
const { codexShimStatus, diagnoseCodexShim, installCodexShim, uninstallCodexShim } = await import("../codex/shim");
switch (deps.args[1]) {
case "install": {
const r = installCodexShim();
const { healthy, summary } = diagnoseCodexShim();
const { collectCodexShimReadinessWarnings } = await import("./codex-shim-readiness");
const warnings = healthy
? collectCodexShimReadinessWarnings()
: [];
console.log(`${r.installed && warnings.length === 0 ? "✅ " : "⚠️ "}${r.message}`);
for (const warning of warnings) console.warn(` ${warning}`);
if (!healthy) console.error(`Codex shim installation is unhealthy: ${summary}`);
return healthy ? 0 : 1;
}
case "status":
console.log(codexShimStatus());
break;
case "uninstall":
case "remove": {
const r = uninstallCodexShim();
console.log(r.removed ? `✅ ${r.message}` : `⚠️ ${r.message}`);
break;
}
default:
console.error("Usage: ocx codex-shim <install|status|uninstall|remove>");
return 1;
}
return 0;
},
update: async deps => {
// `ocx update --help` must print usage and exit WITHOUT side effects — running the
// real self-update stops the proxy and drops in-flight routed streams (issue #168).
if (hasHelpFlag(deps.args.slice(1))) {
printSubcommandUsage("update");
return 0;
}
const { runUpdate } = await import("../update");
await runUpdate();
return 0;
},
"__refresh-version": async deps => {
// Hidden, detached helper spawned by the update prompt to refresh the
// cached latest version without blocking the foreground start. Not in help.
const { refreshVersionCache } = await import("../update/notify");
const channel = deps.args[1] === "preview" ? "preview" : "latest";
await refreshVersionCache(channel);
return 0;
},
"__update-badge": async deps => {
if (deps.args.length !== 1) {
console.error("Usage: ocx __update-badge");
return 64;
}
const { readUpdateBadge } = await import("../update/badge");
console.log(JSON.stringify(readUpdateBadge()));
return 0;
},
"__tray-start": async deps => {
return (await deps.handleTrayProxyStart()) ? 0 : 1;
},
"__tray-restart": async deps => {
await deps.handleTrayProxyRestart();
return Number(process.exitCode ?? 0);
},
"__startup-health": async deps => {
const { collectStartupHealth } = await import("../codex/autostart-health");
console.log(JSON.stringify(collectStartupHealth(deps.loadConfig())));
return 0;
},
"__tray-host": async () => {
const { runWindowsTrayHost } = await import("../tray/windows");
await runWindowsTrayHost();
return 0;
},
"__gui-update-worker": async deps => {
const jobId = deps.args[1];
if (!jobId) return 1;
const channel = normalizeUpdateChannel(deps.args[2]);
await runGuiUpdateWorker(jobId, channel, deps.args[3] === "restart");
return 0;
},
restart: async deps => {
// The running proxy owns its drain and replacement through /api/system/restart.
// If nothing is live, restart degrades to the documented `ensure` start behavior.
await deps.handleProxyRestart(deps.handleRestartStartWhenStopped);
return Number(process.exitCode ?? 0);
},
capabilities: async deps => {
const { runCapabilities } = await import("./capabilities-command");
return await runCapabilities(deps.args.slice(1));
},
health: async deps => {
const healthArgs = deps.args.slice(1);
const wantsHealthJson = healthArgs.includes("--json");
// A proxy that has only just bound can miss a single probe while its event loop
// is still settling startup work — the same just-started race the stop paths
// already retry for (#764, SERVICE_STOP_LIVENESS). Without this, `ocx health`
// run seconds after a service restart reports a false negative on a proxy that
// is in fact serving.
const live = await deps.findLiveProxy({ attempts: 3 });
if (wantsHealthJson) {
console.log(JSON.stringify({ ok: !!live, pid: live?.pid ?? null, port: live?.port ?? null }));
} else {
console.log(live ? `Proxy healthy (PID ${live.pid}, port ${live.port})` : "Proxy not healthy");
}
return live ? 0 : 1;
},
ready: async deps => {
// Fail-closed impossible-state guard: readyArgs is populated by the
// preparse block in src/cli/root.ts before maybeAutoRestoreCodexShim, so
// reaching here without it means dispatch diverged. Refuse with code 64
// and perform NO I/O (no discovery/probe). process.exit is `never`,
// narrowing below.
const readyArgs = deps.head.readyArgs;
if (!readyArgs) return 64;
return await deps.handleReady(readyArgs);
},
provider: async deps => {
const { handleProviderCommand } = await import("./provider");
// Reset first, like the service runner below: reading process.exitCode only
// reports THIS command's outcome if nothing earlier in the process set it.
process.exitCode = 0;
await handleProviderCommand(deps.args.slice(1));
// handleProviderCommand reports failure through process.exitCode, which it sets
// from handleProviderRuntimeCommand. Returning a literal 0 here made index.ts
// call process.exit(0) and erase it, so `ocx provider quota` against a stopped
// proxy printed an error and still exited 0 (#2697).
return Number(process.exitCode ?? 0);
},
account: async deps => {
const { cmdAccount } = await import("./account");
return await cmdAccount(deps.args.slice(1));
},
models: async deps => {
const { handleModels } = await import("./models");
process.exitCode = 0;
await handleModels(deps.args.slice(1));
// Same as the provider runner above: handleModels sets process.exitCode from
// handleModelsRuntimeCommand, and a literal 0 discarded it (#2697).
return Number(process.exitCode ?? 0);
},
alias: async deps => {
const { handleAliasCommand } = await import("./alias");
return await handleAliasCommand(deps.args.slice(1));
},
combo: async deps => {
const { handleComboCommand } = await import("./combo");
return await handleComboCommand(deps.args.slice(1));
},
companion: async deps => {
const { handleCompanionCommand } = await import("./companion");
return await handleCompanionCommand(deps.args.slice(1));
},
route: async deps => {
if (deps.args[1] !== "combo" && deps.args[1] !== "policy") {
console.error("Usage: ocx route <combo|policy> <subcommand>");
return 2;
}
if (deps.args[1] === "combo") {
const { handleComboCommand } = await import("./combo");
return await handleComboCommand(deps.args.slice(2));
} else {
const { handleRoutePolicyCommand } = await import("./route-policy");
return await handleRoutePolicyCommand(deps.args.slice(2));
}
},
effort: async deps => {
const { handleEffortCommand } = await import("./effort");
return await handleEffortCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
},
agent: async deps => {
const { handleAgentCommand } = await import("./agent");
return await handleAgentCommand(deps.args.slice(1));
},
observe: async deps => {
const { handleObserveCommand } = await import("./observe");
return await handleObserveCommand(deps.args.slice(1));
},
inspect: async deps => {
const { handleInspectCommand } = await import("./inspect");
return await handleInspectCommand(deps.args.slice(1));
},
logs: async deps => {
const { handleObserveCommand } = await import("./observe");
return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
},
usage: async deps => {
const { handleObserveCommand } = await import("./observe");
return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
},
storage: async deps => {
// `ocx storage` used to be a pure alias of `observe storage`, which reached only the report
// route. wp7 gave it cleanup, trash, and policy subcommands, so it dispatches to its own
// module -- with `report` as the default subcommand, so a bare `ocx storage` still prints
// the same thing it printed before.
const { handleStorageCommand } = await import("./storage");
return await handleStorageCommand(deps.args.slice(1));
},
memory: async deps => {
const { handleObserveCommand } = await import("./observe");
return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
},
access: async deps => {
const { handleAccessCommand } = await import("./access");
return await handleAccessCommand(deps.args.slice(1));
},
"api-key": async deps => {
const { handleAccessCommand } = await import("./access");
return await handleAccessCommand(["key", ...deps.args.slice(1)]);
},
api: async deps => {
const { handleApiCommand } = await import("./api-protocols");
return await handleApiCommand(deps.args.slice(1));
},
export: async deps => {
const { handleExportCommand } = await import("./export-command");
return await handleExportCommand(deps.args.slice(1));
},
grok: async deps => {
const { handleGrokCommand } = await import("./integrations");
return await handleGrokCommand(deps.args.slice(1));
},
integration: async deps => {
const integration = deps.args[1];
if (integration === "grok") {
const { handleGrokCommand } = await import("./integrations");
return await handleGrokCommand(deps.args.slice(2));
} else if (integration === "native") {
// The native client toggles are a separate server surface from the reversible file
// integrations `client` manages, so they get their own subcommand rather than being
// folded into one that means something else.
const { handleIntegrationCommand } = await import("./inspect");
return await handleIntegrationCommand(deps.args.slice(1));
} else if (integration === "claude") {
const { handleClaudeConfigCommand } = await import("./integrations");
return await handleClaudeConfigCommand(deps.args.slice(2));
} else if (integration === "client") {
const { handleClientIntegrationCommand } = await import("./integrations");
return await handleClientIntegrationCommand(deps.args.slice(2));
} else {
console.error("Usage: ocx integration <claude|grok|client> <subcommand>");
return 2;
}
},
system: async deps => {
const { handleSystemCommand } = await import("./system-command");
return await handleSystemCommand(deps.args.slice(1));
},
config: async deps => {
const { handleConfigCommand } = await import("./config-command");
return await handleConfigCommand(deps.args.slice(1));
},
lab: async deps => {
const { handleLabCommand } = await import("./lab");
return await handleLabCommand(deps.args.slice(1));
},
claude: async deps => {
const { cmdClaude } = await import("./claude");
// "ocx claude desktop" → write Desktop 3P config
if (deps.args[1] === "desktop") {
const { handleClaudeDesktopCommand } = await import("./claude-desktop");
const exitCode = await handleClaudeDesktopCommand(deps.args.slice(2));
if (exitCode !== 0) return exitCode;
return 0;
}
if (deps.args[1] === "config") {
const { handleClaudeConfigCommand } = await import("./integrations");
return await handleClaudeConfigCommand(deps.args.slice(2));
}
return await cmdClaude(deps.args.slice(1));
},
opencode: async deps => {
const { cmdOpencode } = await import("./opencode");
return await cmdOpencode(deps.args.slice(1));
},
mcode: async deps => {
const { cmdMcode } = await import("./minimax");
return await cmdMcode(deps.args.slice(1));
},
mmx: async deps => {
const { cmdMmx } = await import("./minimax");
return await cmdMmx(deps.args.slice(1));
},
zcode: async deps => {
const { handleZcodeCommand } = await import("./integrations");
return await handleZcodeCommand(deps.args.slice(1));
},
help: async () => {
printUsage();
return 0;
},
"--help": async () => {
printUsage();
return 0;
},
"-h": async () => {
printUsage();
return 0;
},
};
/** Registry alias pairs → canonical dispatch name (init/setup, restore/eject, …). */
const aliasTargets = new Map<string, string>();
for (const entry of CLI_COMMANDS) {
for (const alias of entry.aliases ?? []) aliasTargets.set(alias, entry.name);
}
export const DISPATCH_COMMANDS: ReadonlySet<string> = new Set(Object.keys(commandRunners));
export const DISPATCH_ALIASES: ReadonlyMap<string, string> = aliasTargets;
/** Resolve the runner key for a command, following registry aliases to the
* canonical runner. Returns undefined when the command is unknown. */
/** What `handleStart` does about a live proxy it found before binding. */
export type StartOwnerDecision = "refuse" | "service-stay-out" | "sibling" | "await-parent";
/**
* Pure decision for `handleStart` when the pre-bind probe found a live proxy.
*
* The #3106 guard exists so a bare `start` cannot shadow a healthy configured-port
* proxy with an ephemeral-port copy. An interactive `--port X` naming a DIFFERENT
* port than the live proxy's is an explicit sibling request, not that shadow. The
* state-directory spend-ledger lease makes the final same-home refusal; keeping this
* decision allows isolated homes on one machine to remain independent.
* The service wrapper always passes the configured port and keeps its exact
* stay-out-of-the-way semantics: it never takes the sibling path.
*
* `"await-parent"` comes first and only for an exact pid match: the live proxy is the draining
* process that spawned this start as its restart replacement (`OCX_RESTART_PARENT_PID`, already
* checked against the real parent pid). Refusing it would leave no proxy once that parent exits,
* so the caller waits for it instead (`src/cli/restart-handoff.ts`). Every other owner, and a
* live proxy whose pid could not be verified, keeps the table above.
*/
export function decideStartWithLiveOwner(input: {
livePort: number;
requestedPort: number | undefined;
ocxService: string | undefined;
livePid?: number | null;
restartParentPid?: number | null;
}): StartOwnerDecision {
if (input.restartParentPid != null && input.livePid === input.restartParentPid) return "await-parent";
const sibling = input.requestedPort !== undefined
&& input.requestedPort !== input.livePort
// Only the exact "1" sentinel is service context — the same check the exit teardown
// uses — so an env value like "0" or "false" cannot reach the stay-out path.
&& input.ocxService !== "1";
if (sibling) return "sibling";
return input.ocxService === "1" ? "service-stay-out" : "refuse";
}
/** Which shared client state `handleStart`'s exit cleanup tears down. */
export interface StartExitTeardown {
revertSystemEnv: boolean;
restoreNativeCodex: boolean;
stripGrokConfig: boolean;
}
/**
* Pure exit-teardown decision for `handleStart`'s `syncCleanup`.
*
* A sibling instance tears down nothing: the Codex routing, the Grok fence and the system env
* belong to the live proxy it runs beside, and restoring them would take Codex off a proxy that
* is still serving it (`src/codex/sibling-start.ts`). A dashboard drain-and-restart (#563) keeps
* everything for the replacement process. Under a service manager — only the exact `"1"`
* sentinel — a crash/respawn keeps routing and the fence, and only the environment comes down.
* The caller still applies its own external-provider and service-ownership checks.
*/
export function decideStartExitTeardown(input: {
sibling: boolean;
recycling: boolean;
ocxService: string | undefined;
}): StartExitTeardown {
if (input.sibling || input.recycling) {
return { revertSystemEnv: false, restoreNativeCodex: false, stripGrokConfig: false };
}
const preserveRouting = input.ocxService === "1";
return { revertSystemEnv: true, restoreNativeCodex: !preserveRouting, stripGrokConfig: !preserveRouting };
}
/**
* The one startup line for "nothing was written to Codex".
*
* Three very different facts reach it: the user's own OFF switch, a hub declining to rewrite its
* own local clients, and a sibling instance leaving the live proxy's routing alone. Printing the
* toggle's wording for the gate is what made operators hunt for a switch they never set (#4236).
* `port` is the sibling's own bound port, named in its line.
*/
export function startupLeftCodexNativeLine(reason: LocalClientSkipReason, port?: number): string {
if (reason === "sibling") return ` ${siblingSkipMessage(port)}`;
return reason === "hub-gated"
? ` ${HUB_GATED_SKIP_MESSAGE} Startup left Codex native.`
: " Codex integration OFF; startup left Codex native.";
}
/** What `chooseListenPort` does when the preferred port stayed busy through prefer-retry. */
export type BusyPreferredPortDecision =
| "hop"
| "refuse-live-proxy"
| "service-stay-out"
| "refuse-unidentified-holder";
/**
* Pure decision for a soft `start` whose preferred port is busy and whose only remaining
* option is an ephemeral port.
*
* The hop exists so a first start is not defeated by a port this machine happens to be
* using. What it must never be is a silent answer to "someone is already here": a start
* that hops takes over this home's pid and runtime-port records and re-points Codex at
* itself, so hopping past a live opencodex leaves two proxies running and the editor
* talking to the one the user did not mean (#5004). The hop path never asked who held the
* port, and `findLiveProxy` returning null — a stale record, a probe that lost a race, a
* loopback family split — was enough to reach it.
*
* So the decision is made from the holder's own answer rather than from this home's
* bookkeeping, and both outcomes stop the start. An opencodex answer is the duplicate this
* closes. A holder that does not answer as opencodex is deliberately NOT called foreign:
* an identity probe returns the same nothing for a foreign server, an unreachable one, and
* one that lost a race, so all the start can honestly say is that the port it was told to
* use is taken by something it could not identify — and moving to an arbitrary port is the
* one response that hides that from the user while re-pointing Codex. An explicit
* `--port` never reaches here (`findAvailablePort` refuses the fallback instead), and a
* configured port of 0 is a request for an ephemeral port, not a collision.
*
* Service-wrapper context keeps the semantics `decideStartWithLiveOwner` gives it: a
* healthy proxy on the port means the port is served, and the wrapper's
* retry loop must receive the intentional stay-out signal rather than respawn every 5 seconds.
*/
export function decideBusyPreferredPort(input: {
preferredPort: number;
selectedPort: number;
hardPin: boolean;
holderIsOpencodex: boolean;
ocxService: string | undefined;
}): BusyPreferredPortDecision {
// Port 0 (or an unusable preference) asked the OS to choose; nothing was taken away.
if (input.preferredPort <= 0) return "hop";
// The preferred port was obtained — no hop happened, nothing to decide.
if (input.selectedPort === input.preferredPort) return "hop";
// Defensive: a hard pin cannot reach a different port, and if it ever did, the pin is
// the user's explicit instruction and not something to answer with a refusal here.
if (input.hardPin) return "hop";
if (input.holderIsOpencodex) {
// Same sentinel rule as decideStartWithLiveOwner: only the exact "1" is service context.
return input.ocxService === "1" ? "service-stay-out" : "refuse-live-proxy";
}
return "refuse-unidentified-holder";
}
export function resolveDispatchCommand(command: string | undefined): string | undefined {
if (command === undefined) return undefined;
if (Object.prototype.hasOwnProperty.call(commandRunners, command)) return command;
return aliasTargets.get(command);
}
export async function dispatchCommand(head: CliHead, deps: CliDispatchDeps): Promise<number> {
const command = head.command;
if (command === undefined || command === "help" || command === "--help" || command === "-h") {
printUsage();
return 0;
}
if (command === "internal") {
// Routed here rather than as a runner key so it stays out of DISPATCH_COMMANDS and
// therefore out of the registry-parity gate. See src/cli/internal-command.ts.
const { handleInternalCommand } = await import("./internal-command");
return await handleInternalCommand(deps.args.slice(1));
}
const runner = commandRunners[resolveDispatchCommand(command) ?? ""];
if (!runner) {
console.error(`Unknown command: ${command}`);
printUsage();
return 1;
}
return await runner(deps);
}
async function handleConnectedSyncCatalogWrite(
result: { catalogWritten: boolean; cacheSynced: boolean },
scope: RestartScope,
): Promise<void> {
if (!result.catalogWritten && !result.cacheSynced) return;
await handleRestartScopeAfterWrite(scope, console);
}
async function reconcileClientJournalBeforeLifecycle(
state: ClientConnectionState,
): Promise<void> {
if (state.kind === "disconnected") return;
const { reconcileJournal } = await import("../codex/journal");
reconcileJournal(state.kind === "connected"
? { activeClientApiKeyId: state.value.apiKeyId }
: undefined);
}