@minniexcode/codex-switch 0.0.11 → 0.1.0

package/dist/cli/output.js

@@ -85,12 +85,25 @@ function renderHumanSuccess(command, data, warnings) {
                 lines.push("No providers configured.");
             }
             else {
+                const currentProfile = typeof data?.currentProfile === "string" ? data.currentProfile : null;
+                const activeProviderResolvable = data?.activeProviderResolvable !== false;
+                const activeCandidates = Array.isArray(data?.activeProviderCandidates) ? data?.activeProviderCandidates : [];
+                if (currentProfile) {
+                    lines.push(`Current profile: ${currentProfile}`);
+                    if (!activeProviderResolvable && activeCandidates.length > 1) {
+                        lines.push(`Current provider: ambiguous (${activeCandidates.join(", ")})`);
+                    }
+                    else if (!activeProviderResolvable) {
+                        lines.push("Current provider: unmanaged or unresolved");
+                    }
+                }
                 for (const provider of providers) {
                     const tags = Array.isArray(provider.tags) && provider.tags.length > 0
                         ? ` tags=${provider.tags.join(",")}`
                         : "";
                     const note = provider.note ? ` note=${provider.note}` : "";
-                    lines.push(`${provider.name} -> ${provider.profile}${tags}${note}`);
+                    const current = provider.isActive ? " current" : "";
+                    lines.push(`${provider.name} [${String(provider.providerType ?? "direct")}]${current} -> ${provider.profile}${tags}${note}`);
                 }
             }
             break;
@@ -115,17 +128,15 @@ function renderHumanSuccess(command, data, warnings) {
             lines.push(`Current profile: ${String(data?.profile ?? "")}`);
             break;
         case "status":
-            lines.push(`codexDir: ${String(data?.codexDir ?? "")}`);
-            lines.push(`configExists: ${String(data?.configExists ?? false)}`);
-            lines.push(`providersExists: ${String(data?.providersExists ?? false)}`);
-            lines.push(`currentProfile: ${String(data?.currentProfile ?? "")}`);
-            lines.push(`mappedProvider: ${String(data?.provider ?? "")}`);
-            lines.push(`activeProviderResolvable: ${String(data?.activeProviderResolvable ?? false)}`);
-            const auth = data?.auth ?? {};
-            lines.push(`authExists: ${String(auth.exists ?? false)}`);
-            lines.push(`authValid: ${String(auth.valid ?? false)}`);
-            lines.push(`authMode: ${String(auth.authMode ?? "")}`);
-            lines.push(`issues: ${Array.isArray(data?.issues) ? (data?.issues).length : 0}`);
+            lines.push("Status summary:");
+            lines.push(`  target runtime: ${String(data?.codexDir ?? "")}`);
+            lines.push(`  tool home: ${String(data?.storage?.toolHome?.root ?? "")}`);
+            lines.push(`  current profile: ${String(data?.currentProfile ?? "(none)")}`);
+            lines.push(`  mapped provider: ${renderStatusMappedProvider(data)}`);
+            lines.push(`  provider path: ${renderStatusProviderPath(data)}`);
+            lines.push(`  runtime health: ${renderStatusHealth(data)}`);
+            lines.push(`  warnings: ${warnings.length}`);
+            lines.push(`  next step: ${renderStatusNextStep(data, warnings)}`);
             break;
         case "config-show": {
             lines.push(`activeProfile: ${String(data?.activeProfile ?? "")}`);
@@ -153,10 +164,26 @@ function renderHumanSuccess(command, data, warnings) {
             lines.push(`Exported providers to ${String(data?.exportedTo ?? "")}.`);
             break;
         case "init":
-            lines.push(`Initialized Codex directory ${String(data?.codexDir ?? "")}.`);
-            lines.push(`Created codexDir: ${String(data?.createdCodexDir ?? false)}`);
-            lines.push(`Created providers.json: ${String(data?.createdProvidersFile ?? false)}`);
-            lines.push(`providersAlreadyExisted: ${String(data?.providersAlreadyExisted ?? false)}`);
+            lines.push("Initialized codex-switch tool home.");
+            lines.push(`tool home: ${String(data?.toolHomeDir ?? "")}`);
+            lines.push(`tool config: ${String(data?.toolConfigPath ?? "")}`);
+            lines.push(`providers registry: ${String(data?.providersPath ?? "")}`);
+            lines.push(`tool home created: ${String(data?.createdToolHomeDir ?? false)}`);
+            lines.push(`tool config created: ${String(data?.createdToolConfigFile ?? false)}`);
+            lines.push(`providers registry created: ${String(data?.createdProvidersFile ?? false)}`);
+            lines.push("next step: run `codexs add ...` for a direct provider, or `codexs login copilot` before `add --copilot`.");
+            break;
+        case "login":
+            lines.push(`Copilot login ready: ${String(data?.authReady ?? false)}`);
+            lines.push(`upstream: ${String(data?.upstream ?? "")}`);
+            lines.push(`sdk installed: ${String(data?.sdkInstalled ?? false)}${data?.sdkInstalledNow ? " (installed now)" : ""}`);
+            lines.push(`copilot cli source: ${String(data?.cliSource ?? "not-needed")}`);
+            if (data?.cliCommand) {
+                lines.push(`copilot cli command: ${String(data?.cliCommand)}`);
+            }
+            lines.push(`login launched: ${String(data?.loginLaunched ?? false)}`);
+            lines.push(`auth ready: ${String(data?.authReady ?? false)}`);
+            lines.push("next step: run `codexs add <provider> --copilot --profile <name>` and then `codexs switch <provider>`.");
             break;
         case "migrate":
             lines.push(`Migrated providers in ${String(data?.codexDir ?? "")} using ${String(data?.strategy ?? "")}.`);
@@ -185,10 +212,12 @@ function renderHumanSuccess(command, data, warnings) {
             break;
         case "doctor": {
             const healthy = Boolean(data?.healthy);
-            lines.push(healthy ? "No issues found." : "Issues found:");
             const issues = data?.issues ?? [];
+            lines.push(healthy ? "Doctor summary: healthy. No action required." : `Doctor summary: ${issues.length} issue(s) need attention.`);
+            lines.push(`target runtime: ${String(data?.codexDir ?? "")}`);
             for (const issue of issues) {
-                lines.push(`${issue.code}: ${issue.message}`);
+                lines.push(`- ${String(issue.code)}: ${String(issue.message)}`);
+                lines.push(`  next step: ${renderDoctorIssueNextStep(issue)}`);
             }
             break;
         }
@@ -212,6 +241,112 @@ function renderHumanSuccess(command, data, warnings) {
     }
     return lines;
 }
+/**
+ * Summarizes runtime health for the human-readable status output.
+ */
+function renderStatusHealth(data) {
+    const configExists = Boolean(data?.configExists);
+    const providersExists = Boolean(data?.providersExists);
+    const auth = data?.auth ?? {};
+    const bridge = data?.copilotBridge ?? null;
+    const issues = Array.isArray(data?.issues) ? data?.issues : [];
+    const activeProviderResolvable = data?.activeProviderResolvable !== false;
+    const liveState = data?.liveState ?? {};
+    const copilotSdk = data?.copilotSdk ?? {};
+    const copilotAuth = data?.copilotAuth ?? null;
+    const runtimeProvider = typeof data?.runtimeProvider === "string" ? data.runtimeProvider : null;
+    const activePathUsesCopilot = runtimeProvider === "copilot-sdk-bridge";
+    if (!configExists || !providersExists) {
+        return "incomplete local state";
+    }
+    if (!activeProviderResolvable || liveState.reason === "shared-profile") {
+        return "active provider ambiguous";
+    }
+    if (issues.some((issue) => issue.code === "UNMANAGED_ACTIVE_PROFILE")) {
+        return "active profile unmanaged";
+    }
+    if (issues.some((issue) => issue.code === "ACTIVE_PROVIDER_UNRESOLVED")) {
+        return "active provider ambiguous";
+    }
+    if (issues.some((issue) => issue.code === "PROVIDER_BASE_URL_MISMATCH")) {
+        return "provider projection drift";
+    }
+    if (activePathUsesCopilot && copilotSdk.installed === false) {
+        return "copilot sdk missing";
+    }
+    if (activePathUsesCopilot && copilotAuth && copilotAuth.ready === false) {
+        return "copilot auth required";
+    }
+    if (activePathUsesCopilot && bridge && bridge.ok === false) {
+        return "copilot runtime needs repair";
+    }
+    if (auth.exists === false) {
+        return "auth projection missing";
+    }
+    if (auth.valid === false) {
+        return "auth projection invalid";
+    }
+    return "ok";
+}
+/**
+ * Renders the mapped provider line without claiming a unique winner for shared profiles.
+ */
+function renderStatusMappedProvider(data) {
+    if (typeof data?.provider === "string" && data.provider.length > 0) {
+        return data.provider;
+    }
+    const candidates = Array.isArray(data?.activeProviderCandidates) ? data?.activeProviderCandidates : [];
+    if (candidates.length > 1) {
+        return `(ambiguous: ${candidates.join(", ")})`;
+    }
+    return "(unmanaged or unresolved)";
+}
+/**
+ * Renders the active workflow path in status output.
+ */
+function renderStatusProviderPath(data) {
+    return typeof data?.runtimeProvider === "string" && data.runtimeProvider === "copilot-sdk-bridge" ? "copilot" : "direct";
+}
+/**
+ * Suggests the next operator action for the human-readable status output.
+ */
+function renderStatusNextStep(data, warnings) {
+    if (warnings.length > 0) {
+        return "run `codexs doctor` to inspect warnings before the next write command";
+    }
+    if (!data?.provider) {
+        return "run `codexs switch <provider>` after adding or adopting a managed provider";
+    }
+    return "run `codexs doctor` if you need a deeper diagnostic pass";
+}
+/**
+ * Turns structured doctor issue codes into repair-oriented next steps.
+ */
+function renderDoctorIssueNextStep(issue) {
+    switch (issue.code) {
+        case "CONFIG_NOT_FOUND":
+            return "restore or create config.toml before switching providers";
+        case "PROVIDERS_NOT_FOUND":
+            return "run `codexs init` and then add or migrate providers";
+        case "COPILOT_SDK_MISSING":
+            return "run `codexs login copilot` to install the optional Copilot runtime";
+        case "COPILOT_AUTH_REQUIRED":
+            return "run `codexs login copilot` to complete upstream authentication";
+        case "BRIDGE_STATE_STALE":
+        case "BRIDGE_STATE_MISSING":
+        case "BRIDGE_HEALTHCHECK_FAILED":
+            return "reselect the provider with `codexs switch <provider>` or inspect bridge state";
+        case "UNMANAGED_ACTIVE_PROFILE":
+            return "switch to a managed provider or adopt the active profile with `codexs migrate`";
+        case "ACTIVE_PROVIDER_UNRESOLVED":
+        case "SHARED_PROFILE_REFERENCE":
+            return "make provider-to-profile mappings unique before relying on current-provider detection";
+        case "PROVIDER_BASE_URL_MISMATCH":
+            return "rerun `codexs edit <provider> --base-url <url>` or `codexs switch <provider>` to repair the runtime projection";
+        default:
+            return "inspect the issue details and rerun `codexs doctor` after fixing the state";
+    }
+}
 /**
  * Writes one rendered line to either stdout or stderr.
  */

package/dist/commands/handlers.js

@@ -79,11 +79,11 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
     const paths = setupPaths;
     switch (ctx.command) {
         case "list":
-            return (0, list_providers_1.listProviders)(paths.providersPath);
+            return (0, list_providers_1.listProviders)(paths.providersPath, paths.configPath);
         case "show": {
             let providerName = parsed.positionals[0] ?? null;
             if (!providerName && (0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
-                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, "Choose a provider to show");
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, paths.configPath, "Choose a provider to show");
             }
             if (!providerName) {
                 throw (0, errors_1.cliError)("INVALID_ARGUMENT", "Missing provider name for show command.");
@@ -172,6 +172,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                 (0, copilot_installer_1.installCopilotSdk)(paths.runtimesDir);
                 installedNow = true;
             }
+            const availability = (0, copilot_cli_1.checkCopilotCliAvailable)(paths.runtimesDir);
             try {
                 await (0, copilot_adapter_1.readCopilotAuthState)(paths.runtimesDir);
                 return {
@@ -181,6 +182,8 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                         sdkInstalledNow: installedNow,
                         authReady: true,
                         loginLaunched: false,
+                        cliSource: availability.ok ? availability.source ?? null : null,
+                        cliCommand: availability.command ?? null,
                     },
                 };
             }
@@ -190,7 +193,6 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                     throw error;
                 }
             }
-            const availability = (0, copilot_cli_1.checkCopilotCliAvailable)(paths.runtimesDir);
             if (!availability.ok) {
                 throw (0, errors_1.cliError)("COPILOT_CLI_MISSING", "The official Copilot CLI could not be resolved from the installed runtime or PATH.", {
                     cause: availability.cause,
@@ -225,6 +227,8 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                     sdkInstalledNow: installedNow,
                     authReady: true,
                     loginLaunched: true,
+                    cliSource: availability.source ?? null,
+                    cliCommand: availability.command ?? null,
                 },
             };
         }
@@ -242,7 +246,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
         case "switch": {
             let providerName = parsed.positionals[0] ?? null;
             if (!providerName && (0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
-                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, "Choose a provider to switch to");
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, paths.configPath, "Choose a provider to switch to");
             }
             if (!providerName) {
                 throw (0, errors_1.cliError)("PROVIDER_NOT_FOUND", "Missing provider name for switch command.");
@@ -413,7 +417,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
         case "edit": {
             let providerName = parsed.positionals[0] ?? null;
             if (!providerName && (0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
-                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, "Choose a provider to edit");
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, paths.configPath, "Choose a provider to edit");
             }
             if (!providerName) {
                 throw (0, errors_1.cliError)("INVALID_ARGUMENT", "Missing provider name for edit command.");
@@ -472,7 +476,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             const force = (0, args_1.hasFlag)(parsed.commandOptions, "--force");
             const switchToProfile = (0, args_1.getSingleOption)(parsed.commandOptions, "--switch-to", false) ?? undefined;
             if (!providerName && (0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
-                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, "Choose a provider to remove");
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, paths.configPath, "Choose a provider to remove");
             }
             if (!providerName) {
                 throw (0, errors_1.cliError)("PROVIDER_NOT_FOUND", "Missing provider name for remove command.");

package/dist/commands/help.js

@@ -30,6 +30,10 @@ function buildHelpText(commandName) {
             "codex-switch",
             "",
             "Manage and switch local Codex provider/profile configuration safely.",
+            "Primary workflows: direct providers use init -> add -> switch -> status -> doctor.",
+            "Primary workflows: Copilot providers use init -> login copilot -> add --copilot -> switch -> status -> doctor.",
+            "Advanced adopt flows use migrate only when you already have Codex runtime state to import.",
+            "Deprecated entry: setup still exists only to point callers to init or migrate.",
             "",
             "Usage:",
             "  codexs <command> [options]",
@@ -61,14 +65,14 @@ function buildHelpText(commandName) {
             "",
             "Examples:",
             "  codexs init",
+            "  codexs add packycode --profile packycode --api-key sk-xxx",
+            "  codexs switch packycode",
+            "  codexs status",
+            "  codexs doctor",
             "  codexs login copilot",
+            "  codexs add copilot-main --copilot --profile copilot-main",
             "  codexs migrate",
-            "  codexs list",
-            "  codexs switch",
-            "  codexs bridge start",
-            "  codexs add packycode --profile packycode --api-key sk-xxx",
             "  codexs config show",
-            "  codexs remove freemodel",
             "  codexs backups list",
             "  codexs rollback",
             "  codexs help add",

package/dist/commands/registry.js

@@ -88,13 +88,14 @@ exports.COMMANDS = [
         tokens: ["init"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Initialize the codex-switch tool home and registry files.",
+        summary: "Initialize the codex-switch tool home for the primary workflow.",
         usage: ["codexs init [--json] [--codex-dir <path>]"],
         details: [
             "Creates codex-switch.json and providers.json under the tool home when they do not exist yet.",
             "Does not create or validate config.toml, auth.json, or the target Codex directory.",
             "When --codex-dir is passed explicitly and codex-switch.json does not exist yet, init persists it as defaultCodexDir.",
             "Otherwise init stays scoped to tool-home state and does not persist fallback Codex directory resolution.",
+            "Use init first for fresh direct-provider or Copilot setups.",
         ],
         examples: ["codexs init", "codexs init --json --codex-dir ~/.codex"],
     },
@@ -119,13 +120,14 @@ exports.COMMANDS = [
         tokens: ["migrate"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Adopt unmanaged Codex config profiles into providers.json.",
+        summary: "Adopt existing Codex runtime profiles into managed providers.json state.",
         usage: ["codexs migrate [--json] [--codex-dir <path>] [--merge|--overwrite]"],
         details: [
             "Reads config.toml profiles, collects complete provider records, then writes providers.json under managed backup flow.",
             "TTY mode can collect missing provider details and choose merge or overwrite when providers.json already exists.",
             "Migrate adopts only runtime profiles that already expose model, model_provider, and matching base_url.",
             "Non-TTY and --json runs still fail fast because migrate profile selection and provider details remain interactive in this release.",
+            "Treat migrate as an advanced adopt helper for existing runtime state, not the default first step for fresh installs.",
         ],
         examples: ["codexs migrate", "codexs migrate --overwrite --json --codex-dir ~/.codex"],
     },
@@ -134,12 +136,12 @@ exports.COMMANDS = [
         tokens: ["setup"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Deprecated. Use init or migrate instead.",
+        summary: "Deprecated. Kept only to point callers to init or migrate.",
         usage: ["codexs setup"],
         details: [
             "setup no longer performs initialization or migration work.",
-            "Use init for AI-friendly idempotent providers.json initialization.",
-            "Use migrate for interactive adoption from existing config.toml profiles.",
+            "Use init for the primary fresh-install workflow.",
+            "Use migrate only when adopting from existing config.toml profiles.",
         ],
         examples: ["codexs help init", "codexs help migrate"],
     },
@@ -148,9 +150,13 @@ exports.COMMANDS = [
         tokens: ["list"],
         handler: handlers_1.handleRegisteredCommand,
         group: "read",
-        summary: "List configured providers from providers.json.",
+        summary: "List managed providers with profile, type, and current-state hints.",
         usage: ["codexs list [--json] [--codex-dir <path>]"],
-        details: ["Reads providers.json and prints provider-to-profile mappings.", "Use --json for machine-readable automation output."],
+        details: [
+            "Reads providers.json and prints provider-to-profile mappings together with provider type.",
+            "When the active profile is shared by multiple providers, list surfaces the ambiguity instead of inventing one current provider.",
+            "Use --json for machine-readable automation output.",
+        ],
         examples: ["codexs list", "codexs list --json"],
     },
     {
@@ -182,12 +188,13 @@ exports.COMMANDS = [
         tokens: ["status"],
         handler: handlers_1.handleRegisteredCommand,
         group: "read",
-        summary: "Show a quick status summary for the local Codex directory.",
+        summary: "Show tool-home, target-runtime, provider-path, and runtime-health status.",
         usage: ["codexs status [--json] [--codex-dir <path>]"],
         details: [
-            "Reports file presence, current profile, and whether the live profile is mapped.",
-            "When the active provider uses a local runtime bridge, status also reports bridge and SDK state.",
-            "Surfaces config consistency signals without mutating any files.",
+            "Reports the target Codex runtime, tool-home storage roles, current profile, and whether the live profile is mapped.",
+            "When the active provider uses a local runtime bridge, status also reports bridge, Copilot SDK, and upstream auth state.",
+            "Surfaces dual-path config consistency signals without mutating any files.",
+            "Organizes the human-readable view around current state, health impact, and next step.",
             "Use doctor for deeper diagnostics.",
         ],
         examples: ["codexs status", "codexs status --json --codex-dir ./.tmp-codex"],
@@ -216,7 +223,7 @@ exports.COMMANDS = [
         tokens: ["add"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Add a provider with explicit flags or progressive TTY prompts.",
+        summary: "Add a managed provider for the primary direct or Copilot workflows.",
         usage: [
             "codexs add <provider> --profile <name> --api-key <key> [--base-url <url>] [--note <text>] [--tag <tag> ...]",
             "codexs add <provider> --copilot --profile <name> [--bridge-host <host>] [--bridge-port <port>] [--bridge-api-key <secret>] [--install-copilot-sdk]",
@@ -247,7 +254,7 @@ exports.COMMANDS = [
         tokens: ["switch"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Switch the active config profile to a provider.",
+        summary: "Switch the active runtime to a managed provider.",
         usage: ["codexs switch <provider> [--json] [--codex-dir <path>]"],
         details: [
             "When <provider> is omitted in a TTY, an interactive provider selector is shown.",
@@ -255,6 +262,7 @@ exports.COMMANDS = [
             "Direct providers update the active config profile and rewrite auth.json with auth_mode=apikey plus OPENAI_API_KEY.",
             "Copilot bridge providers also rewrite OPENAI_API_KEY to the local bridge secret while managing runtime routing and bridge state.",
             "Copilot bridge providers probe the optional official SDK before switching and fail fast if it is missing.",
+            "Switch succeeds only after the managed profile projection is written to the target runtime.",
             "Backs up config.toml and auth.json and rolls back on failure.",
         ],
         examples: ["codexs switch freemodel", "codexs switch packycode --json"],
@@ -321,7 +329,7 @@ exports.COMMANDS = [
         tokens: ["doctor"],
         handler: handlers_1.handleRegisteredCommand,
         group: "recovery",
-        summary: "Run configuration and environment diagnostics.",
+        summary: "Run issue-first diagnostics across tool-home and target-runtime state.",
         usage: ["codexs doctor [--json] [--codex-dir <path>]"],
         details: [
             "Checks the expected config files, provider/profile consistency, and Codex CLI availability.",

package/dist/domain/config.js

@@ -268,6 +268,8 @@ function buildManagedProfileViews(document, providers) {
  */
 function collectConfigConsistencyIssues(document, providers) {
     const issues = [];
+    const providerMap = providers?.providers ?? null;
+    const profileLinkMap = buildProfileLinkMap(providers);
     for (const view of buildManagedProfileViews(document, providers)) {
         if (view.source === "orphaned-reference") {
             issues.push({
@@ -319,11 +321,34 @@ function collectConfigConsistencyIssues(document, providers) {
                         modelProvider: view.modelProvider,
                     });
                 }
+                else {
+                    const profileLinkInfo = profileLinkMap.get(view.name);
+                    if (profileLinkInfo &&
+                        profileLinkInfo.linkedProviders.length === 1 &&
+                        providerMap) {
+                        const providerName = profileLinkInfo.linkedProviders[0];
+                        const provider = providerMap[providerName];
+                        if (provider &&
+                            !provider.runtime &&
+                            typeof provider.baseUrl === "string" &&
+                            provider.baseUrl.trim() !== "" &&
+                            provider.baseUrl !== modelProviderSection.baseUrl) {
+                            issues.push({
+                                code: "PROVIDER_BASE_URL_MISMATCH",
+                                profile: view.name,
+                                provider: providerName,
+                                providerBaseUrl: provider.baseUrl,
+                                configBaseUrl: modelProviderSection.baseUrl,
+                                providerType: "direct",
+                            });
+                        }
+                    }
+                }
             }
         }
     }
     if (document.activeProfile) {
-        const activeLinkInfo = buildProfileLinkMap(providers).get(document.activeProfile);
+        const activeLinkInfo = profileLinkMap.get(document.activeProfile);
         if (!activeLinkInfo) {
             issues.push({
                 code: "UNMANAGED_ACTIVE_PROFILE",

package/dist/domain/providers.js

@@ -10,6 +10,7 @@ exports.isRuntimeBackedProvider = isRuntimeBackedProvider;
 exports.isCopilotBridgeProvider = isCopilotBridgeProvider;
 exports.buildCopilotBridgeBaseUrl = buildCopilotBridgeBaseUrl;
 exports.buildCopilotModelProviderProjection = buildCopilotModelProviderProjection;
+exports.buildDirectModelProviderProjection = buildDirectModelProviderProjection;
 /**
  * Validates and normalizes unknown JSON into the providers.json domain model.
  */
@@ -162,6 +163,21 @@ function buildCopilotModelProviderProjection(runtime) {
         wireApi: "responses",
     };
 }
+/**
+ * Builds the Codex-facing custom model_provider projection for a direct provider.
+ */
+function buildDirectModelProviderProjection(profile, baseUrl) {
+    const normalizedBaseUrl = baseUrl.trim();
+    if (!normalizedBaseUrl) {
+        throw new Error(`Direct model provider "${profile}" requires a non-empty base_url.`);
+    }
+    return {
+        baseUrl: normalizedBaseUrl,
+        name: profile.trim(),
+        requiresOpenAiAuth: true,
+        wireApi: "responses",
+    };
+}
 /**
  * Validates one runtime-backed provider block.
  */

package/dist/domain/runtime-state.js

@@ -97,7 +97,9 @@ function inspectLiveStateDrift(currentProfile, providers) {
         return {
             currentProfile,
             mappedProvider: null,
+            mappedProviders: [],
             profileMapped: false,
+            providerResolvable: false,
             canBackfillActiveProvider: false,
             reason: providers ? "profile-missing" : "config-missing",
         };
@@ -106,27 +108,47 @@ function inspectLiveStateDrift(currentProfile, providers) {
         return {
             currentProfile,
             mappedProvider: null,
+            mappedProviders: [],
             profileMapped: false,
+            providerResolvable: false,
             canBackfillActiveProvider: false,
             reason: "providers-missing",
         };
     }
+    const mappedProviders = [];
     for (const [name, provider] of Object.entries(providers.providers)) {
-        // A direct profile match means the runtime state is still managed.
         if (provider.profile === currentProfile) {
-            return {
-                currentProfile,
-                mappedProvider: name,
-                profileMapped: true,
-                canBackfillActiveProvider: false,
-                reason: "ok",
-            };
+            mappedProviders.push(name);
         }
     }
+    if (mappedProviders.length === 1) {
+        return {
+            currentProfile,
+            mappedProvider: mappedProviders[0],
+            mappedProviders,
+            profileMapped: true,
+            providerResolvable: true,
+            canBackfillActiveProvider: false,
+            reason: "ok",
+        };
+    }
+    if (mappedProviders.length > 1) {
+        return {
+            currentProfile,
+            mappedProvider: null,
+            mappedProviders,
+            profileMapped: true,
+            providerResolvable: false,
+            canBackfillActiveProvider: false,
+            reason: "shared-profile",
+        };
+    }
     return {
         currentProfile,
         mappedProvider: null,
+        mappedProviders: [],
         profileMapped: false,
+        providerResolvable: false,
         canBackfillActiveProvider: true,
         reason: "provider-unmapped",
     };