@minniexcode/codex-switch 0.0.6 → 0.0.8

package/README.AI.md

@@ -17,7 +17,8 @@ Primary goals:
 ## Main Command Surface
 
 ```bash
-codexs setup
+codexs init
+codexs migrate
 codexs list
 codexs show <provider>
 codexs current
@@ -92,11 +93,12 @@ codexs status --json
 Current package version in this repository:
 
 ```text
-0.0.4
+0.0.7
 ```
 
 Recent version summary:
 
+- `0.0.7`: command-surface refactor, env_key/auth-mirror model corrections, and the `setup` split into `init` plus `migrate`
 - `0.0.4`: setup/show/edit/backups list/specific rollback/import merge and clearer CLI semantics
 - `0.0.3`: interactive TTY flows and improved help
 - `0.0.2`: mutation orchestration, backups, rollback, locks, drift detection improvements
@@ -107,4 +109,5 @@ Recent version summary:
 - Prefer `--json` when invoking commands programmatically
 - Treat `providers.json` as sensitive because it may contain API keys
 - Do not assume silent write-back from runtime files into `providers.json`
+- Prefer `init` for repeatable machine setup and `migrate` for human-led adopt flows
 - Use `docs/` for deeper product and architecture context

package/README.md

@@ -10,14 +10,15 @@ It is designed for users who work with multiple Codex providers, API keys, or pr
 
 What it does:
 
-- Initialize `providers.json` from an existing Codex directory
+- Initialize an empty managed `providers.json`
+- Migrate unmanaged runtime profiles from an existing Codex directory
 - List, show, add, edit, and remove provider records
 - Switch the active provider/profile safely
 - Import and export provider definitions
 - Run diagnostics and detect local drift
 - List backups and roll back to a previous managed state
 
-Current version: `0.0.6`
+Current version: `0.0.8`
 
 ## Install
 
@@ -44,7 +45,8 @@ codexs --help
 Take over an existing Codex directory:
 
 ```bash
-codexs setup
+codexs init
+codexs migrate
 ```
 
 Inspect managed providers:
@@ -72,7 +74,8 @@ codexs doctor
 ## Common Commands
 
 ```bash
-codexs setup
+codexs init
+codexs migrate
 codexs list
 codexs show <provider>
 codexs current
@@ -92,6 +95,8 @@ Command help:
 
 ```bash
 codexs help switch
+codexs help init
+codexs help migrate
 codexs help setup
 ```
 
@@ -120,8 +125,9 @@ Notes:
 
 This CLI supports both human TTY use and non-interactive automation.
 
-Current exception:
-- `setup` in `0.0.6` is intentionally TTY-only for adopt initialization. It requires interactive profile selection and provider detail collection, and non-interactive/`--json` runs fail fast with a structured error.
+Current exceptions:
+- `init` is automation-friendly and idempotent, but still returns a structured error in non-interactive or `--json` mode when the resolved target directory does not exist.
+- `migrate` remains intentionally TTY-only for adopt initialization. It requires interactive profile selection and provider detail collection, and non-interactive/`--json` runs fail fast with a structured error.
 
 Recommended global flags:
 

package/dist/app/add-provider.js

@@ -1,12 +1,48 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.addProvider = addProvider;
+const crypto = __importStar(require("node:crypto"));
 const config_1 = require("../domain/config");
 const providers_1 = require("../domain/providers");
 const errors_1 = require("../domain/errors");
 const config_repo_1 = require("../storage/config-repo");
 const fs_utils_1 = require("../storage/fs-utils");
 const providers_repo_1 = require("../storage/providers-repo");
+const auth_repo_1 = require("../storage/auth-repo");
+const copilot_installer_1 = require("../runtime/copilot-installer");
 const run_mutation_1 = require("./run-mutation");
 /**
  * Adds a new provider record to the managed providers registry.
@@ -17,8 +53,37 @@ function addProvider(args) {
     if (providers.providers[args.providerName]) {
         throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", `Provider "${args.providerName}" already exists.`);
     }
+    const bridgeHost = args.bridgeHost ?? "127.0.0.1";
+    const bridgePort = args.bridgePort ?? 4141;
+    const runtime = args.copilot
+        ? {
+            kind: "copilot-sdk-bridge",
+            upstream: "github-copilot",
+            bridgeHost,
+            bridgePort,
+            bridgePath: "/v1",
+            premiumRequests: true,
+            authSource: "official-sdk",
+            sdkInstallMode: "lazy",
+        }
+        : undefined;
+    if (args.copilot) {
+        const installStatus = (0, copilot_installer_1.probeCopilotSdkInstall)();
+        if (!installStatus.installed) {
+            if (!args.installCopilotSdk) {
+                throw (0, errors_1.cliError)(args.interactive ? "COPILOT_SDK_MISSING" : "COPILOT_SDK_INSTALL_REQUIRES_TTY", args.interactive
+                    ? "The optional Copilot SDK runtime is not installed. Re-run with --install-copilot-sdk or confirm installation interactively."
+                    : "The optional Copilot SDK runtime is not installed. Pass --install-copilot-sdk when running non-interactively.", {
+                    installDir: installStatus.installDir,
+                    packageName: installStatus.packageName,
+                });
+            }
+            (0, copilot_installer_1.installCopilotSdk)();
+        }
+    }
     const document = (0, config_repo_1.readStructuredConfig)(args.configPath);
     const existingProfile = document.profiles.find((profile) => profile.name === args.profile);
+    const existingModelProvider = document.modelProviders.find((entry) => entry.name === args.profile);
     if (!existingProfile && !args.createProfile) {
         throw (0, errors_1.cliError)("PROFILE_NOT_FOUND", `Profile "${args.profile}" does not exist in config.toml.`, {
             profile: args.profile,
@@ -33,21 +98,31 @@ function addProvider(args) {
             }),
         }
         : undefined;
-    if (!existingProfile && args.createProfile) {
-        (0, config_repo_1.requireModelProviderRuntimeSection)(document, args.profile);
-    }
+    const upsertModelProviders = !existingModelProvider && args.createProfile
+        ? {
+            [args.profile]: {
+                baseUrl: args.copilot ? (0, providers_1.buildCopilotBridgeBaseUrl)(runtime) : args.baseUrl ?? undefined,
+                envKey: (0, config_1.buildManagedProfileEnvKey)(args.profile),
+            },
+        }
+        : undefined;
     if (existingProfile) {
         (0, config_repo_1.requireManagedProfileRuntime)(document, providers, args.profile);
     }
+    const envKey = existingModelProvider?.envKey ?? (0, config_1.buildManagedProfileEnvKey)(args.profile);
+    const apiKey = args.copilot ? args.bridgeApiKey ?? crypto.randomBytes(24).toString("hex") : args.apiKey;
+    const baseUrl = args.copilot ? (0, providers_1.buildCopilotBridgeBaseUrl)(runtime) : args.baseUrl ?? undefined;
     const next = {
         providers: {
             ...providers.providers,
             [args.providerName]: (0, providers_1.cleanProviderRecord)({
                 profile: args.profile,
-                apiKey: args.apiKey,
-                baseUrl: args.baseUrl ?? undefined,
+                apiKey,
+                envKey,
+                baseUrl,
                 note: args.note ?? undefined,
                 tags: args.tags,
+                runtime,
             }),
         },
     };
@@ -59,18 +134,28 @@ function addProvider(args) {
         files: [
             { absolutePath: args.providersPath, relativePath: "providers.json" },
             { absolutePath: args.configPath, relativePath: "config.toml" },
+            { absolutePath: args.authPath, relativePath: "auth.json" },
         ],
         mutate: () => {
             const configPlan = (0, config_repo_1.createConfigMutationPlan)(document, {
                 upsertProfiles,
+                upsertModelProviders,
             });
             // Persist only the normalized provider payload so later reads are deterministic.
             (0, providers_repo_1.writeProvidersFile)(args.providersPath, next);
             (0, config_repo_1.applyConfigMutation)(args.configPath, document, configPlan);
+            if (document.activeProfile === args.profile) {
+                const activeProviderName = (0, config_repo_1.resolveActiveProviderName)(document, next);
+                const existingAuth = (0, auth_repo_1.readAuthFileIfExists)(args.authPath);
+                (0, auth_repo_1.writeAuthFile)(args.authPath, next.providers[activeProviderName], existingAuth ?? undefined);
+            }
             return {
                 provider: args.providerName,
                 profile: args.profile,
+                envKey,
+                runtimeKind: runtime?.kind ?? null,
                 createdProfileSections: configPlan.createdProfileSections,
+                createdModelProviderSections: configPlan.createdModelProviderSections,
                 deletedProfileSections: configPlan.deletedProfileSections,
                 keptSharedProfiles: [],
                 switchedActiveProfile: configPlan.switchedActiveProfile,

package/dist/app/edit-provider.js

@@ -7,6 +7,7 @@ const providers_1 = require("../domain/providers");
 const config_repo_1 = require("../storage/config-repo");
 const fs_utils_1 = require("../storage/fs-utils");
 const providers_repo_1 = require("../storage/providers-repo");
+const auth_repo_1 = require("../storage/auth-repo");
 const run_mutation_1 = require("./run-mutation");
 /**
  * Updates selected fields on a single managed provider.
@@ -23,13 +24,7 @@ function editProvider(args) {
         });
     }
     const updatedFields = [];
-    const nextRecord = (0, providers_1.cleanProviderRecord)({
-        profile: args.profile ?? current.profile,
-        apiKey: args.apiKey ?? current.apiKey,
-        baseUrl: args.baseUrl === null ? undefined : args.baseUrl ?? current.baseUrl,
-        note: args.note === null ? undefined : args.note ?? current.note,
-        tags: args.tags ?? current.tags,
-    });
+    const nextProfile = args.profile ?? current.profile;
     if (args.profile !== undefined && args.profile !== current.profile) {
         updatedFields.push("profile");
     }
@@ -46,10 +41,12 @@ function editProvider(args) {
         updatedFields.push("tags");
     }
     const oldProfile = current.profile;
-    const newProfile = nextRecord.profile;
+    const newProfile = nextProfile;
     const targetSection = document.profiles.find((profile) => profile.name === newProfile) ?? null;
+    const targetModelProviderSection = document.modelProviders.find((entry) => entry.name === newProfile) ?? null;
     const targetProfileExists = Boolean(targetSection);
     let upsertProfiles;
+    let upsertModelProviders;
     if (!targetProfileExists) {
         if (!args.createProfile) {
             throw (0, errors_1.cliError)("PROFILE_NOT_FOUND", `Profile "${newProfile}" does not exist in config.toml.`, {
@@ -63,11 +60,30 @@ function editProvider(args) {
                 modelProvider: newProfile,
             }),
         };
-        (0, config_repo_1.requireModelProviderRuntimeSection)(document, newProfile);
+        upsertModelProviders = {
+            [newProfile]: {
+                baseUrl: args.baseUrl ?? undefined,
+                envKey: (0, config_1.buildManagedProfileEnvKey)(newProfile),
+            },
+        };
     }
     else {
         (0, config_repo_1.requireManagedProfileRuntime)(document, providers, newProfile);
     }
+    const nextEnvKey = args.profile !== undefined && args.profile !== current.profile
+        ? targetModelProviderSection?.envKey ?? (0, config_1.buildManagedProfileEnvKey)(newProfile)
+        : current.envKey;
+    if (nextEnvKey !== current.envKey) {
+        updatedFields.push("envKey");
+    }
+    const nextRecord = (0, providers_1.cleanProviderRecord)({
+        profile: newProfile,
+        apiKey: args.apiKey ?? current.apiKey,
+        envKey: nextEnvKey,
+        baseUrl: args.baseUrl === null ? undefined : args.baseUrl ?? current.baseUrl,
+        note: args.note === null ? undefined : args.note ?? current.note,
+        tags: args.tags ?? current.tags,
+    });
     if (targetProfileExists && args.model !== undefined) {
         upsertProfiles = {
             [newProfile]: {
@@ -78,6 +94,7 @@ function editProvider(args) {
             updatedFields.push("model");
         }
     }
+    // Compute profile link ownership after the edit so lifecycle planning can decide whether sections stay, move, or delete.
     const remainingLinksByProfile = new Map();
     for (const [name, provider] of Object.entries(providers.providers)) {
         if (name === args.providerName) {
@@ -108,24 +125,35 @@ function editProvider(args) {
         files: [
             { absolutePath: args.providersPath, relativePath: "providers.json" },
             { absolutePath: args.configPath, relativePath: "config.toml" },
+            { absolutePath: args.authPath, relativePath: "auth.json" },
         ],
         mutate: () => {
             const configPlan = (0, config_repo_1.createConfigMutationPlan)(document, {
                 upsertProfiles,
+                upsertModelProviders,
                 deleteProfiles: lifecycle.deletedProfileSections,
                 setActiveProfile: lifecycle.nextActiveProfile,
             });
-            (0, providers_repo_1.writeProvidersFile)(args.providersPath, {
+            const nextProviders = {
                 providers: {
                     ...providers.providers,
                     [args.providerName]: nextRecord,
                 },
-            });
+            };
+            // Write providers first so the registry and config move together inside the managed backup boundary.
+            (0, providers_repo_1.writeProvidersFile)(args.providersPath, nextProviders);
             (0, config_repo_1.applyConfigMutation)(args.configPath, document, configPlan);
+            const updatedDocument = (0, config_repo_1.readStructuredConfig)(args.configPath);
+            if (updatedDocument.activeProfile) {
+                const activeProviderName = (0, config_repo_1.resolveActiveProviderName)(updatedDocument, nextProviders);
+                const existingAuth = (0, auth_repo_1.readAuthFileIfExists)(args.authPath);
+                (0, auth_repo_1.writeAuthFile)(args.authPath, nextProviders.providers[activeProviderName], existingAuth ?? undefined);
+            }
             return {
                 provider: args.providerName,
                 updatedFields,
                 createdProfileSections: configPlan.createdProfileSections,
+                createdModelProviderSections: configPlan.createdModelProviderSections,
                 deletedProfileSections: configPlan.deletedProfileSections,
                 keptSharedProfiles: lifecycle.keptSharedProfiles,
                 switchedActiveProfile: lifecycle.switchedActiveProfile,

package/dist/app/get-status.js

@@ -37,12 +37,17 @@ exports.getStatus = getStatus;
 const fs = __importStar(require("node:fs"));
 const config_1 = require("../domain/config");
 const runtime_state_1 = require("../domain/runtime-state");
+const providers_1 = require("../domain/providers");
 const config_repo_1 = require("../storage/config-repo");
 const providers_repo_1 = require("../storage/providers-repo");
+const auth_repo_1 = require("../storage/auth-repo");
+const copilot_installer_1 = require("../runtime/copilot-installer");
+const copilot_bridge_1 = require("../runtime/copilot-bridge");
+const copilot_adapter_1 = require("../runtime/copilot-adapter");
 /**
  * Reports the current on-disk runtime state and how it maps back to managed providers.
  */
-function getStatus(codexDir, configPath, providersPath) {
+async function getStatus(codexDir, configPath, providersPath, authPath) {
     const configExists = fs.existsSync(configPath);
     const providersExists = fs.existsSync(providersPath);
     let currentProfile = null;
@@ -50,6 +55,7 @@ function getStatus(codexDir, configPath, providersPath) {
     const providers = providersExists ? (0, providers_repo_1.readProvidersFile)(providersPath) : null;
     let configViews = [];
     let consistencyIssues = [];
+    const authState = (0, auth_repo_1.readManagedAuthState)(authPath);
     if (configExists) {
         const document = (0, config_repo_1.readStructuredConfig)(configPath);
         currentProfile = document.activeProfile;
@@ -60,6 +66,18 @@ function getStatus(codexDir, configPath, providersPath) {
         }
     }
     const liveState = (0, runtime_state_1.inspectLiveStateDrift)(currentProfile, providers);
+    const activeProviderCandidates = currentProfile && providers ? (0, providers_1.findProvidersByProfile)(providers, currentProfile) : [];
+    const activeProvider = activeProviderCandidates.length === 1 && providers ? providers.providers[activeProviderCandidates[0]] : null;
+    const copilotInstall = (0, copilot_installer_1.probeCopilotSdkInstall)();
+    const copilotBridge = activeProvider && (0, providers_1.isCopilotBridgeProvider)(activeProvider) ? await (0, copilot_bridge_1.probeCopilotBridgeRuntime)(activeProvider) : null;
+    const copilotAuth = activeProvider && (0, providers_1.isCopilotBridgeProvider)(activeProvider)
+        ? await (0, copilot_adapter_1.readCopilotAuthState)().catch((error) => ({
+            ready: false,
+            source: "official-sdk",
+            mode: "session",
+            error: error instanceof Error ? error.message : String(error),
+        }))
+        : null;
     if (liveState.canBackfillActiveProvider) {
         // Surface unmanaged live state without mutating anything during a read-only status call.
         warnings.push("Current config profile is not mapped in providers.json. Backfill would be required before treating live state as managed.");
@@ -74,7 +92,19 @@ function getStatus(codexDir, configPath, providersPath) {
             currentProfile,
             currentProfileMapped: liveState.profileMapped,
             provider: liveState.mappedProvider,
+            activeProviderResolvable: activeProviderCandidates.length === 1,
+            activeProviderCandidates,
+            runtimeProvider: activeProvider && (0, providers_1.isCopilotBridgeProvider)(activeProvider) ? activeProvider.runtime?.kind ?? null : null,
+            copilotSdk: {
+                installed: copilotInstall.installed,
+                installDir: copilotInstall.installDir,
+                packageName: copilotInstall.packageName,
+                packageVersion: copilotInstall.packageVersion ?? null,
+            },
+            copilotAuth,
+            copilotBridge,
             liveState,
+            auth: authState,
             configProfiles: configViews,
             issues: consistencyIssues,
         },

package/dist/app/init-codex.js

@@ -0,0 +1,68 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initCodex = initCodex;
+const fs = __importStar(require("node:fs"));
+const errors_1 = require("../domain/errors");
+const fs_utils_1 = require("../storage/fs-utils");
+const providers_repo_1 = require("../storage/providers-repo");
+/**
+ * Initializes a Codex directory for managed providers.json usage without requiring live Codex state.
+ */
+function initCodex(args) {
+    const codexDirExists = fs.existsSync(args.codexDir);
+    if (!codexDirExists && !args.createCodexDir) {
+        throw (0, errors_1.cliError)("CODEX_DIR_NOT_FOUND", "The requested Codex directory does not exist.", {
+            codexDir: args.codexDir,
+        });
+    }
+    if (!codexDirExists) {
+        (0, fs_utils_1.ensureDir)(args.codexDir);
+    }
+    const providersExists = fs.existsSync(args.providersPath);
+    if (!providersExists) {
+        (0, providers_repo_1.writeProvidersFile)(args.providersPath, { providers: {} });
+    }
+    return {
+        data: {
+            codexDir: args.codexDir,
+            createdCodexDir: !codexDirExists,
+            createdProvidersFile: !providersExists,
+            providersAlreadyExisted: providersExists,
+            configExists: fs.existsSync(args.configPath),
+            authExists: fs.existsSync(args.authPath),
+        },
+    };
+}

package/dist/app/list-providers.js

@@ -11,6 +11,7 @@ function listProviders(providersPath) {
     const items = names.map((name) => ({
         name,
         profile: providers.providers[name].profile,
+        envKey: providers.providers[name].envKey,
         note: providers.providers[name].note ?? null,
         tags: providers.providers[name].tags ?? [],
     }));

package/dist/app/run-doctor.js

@@ -41,10 +41,15 @@ const config_repo_1 = require("../storage/config-repo");
 const providers_repo_1 = require("../storage/providers-repo");
 const errors_1 = require("../domain/errors");
 const codex_probe_1 = require("../runtime/codex-probe");
+const auth_repo_1 = require("../storage/auth-repo");
+const providers_1 = require("../domain/providers");
+const copilot_installer_1 = require("../runtime/copilot-installer");
+const copilot_bridge_1 = require("../runtime/copilot-bridge");
+const copilot_adapter_1 = require("../runtime/copilot-adapter");
 /**
  * Performs consistency checks across config.toml, providers.json, and the local Codex CLI.
  */
-function runDoctor(args) {
+async function runDoctor(args) {
     const issues = [];
     let currentProfile = null;
     let providers = null;
@@ -78,6 +83,7 @@ function runDoctor(args) {
         try {
             providers = (0, providers_repo_1.readProvidersFile)(args.providersPath);
             if (document) {
+                // Preserve domain issue codes while translating them into user-facing diagnostic messages.
                 for (const issue of (0, config_1.collectConfigConsistencyIssues)(document, providers)) {
                     issues.push({
                         ...issue,
@@ -95,6 +101,77 @@ function runDoctor(args) {
             });
         }
     }
+    const authState = (0, auth_repo_1.readManagedAuthState)(args.authPath);
+    if (authState.exists && !authState.valid) {
+        issues.push({
+            code: "AUTH_JSON_INVALID",
+            message: authState.parseError ?? "auth.json is invalid.",
+            file: args.authPath,
+        });
+    }
+    if (document?.activeProfile && providers) {
+        const matches = (0, providers_1.findProvidersByProfile)(providers, document.activeProfile);
+        if (matches.length === 1) {
+            const activeProvider = providers.providers[matches[0]];
+            const payload = authState.payload ?? {};
+            const actualKeys = authState.managedSecretKeys;
+            if (authState.authMode !== null && authState.authMode !== "apikey") {
+                issues.push({
+                    code: "AUTH_JSON_INVALID",
+                    message: `auth.json auth_mode must be "apikey", found "${authState.authMode}".`,
+                });
+            }
+            if (!actualKeys.includes(activeProvider.envKey) || actualKeys.length !== 1) {
+                issues.push({
+                    code: "AUTH_JSON_ENV_KEY_MISMATCH",
+                    message: `auth.json managed env key does not match active provider "${matches[0]}".`,
+                    provider: matches[0],
+                    expectedEnvKey: activeProvider.envKey,
+                    actualEnvKeys: actualKeys,
+                });
+            }
+            if (payload[activeProvider.envKey] !== activeProvider.apiKey) {
+                issues.push({
+                    code: "AUTH_JSON_APIKEY_MISMATCH",
+                    message: `auth.json secret value does not match active provider "${matches[0]}".`,
+                    provider: matches[0],
+                });
+            }
+            if ((0, providers_1.isCopilotBridgeProvider)(activeProvider)) {
+                const installStatus = (0, copilot_installer_1.probeCopilotSdkInstall)();
+                if (!installStatus.installed) {
+                    issues.push({
+                        code: "COPILOT_SDK_MISSING",
+                        message: "The optional Copilot SDK runtime is not installed.",
+                        installDir: installStatus.installDir,
+                        packageName: installStatus.packageName,
+                    });
+                }
+                try {
+                    await (0, copilot_adapter_1.readCopilotAuthState)();
+                }
+                catch (error) {
+                    const normalized = (0, errors_1.normalizeError)(error);
+                    issues.push({
+                        code: normalized.code,
+                        message: normalized.message,
+                        ...(normalized.details ?? {}),
+                    });
+                }
+                const bridge = await (0, copilot_bridge_1.probeCopilotBridgeRuntime)(activeProvider);
+                if (!bridge.ok) {
+                    issues.push({
+                        code: bridge.cause === "Copilot bridge state base URL does not match the provider runtime configuration."
+                            ? "PROVIDER_BASE_URL_MISMATCH"
+                            : "BRIDGE_HEALTHCHECK_FAILED",
+                        message: bridge.cause,
+                        ...(bridge.details ?? {}),
+                    });
+                }
+            }
+        }
+    }
+    // Drift inspection still runs when files are missing so status output can explain partial state.
     const drift = (0, runtime_state_1.inspectLiveStateDrift)(currentProfile, providers);
     const codexCheck = (0, codex_probe_1.probeCodexRuntime)();
     if (!codexCheck.ok) {
@@ -120,10 +197,14 @@ function runDoctor(args) {
             codexDir: args.codexDir,
             storage: (0, runtime_state_1.getStorageRoles)(),
             liveState: drift,
+            auth: authState,
         },
         warnings: issues.length === 0 ? [] : [`doctor found ${issues.length} issue(s)`],
     };
 }
+/**
+ * Maps structured config consistency issues onto stable human-readable diagnostic text.
+ */
 function renderConfigIssueMessage(issue) {
     switch (issue.code) {
         case "ORPHANED_PROFILE_REFERENCE":
@@ -142,7 +223,21 @@ function renderConfigIssueMessage(issue) {
             return `Model provider section "${issue.modelProvider}" for profile "${issue.profile}" is missing from config.toml.`;
         case "MODEL_PROVIDER_BASE_URL_MISSING":
             return `Model provider section "${issue.modelProvider}" for profile "${issue.profile}" is missing base_url.`;
+        case "MODEL_PROVIDER_ENV_KEY_MISSING":
+            return `Model provider section "${issue.modelProvider}" for profile "${issue.profile}" is missing env_key.`;
+        case "PROVIDER_ENV_KEY_MISMATCH":
+            return `Provider "${issue.provider}" envKey does not match runtime env_key for profile "${issue.profile}".`;
+        case "ACTIVE_PROVIDER_UNRESOLVED":
+            return `Active profile "${issue.profile}" maps to multiple providers and cannot determine the current auth mirror owner.`;
+        case "AUTH_JSON_INVALID":
+            return String(issue.message ?? issue.reason ?? "auth.json is invalid.");
+        case "AUTH_JSON_ENV_KEY_MISMATCH":
+            return `auth.json managed env key does not match provider "${String(issue.provider ?? "")}".`;
+        case "AUTH_JSON_APIKEY_MISMATCH":
+            return `auth.json secret does not match provider "${String(issue.provider ?? "")}".`;
         case "DESTRUCTIVE_REMOVE_BLOCKED":
             return `Provider "${issue.provider}" cannot be removed while "${issue.activeProfile}" remains active.`;
+        default:
+            return String(issue.code ?? "UNKNOWN_ISSUE");
     }
 }