@tokensrc/codex 1.13.4 → 1.14.0

package/dist/commands.js

@@ -1,17 +1,37 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { hostname } from "node:os";
+import { join } from "node:path";
 import { getStoragePath, loadAccounts, setStoragePath, setStoragePathDirect } from "codex-multi-auth/storage";
 import { normalizeCodexServiceUrl } from "./client.js";
 import { CodexServiceError } from "./errors.js";
-import { backupCodexFileCredentials, codexFileCredentialsMatchAccount, inspectLocalCodexCredentialStatus, resetManagedCodexFileCredentials, restoreCodexFileCredentials, writeCodexChatgptFileCredentials } from "./credentials.js";
+import { backupCodexFileCredentials, codexFileCredentialsMatchAccount, discardCodexFileCredentialBackup, inspectLocalCodexCredentialStatus, readManagedCodexLineageState, resetManagedCodexFileCredentials, restoreCodexFileCredentials, writeCodexChatgptFileCredentials } from "./credentials.js";
 import { CODEX_DISTRIBUTION_SCHEMA_VERSION } from "./protocol.js";
 import { formatCodexAccountDisplayIdentity, resolveCodexAdminAccount, resolveCodexAccountDisplayName } from "./account-display.js";
 import { loadCodexQuotaUploads } from "./quota-cache.js";
 import { cleanupLegacyCodexProvider } from "./legacy-cleanup.js";
-import { clearCodexSelection, loadCodexSelection, saveCodexSelection } from "./selection.js";
+import { executeCodexEnrollmentLogin } from "./enrollment-flow.js";
+import { executeCodexMigrationLoginBatch } from "./migration-login-batch.js";
+import { executeCodexShortLivedCredentialDelivery } from "./short-lived-delivery-flow.js";
+import { executeManagedCodexV3Login, executeManagedCodexV3Upload, reportManagedCodexV3Credentials } from "./managed-credential-v3-flow.js";
+import { readManagedCodexV3State } from "./managed-credential-v3.js";
+import { profileManagedCredentialsV3Enabled } from "./profile.js";
+import { executeCodexAssignmentRetirementLocalDelete } from "./retirement-flow.js";
+import { clearCodexSelection, loadCodexSelection, rememberCodexSelectionProviderAccount, saveCodexSelection } from "./selection.js";
 import { installCodexShortcuts, removeCodexShortcuts } from "./shortcuts.js";
 import { isCodexAccountAvailable, renderCodexAccountDashboard, selectCodexAccount } from "./tui.js";
+import { readCodexShortLivedDeliveryJournal } from "./short-lived-delivery-journal.js";
+import { superviseCodexShortLivedCredentials } from "./credential-supervisor.js";
 export const NO_AVAILABLE_CHATGPT_ACCOUNT_MESSAGE = "当前用户没有绑定可用的 ChatGPT 账号。请前往 OA 系统提交 IT11 工单，申请独享或共享的 ChatGPT 个人账号。";
+// The Server refreshes a user-bound lineage only inside its final 60-second
+// credential safety window. Asking for a new delivery earlier would merely
+// re-encrypt the same access/ID tokens and must not be treated as a renewal.
+const SERVER_MANAGED_SHORT_LIVED_REFRESH_WINDOW_MS = 60_000;
+const SCHEMA_V2_LEGACY_MANAGEMENT_DISABLED = "schema_v2_legacy_management_disabled";
+export function effectiveCodexCredentialRefreshBefore(requestedMs, serverManagedShortLived) {
+    return serverManagedShortLived
+        ? Math.min(requestedMs, SERVER_MANAGED_SHORT_LIVED_REFRESH_WINDOW_MS)
+        : requestedMs;
+}
 async function json(command, deps) {
     if (command.optsWithGlobals().json)
         return true;
@@ -30,6 +50,27 @@ function success(value) {
 function importFailures(credentials) {
     return credentials.filter(({ status }) => status === "REJECTED" || status === "UNKNOWN");
 }
+function schemaV2LifecycleEnabled(config) {
+    const capabilities = config.profile?.userBoundRefreshTokens;
+    return capabilities?.delivery === true || capabilities?.migrationPlans === true;
+}
+function managedCredentialsV3Enabled(config) {
+    return profileManagedCredentialsV3Enabled(config.profile);
+}
+function codexConfigPathForEnv(env) {
+    const codexHome = env.CODEX_HOME?.trim();
+    return codexHome ? join(codexHome, "config.toml") : undefined;
+}
+function assertLegacyManagementEnabled(config) {
+    if (!schemaV2LifecycleEnabled(config))
+        return;
+    throw new CodexServiceError("Schema-v2 user-bound credentials are enabled; legacy refresh-token pool management is disabled.", SCHEMA_V2_LEGACY_MANAGEMENT_DISABLED, 409);
+}
+function assignmentCredentialStatus(assignment) {
+    if (assignment.deliveryEligible)
+        return "AVAILABLE";
+    return ["NEEDS_REAUTH", "LOST", "DIVERGED", "COMPROMISED"].includes(assignment.lineageStatus ?? "") ? "NEEDS_REAUTH" : "TEMPORARILY_UNAVAILABLE";
+}
 function serviceConnection(options = {}) {
     return {
         ...(options.server ? { serverUrl: options.server } : {}),
@@ -64,15 +105,62 @@ function formatAdminAccount(account) {
     })} (${account.id})`;
 }
 async function loadAccountData(deps, options = {}) {
-    const response = await deps.clientFor(serviceConnection(options)).listAccounts();
     const previous = await loadCodexSelection(deps.config.persistence.configDirectory);
+    if (managedCredentialsV3Enabled(deps.config)) {
+        const v3Assignments = await deps.clientFor(serviceConnection(options)).listV3CredentialAssignments();
+        const accounts = v3Assignments.items.map((assignment) => ({
+            id: assignment.managedAccountId,
+            accountId: assignment.assignmentId,
+            label: assignment.label,
+            isDefault: true,
+            accessExpiresAt: Date.parse(assignment.credentialExpiresAt),
+            credentialStatus: assignment.lineageStatus === "NEEDS_REAUTH"
+                ? "NEEDS_REAUTH"
+                : assignment.authorityMode === "CLIENT_MANAGED" ? "AVAILABLE" : "TEMPORARILY_UNAVAILABLE",
+            lineageStatus: assignment.lineageStatus === "STALE" ? "SYNC_LAGGING" : assignment.lineageStatus,
+            quota: null
+        }));
+        return {
+            response: { schemaVersion: CODEX_DISTRIBUTION_SCHEMA_VERSION, accounts,
+                defaultAccountId: accounts[0]?.id ?? null },
+            selectedAccountId: previous?.account.managedAccountId,
+            v3Assignments
+        };
+    }
+    if (deps.config.profile?.userBoundRefreshTokens?.delivery === true) {
+        const assignments = await deps.clientFor(serviceConnection(options)).listCredentialAssignments();
+        const accounts = assignments.items.map((assignment) => ({
+            id: assignment.managedAccountId,
+            accountId: assignment.assignmentId,
+            label: assignment.label,
+            isDefault: previous?.account.assignmentId === assignment.assignmentId,
+            ...(assignment.credentialExpiresAt
+                ? { accessExpiresAt: Date.parse(assignment.credentialExpiresAt) }
+                : {}),
+            credentialStatus: assignmentCredentialStatus(assignment),
+            lineageStatus: assignment.lineageStatus ?? undefined,
+            quota: null
+        }));
+        return {
+            response: {
+                schemaVersion: CODEX_DISTRIBUTION_SCHEMA_VERSION,
+                accounts,
+                defaultAccountId: previous?.account.managedAccountId ?? null
+            },
+            selectedAccountId: previous?.account.managedAccountId,
+            assignments
+        };
+    }
+    const response = await deps.clientFor(serviceConnection(options)).listAccounts();
     return {
         response,
         selectedAccountId: previous?.account.id ?? response.defaultAccountId ?? undefined
     };
 }
 async function chooseAccount(deps, requested, options = {}) {
-    const { response, selectedAccountId } = await loadAccountData(deps, options);
+    const data = await loadAccountData(deps, options);
+    const { response, selectedAccountId } = data;
+    const previous = await loadCodexSelection(deps.config.persistence.configDirectory);
     const cli = deps.config.branding.cliName === "numa"
         ? "numa codex use"
         : `${deps.config.branding.cliName} use`;
@@ -88,39 +176,240 @@ async function chooseAccount(deps, requested, options = {}) {
         label: account.label,
         providerAccountId: account.accountId
     });
+    const assignment = data.assignments?.items.find((item) => item.managedAccountId === account.id && item.assignmentId === account.accountId);
+    const retainedProviderAccountId = assignment
+        && previous?.account.assignmentId === assignment.assignmentId
+        ? previous.account.providerAccountId
+        : undefined;
+    const v3Assignment = data.v3Assignments?.items.find((item) => item.managedAccountId === account.id && item.assignmentId === account.accountId);
     const selection = await saveCodexSelection(deps.config.persistence.configDirectory, {
         serviceUrl: options.server ?? deps.config.connection.serverUrl,
         allowInsecurePoc: Boolean(options.insecurePoc || options.insecureHttp || deps.config.connection.allowInsecureHttp),
-        account: { id: account.id, accountId: account.accountId, label: accountLabel }
+        account: v3Assignment ? {
+            id: v3Assignment.managedAccountId,
+            accountId: v3Assignment.providerAccountId,
+            label: accountLabel,
+            distributionMode: "CLIENT_MANAGED_V3",
+            assignmentId: v3Assignment.assignmentId,
+            managedAccountId: v3Assignment.managedAccountId,
+            providerAccountId: v3Assignment.providerAccountId
+        } : assignment ? {
+            id: assignment.managedAccountId,
+            label: accountLabel,
+            distributionMode: "SERVER_MANAGED_SHORT_LIVED",
+            assignmentId: assignment.assignmentId,
+            managedAccountId: assignment.managedAccountId,
+            ...(retainedProviderAccountId ? {
+                accountId: retainedProviderAccountId,
+                providerAccountId: retainedProviderAccountId
+            } : {})
+        } : {
+            id: account.id,
+            accountId: account.accountId,
+            label: accountLabel,
+            distributionMode: "SCHEMA_V1"
+        }
     });
     return { account, selection };
 }
-async function installCredentials(deps, accountId, service) {
-    const response = await deps.clientFor(service).getLoginCredentials(accountId);
-    await cleanupLegacyCodexProvider();
-    await backupCodexFileCredentials();
+async function installCredentials(deps, selection, service) {
+    const client = deps.clientFor(service);
+    await cleanupLegacyCodexProvider(codexConfigPathForEnv(deps.env));
+    if (managedCredentialsV3Enabled(deps.config)) {
+        const state = await readManagedCodexV3State(deps.env);
+        if (!state || state.phase !== "INSTALLED" || state.authorityMode !== "CLIENT_MANAGED"
+            || selection.account.distributionMode !== "CLIENT_MANAGED_V3"
+            || selection.account.assignmentId !== state.assignmentId
+            || selection.account.managedAccountId !== state.managedAccountId
+            || selection.account.providerAccountId !== state.providerAccountId) {
+            throw new CodexServiceError("The selected v3 assignment does not match acknowledged local credentials; run `numa codex login` or `numa codex upload`.", "lineage_version_conflict", 409);
+        }
+        const assignments = await client.listV3CredentialAssignments();
+        const current = assignments.items[0];
+        if (!current || current.assignmentId !== state.assignmentId || current.lineageId !== state.lineageId
+            || current.authorityMode !== "CLIENT_MANAGED") {
+            throw new CodexServiceError("The v3 credential assignment is no longer active.", "codex_assignment_not_found", 404);
+        }
+        return { expiresAt: Date.parse(state.credentialExpiresAt), selection };
+    }
+    if (deps.config.profile?.userBoundRefreshTokens?.delivery === true) {
+        await discardCodexFileCredentialBackup(deps.env);
+        if (selection.account.distributionMode !== "SERVER_MANAGED_SHORT_LIVED"
+            || !selection.account.assignmentId || !selection.account.managedAccountId) {
+            throw new CodexServiceError("The saved Codex selection is not a schema-v2 credential assignment.", "codex_assignment_not_found", 404);
+        }
+        const assignments = await client.listCredentialAssignments();
+        const assignment = assignments.items.find((item) => item.assignmentId === selection.account.assignmentId
+            && item.managedAccountId === selection.account.managedAccountId);
+        if (!assignment) {
+            throw new CodexServiceError("The selected schema-v2 credential assignment is no longer active.", "codex_assignment_not_found", 404);
+        }
+        const state = await readManagedCodexLineageState(deps.env);
+        const journal = await readCodexShortLivedDeliveryJournal(deps.env);
+        const recoverable = journal?.tenantId === deps.config.connection.tenantId
+            && journal.assignmentId === assignment.assignmentId
+            || state?.assignmentId === assignment.assignmentId
+                && (state.tenantId === deps.config.connection.tenantId || state.tenantId === null)
+                && (state.phase === "INSTALLING"
+                    || state.phase === "INSTALLED_PENDING_ACK" && Date.parse(state.ackExpiresAt) > Date.now());
+        if (!assignment.deliveryEligible && !recoverable) {
+            throw new CodexServiceError("The selected schema-v2 credential assignment is not ready for delivery.", "short_lived_credential_lineage_not_ready", 409);
+        }
+        const delivered = await executeCodexShortLivedCredentialDelivery({
+            client,
+            tenantId: deps.config.connection.tenantId,
+            assignmentId: assignment.assignmentId,
+            allowNewDelivery: assignment.deliveryEligible,
+            env: deps.env
+        });
+        const updated = await rememberCodexSelectionProviderAccount(deps.config.persistence.configDirectory, assignment.assignmentId, delivered.providerAccountId);
+        return { expiresAt: Date.parse(delivered.credentialExpiresAt), selection: updated };
+    }
+    await backupCodexFileCredentials(deps.env);
+    const response = await client.getLoginCredentials(selection.account.id);
     await writeCodexChatgptFileCredentials({
         accessToken: response.accessToken,
         idToken: response.idToken,
         accountId: response.account.accountId
-    });
-    return { expiresAt: response.expiresAt };
+    }, Date.now(), deps.env);
+    return { expiresAt: response.expiresAt, selection };
 }
 async function selectedCredentials(deps, requested, options = {}) {
+    if (managedCredentialsV3Enabled(deps.config)) {
+        const state = await readManagedCodexV3State(deps.env);
+        if (!state || state.phase !== "INSTALLED" || state.authorityMode !== "CLIENT_MANAGED") {
+            throw new CodexServiceError("No acknowledged v3 Codex credential is installed; run `numa codex login` or `numa codex upload`.", "managed_codex_v3_login_required", 409);
+        }
+        if (requested && ![
+            state.assignmentId,
+            state.managedAccountId,
+            state.providerAccountId,
+            state.lineageId
+        ].includes(requested)) {
+            throw new CodexServiceError("The requested account is not the active v3 lineage.", "codex_account_not_found", 404);
+        }
+        const assignments = await deps.clientFor(serviceConnection(options)).listV3CredentialAssignments();
+        const assignment = assignments.items[0];
+        if (!assignment || assignment.assignmentId !== state.assignmentId
+            || assignment.managedAccountId !== state.managedAccountId
+            || assignment.providerAccountId !== state.providerAccountId
+            || assignment.lineageId !== state.lineageId
+            || assignment.authorityMode !== "CLIENT_MANAGED") {
+            throw new CodexServiceError("The local v3 lineage no longer matches the server assignment.", "lineage_version_conflict", 409);
+        }
+        const selection = await saveCodexSelection(deps.config.persistence.configDirectory, {
+            serviceUrl: options.server ?? deps.config.connection.serverUrl,
+            allowInsecurePoc: Boolean(options.insecurePoc || options.insecureHttp || deps.config.connection.allowInsecureHttp),
+            account: {
+                id: state.managedAccountId,
+                accountId: state.providerAccountId,
+                label: assignment.label,
+                distributionMode: "CLIENT_MANAGED_V3",
+                assignmentId: state.assignmentId,
+                managedAccountId: state.managedAccountId,
+                providerAccountId: state.providerAccountId
+            }
+        });
+        return { selection, expiresAt: Date.parse(state.credentialExpiresAt) };
+    }
     let selection = await loadCodexSelection(deps.config.persistence.configDirectory);
     const currentServiceUrl = options.server ?? deps.config.connection.serverUrl;
     const currentAllowsInsecureHttp = Boolean(options.insecurePoc || options.insecureHttp || deps.config.connection.allowInsecureHttp);
     const serviceChanged = selection !== undefined && !sameServiceUrl(selection.serviceUrl, selection.allowInsecurePoc, currentServiceUrl, currentAllowsInsecureHttp);
-    if (!selection || serviceChanged || options.server || requested && selection.account.id !== requested) {
+    const requestedMatchesSelection = selection !== undefined && requested !== undefined
+        && [
+            selection.account.id,
+            selection.account.accountId,
+            selection.account.assignmentId,
+            selection.account.managedAccountId,
+            selection.account.providerAccountId,
+            selection.account.label
+        ].includes(requested);
+    if (!selection || serviceChanged || requested && !requestedMatchesSelection) {
         selection = (await chooseAccount(deps, requested, options)).selection;
     }
-    if (!(await codexFileCredentialsMatchAccount(selection.account.accountId))) {
-        await installCredentials(deps, selection.account.id, {
+    if (deps.config.profile?.userBoundRefreshTokens?.delivery === true) {
+        if (selection.account.distributionMode !== "SERVER_MANAGED_SHORT_LIVED") {
+            selection = (await chooseAccount(deps, requested, options)).selection;
+        }
+        const assignments = await deps.clientFor({
+            serverUrl: selection.serviceUrl,
+            allowInsecureHttp: selection.allowInsecurePoc
+        }).listCredentialAssignments();
+        const assignment = assignments.items.find((item) => item.assignmentId === selection.account.assignmentId
+            && item.managedAccountId === selection.account.managedAccountId);
+        if (!assignment) {
+            throw new CodexServiceError("The selected schema-v2 credential assignment is no longer active.", "codex_assignment_not_found", 404);
+        }
+        const state = await readManagedCodexLineageState(deps.env);
+        const journal = await readCodexShortLivedDeliveryJournal(deps.env);
+        const stateMatches = state !== undefined
+            && (state.tenantId === deps.config.connection.tenantId || state.tenantId === null)
+            && state.assignmentId === assignment.assignmentId
+            && state.managedAccountId === assignment.managedAccountId;
+        const local = await inspectLocalCodexCredentialStatus(stateMatches ? state.providerAccountId : selection.account.providerAccountId, deps.env);
+        const pending = journal?.tenantId === deps.config.connection.tenantId
+            && journal.assignmentId === assignment.assignmentId
+            || stateMatches && state.phase !== "INSTALLED";
+        if (!assignment.deliveryEligible || !stateMatches || !local.usable
+            || local.matchesExpectedAccount !== true || pending) {
+            return installCredentials(deps, selection, {
+                serverUrl: selection.serviceUrl,
+                allowInsecureHttp: selection.allowInsecurePoc
+            });
+        }
+        const matchingState = state;
+        if (selection.account.providerAccountId !== matchingState.providerAccountId) {
+            selection = await rememberCodexSelectionProviderAccount(deps.config.persistence.configDirectory, assignment.assignmentId, matchingState.providerAccountId);
+        }
+        return { selection, expiresAt: local.expiresAt ?? Date.parse(matchingState.credentialExpiresAt) };
+    }
+    if (!selection.account.accountId) {
+        throw new CodexServiceError("The saved Codex selection has no provider account.", "invalid_configuration");
+    }
+    if (!(await codexFileCredentialsMatchAccount(selection.account.accountId, deps.env))) {
+        return installCredentials(deps, selection, {
             serverUrl: selection.serviceUrl,
             allowInsecureHttp: selection.allowInsecurePoc
         });
     }
-    return selection;
+    const local = await inspectLocalCodexCredentialStatus(selection.account.accountId, deps.env);
+    return { selection, expiresAt: local.expiresAt };
+}
+async function launchWithSelectedCredentials(deps, selected, launch) {
+    if (managedCredentialsV3Enabled(deps.config)) {
+        try {
+            return await launch();
+        }
+        finally {
+            const report = await reportManagedCodexV3Credentials({
+                client: deps.clientFor({
+                    serverUrl: selected.selection.serviceUrl,
+                    allowInsecureHttp: selected.selection.allowInsecurePoc
+                }),
+                tenantId: deps.config.connection.tenantId,
+                env: deps.env
+            });
+            if (!report.reported && report.warningCode) {
+                deps.errorOutput.write(`Codex credential observation deferred (${report.warningCode}); local credentials were not marked invalid.\n`);
+            }
+        }
+    }
+    if (deps.config.profile?.userBoundRefreshTokens?.delivery !== true)
+        return launch();
+    let current = selected;
+    return superviseCodexShortLivedCredentials({
+        initialExpiresAt: current.expiresAt,
+        launch: (signal) => launch(signal),
+        renew: async () => {
+            const installed = await installCredentials(deps, current.selection, {
+                serverUrl: current.selection.serviceUrl,
+                allowInsecureHttp: current.selection.allowInsecurePoc
+            });
+            current = installed;
+            return { expiresAt: installed.expiresAt };
+        }
+    });
 }
 export function registerCodexCommands(program, deps, options = {}) {
     const codex = options.nested === false
@@ -147,21 +436,67 @@ export function registerCodexCommands(program, deps, options = {}) {
             else
                 deps.output.write("Logged out.\n");
         });
+    if (!includeAuthCommands && managedCredentialsV3Enabled(deps.config))
+        serviceOptions(codex.command("login")
+            .description("Run an isolated official Codex login and install client-managed credentials"))
+            .option("--device-auth", "use the official Codex device authorization flow")
+            .action(async (opts, command) => {
+            if (!managedCredentialsV3Enabled(deps.config)) {
+                throw new CodexServiceError("Managed Codex credential v3 is not enabled by the verified platform profile.", "managed_codex_v3_not_enabled", 409);
+            }
+            const result = await executeManagedCodexV3Login({
+                client: deps.clientFor(serviceConnection(opts)),
+                tenantId: deps.config.connection.tenantId,
+                env: deps.env,
+                deviceAuth: opts.deviceAuth
+            });
+            const assignments = await deps.clientFor(serviceConnection(opts)).listV3CredentialAssignments();
+            const assignment = assignments.items.find((item) => item.assignmentId === result.assignmentId);
+            await saveCodexSelection(deps.config.persistence.configDirectory, {
+                serviceUrl: opts.server ?? deps.config.connection.serverUrl,
+                allowInsecurePoc: Boolean(opts.insecurePoc || opts.insecureHttp || deps.config.connection.allowInsecureHttp),
+                account: {
+                    id: result.managedAccountId,
+                    accountId: result.providerAccountId,
+                    label: assignment?.label ?? "Codex account",
+                    distributionMode: "CLIENT_MANAGED_V3",
+                    assignmentId: result.assignmentId,
+                    managedAccountId: result.managedAccountId,
+                    providerAccountId: result.providerAccountId
+                }
+            });
+            const output = {
+                enrollmentId: result.enrollmentId,
+                assignmentId: result.assignmentId,
+                managedAccountId: result.managedAccountId,
+                providerAccountId: result.providerAccountId,
+                lineageId: result.lineageId,
+                generationVersion: result.generationVersion,
+                authorityMode: result.authorityMode,
+                credentialExpiresAt: result.credentialExpiresAt
+            };
+            if (await json(command, deps))
+                print(deps.output, success(output));
+            else
+                deps.output.write(`Codex login installed and acknowledged for ${result.providerAccountId}; generation=${result.generationVersion}.\n`);
+        });
     serviceOptions(codex.command("list").description("List available Codex accounts without downloading credentials"))
         .action(async (opts, command) => {
-        const { response: result, selectedAccountId } = await loadAccountData(deps, opts);
+        const { response: result, selectedAccountId, assignments, v3Assignments } = await loadAccountData(deps, opts);
         const hasAvailableAccount = result.accounts.some(isCodexAccountAvailable);
+        const shouldRequestAccount = result.accounts.length === 0
+            || !hasAvailableAccount && assignments === undefined && v3Assignments === undefined;
         if (await json(command, deps))
             print(deps.output, success({
                 ...result,
-                ...(hasAvailableAccount ? {} : { guidance: { code: "chatgpt_account_request_required", ticket_template: "IT11", message: NO_AVAILABLE_CHATGPT_ACCOUNT_MESSAGE } })
+                ...(shouldRequestAccount ? { guidance: { code: "chatgpt_account_request_required", ticket_template: "IT11", message: NO_AVAILABLE_CHATGPT_ACCOUNT_MESSAGE } } : {})
             }));
         else if (result.accounts.length === 0) {
             deps.output.write(`【需要申请 ChatGPT 账号】\n${NO_AVAILABLE_CHATGPT_ACCOUNT_MESSAGE}\n`);
         }
         else {
             deps.output.write(renderCodexAccountDashboard(result.accounts, selectedAccountId));
-            if (!hasAvailableAccount) {
+            if (shouldRequestAccount) {
                 deps.output.write(`【需要申请 ChatGPT 账号】\n${NO_AVAILABLE_CHATGPT_ACCOUNT_MESSAGE}\n`);
             }
         }
@@ -169,7 +504,7 @@ export function registerCodexCommands(program, deps, options = {}) {
     serviceOptions(codex.command("use [account]").description("Select an account and update the official Codex auth.json"))
         .action(async (account, opts, command) => {
         const result = await chooseAccount(deps, account, opts);
-        await installCredentials(deps, result.account.id, serviceConnection(opts));
+        await installCredentials(deps, result.selection, serviceConnection(opts));
         if (await json(command, deps))
             print(deps.output, success({ account: result.account, auth_mode: "chatgpt" }));
         else
@@ -183,8 +518,8 @@ export function registerCodexCommands(program, deps, options = {}) {
         if (opts.selectAccount)
             await clearCodexSelection(deps.config.persistence.configDirectory);
         const selected = await selectedCredentials(deps, opts.account, opts);
-        deps.errorOutput.write(`Using ChatGPT account: ${selected.account.label} (${selected.account.id})\n`);
-        process.exitCode = await deps.run(args);
+        deps.errorOutput.write(`Using ChatGPT account: ${selected.selection.account.label} (${selected.selection.account.id})\n`);
+        process.exitCode = await launchWithSelectedCredentials(deps, selected, (signal) => deps.run(args, { signal }));
     });
     serviceOptions(codex.command("app [workspace]").description("Validate and launch the official Codex desktop app"))
         .option("-a, --account <id>", "account id")
@@ -195,8 +530,8 @@ export function registerCodexCommands(program, deps, options = {}) {
         if (opts.selectAccount)
             await clearCodexSelection(deps.config.persistence.configDirectory);
         const selected = await selectedCredentials(deps, opts.account, opts);
-        deps.errorOutput.write(`Using ChatGPT account: ${selected.account.label} (${selected.account.id})\n`);
-        process.exitCode = await deps.app(workspace);
+        deps.errorOutput.write(`Using ChatGPT account: ${selected.selection.account.label} (${selected.selection.account.id})\n`);
+        process.exitCode = await launchWithSelectedCredentials(deps, selected, (signal) => deps.app(workspace, { signal }));
     });
     codex.command("status").description("Show selection, desktop app, and official auth.json status")
         .option("--remote", "include remote accounts")
@@ -247,8 +582,10 @@ export function registerCodexCommands(program, deps, options = {}) {
     codex.command("reset").description("Reset selection and managed official credentials")
         .action(async (_options, command) => {
         const selection = await loadCodexSelection(deps.config.persistence.configDirectory);
-        const cleanup = await cleanupLegacyCodexProvider();
-        const auth = await resetManagedCodexFileCredentials(selection?.account.accountId);
+        const cleanup = await cleanupLegacyCodexProvider(codexConfigPathForEnv(deps.env));
+        if (schemaV2LifecycleEnabled(deps.config))
+            await discardCodexFileCredentialBackup(deps.env);
+        const auth = await resetManagedCodexFileCredentials(selection?.account.providerAccountId ?? selection?.account.accountId, deps.env);
         await clearCodexSelection(deps.config.persistence.configDirectory);
         if (await json(command, deps))
             print(deps.output, success({ reset: true, auth_action: auth.action, legacy_provider_removed: cleanup.changed }));
@@ -264,7 +601,8 @@ export function registerCodexCommands(program, deps, options = {}) {
         .option("--replace-login", "confirm replacement")
         .action(async (account, opts, command) => {
         if (opts.restore) {
-            const result = await restoreCodexFileCredentials();
+            assertLegacyManagementEnabled(deps.config);
+            const result = await restoreCodexFileCredentials(deps.env);
             if (await json(command, deps))
                 print(deps.output, success({ action: result.action }));
             else
@@ -275,56 +613,124 @@ export function registerCodexCommands(program, deps, options = {}) {
             throw new Error("auth-agent replaces the current login; add --replace-login to confirm.");
         if (opts.credentialStore !== "file")
             throw new Error("ChatGPT auth.json 同步目前仅支持 --credential-store file。");
-        const selection = (await chooseAccount(deps, account, opts)).selection;
+        if (managedCredentialsV3Enabled(deps.config)) {
+            const interval = Number(opts.interval) * 1_000;
+            if (!Number.isFinite(interval) || interval <= 0)
+                throw new Error("--interval must be positive.");
+            do {
+                const result = await reportManagedCodexV3Credentials({
+                    client: deps.clientFor(serviceConnection(opts)),
+                    tenantId: deps.config.connection.tenantId,
+                    env: deps.env
+                });
+                const event = {
+                    level: result.reported ? "INFO" : "WARN",
+                    event: result.reported ? "credentials.observed" : "credentials.observation_deferred",
+                    at: new Date().toISOString(),
+                    ...(result.generationVersion ? { generationVersion: result.generationVersion } : {}),
+                    ...(result.warningCode ? { warningCode: result.warningCode } : {})
+                };
+                if (await json(command, deps))
+                    print(deps.output, success(event));
+                else
+                    deps.output.write(`${event.at} ${event.level} ${event.event}${result.warningCode ? ` (${result.warningCode})` : ""}\n`);
+                if (opts.once)
+                    break;
+                await new Promise((resolve) => setTimeout(resolve, interval));
+            } while (true);
+            return;
+        }
+        let selected = await selectedCredentials(deps, account, opts);
         const interval = Number(opts.interval) * 1_000;
-        const refreshBefore = Number(opts.refreshBefore) * 1_000;
+        const requestedRefreshBefore = Number(opts.refreshBefore) * 1_000;
         if (!Number.isFinite(interval) || interval <= 0)
             throw new Error("--interval must be positive.");
-        if (!Number.isFinite(refreshBefore) || refreshBefore <= 0)
+        if (!Number.isFinite(requestedRefreshBefore) || requestedRefreshBefore <= 0) {
             throw new Error("--refresh-before must be positive.");
-        const local = await inspectLocalCodexCredentialStatus(selection.account.accountId);
-        let expiresAt = local.state === "installed" && local.matchesExpectedAccount === true
-            ? local.expiresAt
-            : undefined;
+        }
+        const refreshBefore = effectiveCodexCredentialRefreshBefore(requestedRefreshBefore, deps.config.profile?.userBoundRefreshTokens?.delivery === true);
+        let expiresAt = selected.expiresAt;
         do {
             const timestamp = Date.now();
             if (expiresAt === undefined || expiresAt <= timestamp + refreshBefore) {
-                expiresAt = (await installCredentials(deps, selection.account.id, serviceConnection(opts))).expiresAt;
+                selected = await installCredentials(deps, selected.selection, serviceConnection(opts));
+                expiresAt = selected.expiresAt;
                 const event = {
                     level: "INFO",
                     event: "credentials.installed",
                     at: new Date(timestamp).toISOString(),
-                    account: selection.account.id,
+                    account: selected.selection.account.id,
                     expiresAt
                 };
                 if (await json(command, deps))
                     print(deps.output, success(event));
                 else
-                    deps.output.write(`${event.at} INFO credentials.installed ${selection.account.label}\n`);
+                    deps.output.write(`${event.at} INFO credentials.installed ${selected.selection.account.label}\n`);
             }
             else {
                 const event = {
                     level: "INFO",
                     event: "credentials.current",
                     at: new Date(timestamp).toISOString(),
-                    account: selection.account.id,
+                    account: selected.selection.account.id,
                     expiresAt,
                     refreshAt: expiresAt - refreshBefore
                 };
                 if (await json(command, deps))
                     print(deps.output, success(event));
                 else
-                    deps.output.write(`${event.at} INFO credentials.current ${selection.account.label}; refresh not due\n`);
+                    deps.output.write(`${event.at} INFO credentials.current ${selected.selection.account.label}; refresh not due\n`);
             }
             if (opts.once)
                 break;
             await new Promise((resolve) => setTimeout(resolve, interval));
         } while (true);
     });
-    serviceOptions(codex.command("upload").description("Upload the local codex-multi-auth account pool"))
+    serviceOptions(codex.command("upload").description("Enroll official Codex credentials (v3) or upload the legacy local pool"))
         .option("--storage <path>", "account storage path")
         .option("--source <name>", "upload source")
         .action(async (opts, command) => {
+        if (managedCredentialsV3Enabled(deps.config)) {
+            if (opts.storage || opts.source) {
+                throw new CodexServiceError("Managed credential v3 upload reads only the official CODEX_HOME/auth.json.", "invalid_configuration");
+            }
+            const result = await executeManagedCodexV3Upload({
+                client: deps.clientFor(serviceConnection(opts)),
+                tenantId: deps.config.connection.tenantId,
+                env: deps.env
+            });
+            const assignments = await deps.clientFor(serviceConnection(opts)).listV3CredentialAssignments();
+            const assignment = assignments.items.find((item) => item.assignmentId === result.assignmentId);
+            await saveCodexSelection(deps.config.persistence.configDirectory, {
+                serviceUrl: opts.server ?? deps.config.connection.serverUrl,
+                allowInsecurePoc: Boolean(opts.insecurePoc || opts.insecureHttp || deps.config.connection.allowInsecureHttp),
+                account: {
+                    id: result.managedAccountId,
+                    accountId: result.providerAccountId,
+                    label: assignment?.label ?? "Codex account",
+                    distributionMode: "CLIENT_MANAGED_V3",
+                    assignmentId: result.assignmentId,
+                    managedAccountId: result.managedAccountId,
+                    providerAccountId: result.providerAccountId
+                }
+            });
+            const output = {
+                enrollmentId: result.enrollmentId,
+                assignmentId: result.assignmentId,
+                managedAccountId: result.managedAccountId,
+                providerAccountId: result.providerAccountId,
+                lineageId: result.lineageId,
+                generationVersion: result.generationVersion,
+                authorityMode: result.authorityMode,
+                credentialExpiresAt: result.credentialExpiresAt
+            };
+            if (await json(command, deps))
+                print(deps.output, success(output));
+            else
+                deps.output.write(`Official Codex credentials enrolled, installed, and acknowledged; generation=${result.generationVersion}.\n`);
+            return;
+        }
+        assertLegacyManagementEnabled(deps.config);
         if (opts.storage)
             setStoragePathDirect(opts.storage);
         else
@@ -382,6 +788,124 @@ export function registerCodexCommands(program, deps, options = {}) {
         if (failures.length > 0)
             process.exitCode = 1;
     });
+    const enrollment = codex.command("enrollment")
+        .description("Execute administrator-created one-shot Codex login intents");
+    serviceOptions(enrollment.command("status <intent>").description("Show redacted enrollment intent status"))
+        .action(async (intent, opts, command) => {
+        const result = await deps.clientFor(serviceConnection(opts)).getEnrollmentIntent(intent);
+        if (await json(command, deps)) {
+            print(deps.output, { ok: true, ...result });
+            return;
+        }
+        deps.output.write(`${result.intent.id}  ${result.intent.type}  ${result.intent.status}`
+            + `  revision=${result.intent.revision}\n`);
+        deps.output.write(`expires=${result.intent.expiresAt}`
+            + `${result.intent.assignmentId ? `  assignment=${result.intent.assignmentId}` : ""}`
+            + `${result.intent.managedAccountId ? `  account=${result.intent.managedAccountId}` : ""}\n`);
+        if (!result.capabilities.candidateUpload) {
+            deps.output.write("安全候选上传尚未启用；当前任务只能查询或取消，不会启动 OpenAI 登录。\n");
+        }
+    });
+    serviceOptions(enrollment.command("login <intent>")
+        .description("Run one isolated official Codex login for an enrollment intent"))
+        .option("--device-auth", "use the official Codex device authorization flow")
+        .action(async (intent, _opts, command) => {
+        const result = await executeCodexEnrollmentLogin({
+            client: deps.clientFor(serviceConnection(_opts)),
+            tenantId: deps.config.connection.tenantId,
+            intentId: intent,
+            deviceAuth: _opts.deviceAuth
+        });
+        if (await json(command, deps))
+            print(deps.output, { ok: true, ...result });
+        else {
+            deps.output.write(`${result.intent.id} 登录候选已处理；状态=${result.intent.status}`
+                + `${result.result.managedAccountId ? `，账号=${result.result.managedAccountId}` : ""}`
+                + `${result.result.lineageId ? `，lineage=${result.result.lineageId}` : ""}`
+                + "。\n");
+            if (result.result.outcome === "TEMPORARILY_UNAVAILABLE") {
+                deps.output.write("同一进程内的安全重试已耗尽；请取消并新建任务，不能用另一次登录覆盖已保留的候选。\n");
+            }
+        }
+    });
+    serviceOptions(enrollment.command("login-batch <planId>")
+        .description("Sequentially execute isolated logins from a migration plan queue")
+        .option("--device-auth", "use the official Codex device authorization flow")
+        .option("--dry-run", "show the redacted sequential plan without starting login")
+        .option("--page-size <count>", "migration queue page size", "100"))
+        .action(async (planId, opts, command) => {
+        if (deps.config.profile?.userBoundRefreshTokens?.migrationPlans !== true) {
+            throw new CodexServiceError("The selected tenant has not enabled schema-v2 migration login plans.", "capability_not_enabled", 409);
+        }
+        const pageSize = Number(opts.pageSize);
+        if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 100) {
+            throw new CodexServiceError("--page-size must be an integer from 1 to 100.", "invalid_configuration");
+        }
+        const batch = await executeCodexMigrationLoginBatch({
+            client: deps.clientFor(serviceConnection(opts)),
+            tenantId: deps.config.connection.tenantId,
+            planId,
+            deviceAuth: opts.deviceAuth,
+            dryRun: opts.dryRun,
+            pageSize
+        });
+        const failed = batch.counts.failed > 0
+            || ["TARGET_UNCERTAIN", "AUTHENTICATION_ERROR", "SERVICE_ERROR", "LOGIN_ERROR"]
+                .includes(batch.stopReason);
+        if (await json(command, deps)) {
+            print(deps.output, { ok: !failed, ...batch });
+        }
+        else {
+            deps.output.write(`migration=${batch.plan.id} status=${batch.plan.status} revision=${batch.plan.revision}`
+                + ` stop=${batch.stopReason}${batch.dryRun ? " dry-run" : ""}\n`);
+            deps.output.write(`capacity: verifiedMinimum=${batch.capacity.verifiedMinimum}, verifiedLimit=unknown,`
+                + ` sequentialRequired=${batch.capacity.sequentialRequired}; verifiedMinimum 不是上限。\n`);
+            for (const item of batch.items) {
+                deps.output.write(`${item.assignmentId} ${item.action}/${item.status}`
+                    + `${item.intentId ? ` intent=${item.intentId}` : ""}`
+                    + `${item.outcome ? ` outcome=${item.outcome}` : ""}`
+                    + `${item.skipReason ? ` skip=${item.skipReason}` : ""}`
+                    + `${item.safeErrorCode ? ` error=${item.safeErrorCode}` : ""}\n`);
+            }
+            deps.output.write(`summary: attempted=${batch.counts.attempted}, completed=${batch.counts.completed},`
+                + ` failed=${batch.counts.failed}, skipped=${batch.counts.skipped}.\n`);
+        }
+        if (failed)
+            process.exitCode = 1;
+    });
+    serviceOptions(enrollment.command("cancel <intent>").description("Cancel an enrollment intent"))
+        .option("--idempotency-key <key>", "reuse a prior cancellation idempotency key")
+        .action(async (intent, opts, command) => {
+        const client = deps.clientFor(serviceConnection(opts));
+        const current = await client.getEnrollmentIntent(intent);
+        const result = await client.cancelEnrollmentIntent(intent, {
+            idempotencyKey: opts.idempotencyKey?.trim() || randomUUID(),
+            revision: current.intent.revision
+        });
+        if (await json(command, deps))
+            print(deps.output, { ok: true, ...result });
+        else
+            deps.output.write(`${result.intent.id} 已取消；状态=${result.intent.status}。\n`);
+    });
+    const retirement = codex.command("retirement")
+        .description("Remove an exact locally installed lineage for a Server retirement request");
+    serviceOptions(retirement.command("acknowledge <retirement>")
+        .description("Delete the matching managed short-lived credentials and append local evidence")
+        .option("--idempotency-key <key>", "reuse a prior local deletion acknowledgement key"))
+        .action(async (retirementId, opts, command) => {
+        const result = await executeCodexAssignmentRetirementLocalDelete({
+            client: deps.clientFor(serviceConnection(opts)),
+            retirementId,
+            env: deps.env,
+            ...(opts.idempotencyKey?.trim() ? { idempotencyKey: opts.idempotencyKey.trim() } : {})
+        });
+        if (await json(command, deps))
+            print(deps.output, { ok: true, ...result });
+        else
+            deps.output.write(`本机匹配的短效凭据已删除并记录证据；retirement=${result.retirement.id}`
+                + `，revision=${result.retirement.revision}，状态=${result.retirement.status}。\n`
+                + "该证据不代表其他终端已清理；最终退役仍等待全部已披露短效凭据自然过期。\n");
+    });
     const admin = codex.command("admin")
         .description("Administer server-managed Codex accounts and assignments");
     const adminAccounts = admin.command("accounts")
@@ -425,6 +949,7 @@ export function registerCodexCommands(program, deps, options = {}) {
     serviceOptions(adminAccounts.command("refresh <account>")
         .description("Request one server-side refresh-token exchange"))
         .action(async (account, opts, command) => {
+        assertLegacyManagementEnabled(deps.config);
         const client = deps.clientFor(serviceConnection(opts));
         const resolved = await resolveAdminAccount(client, account);
         const result = await client.refreshAdminAccount(resolved.id);
@@ -468,6 +993,7 @@ export function registerCodexCommands(program, deps, options = {}) {
         .description("Bind a ChatGPT/Codex account to a Keycloak user"))
         .option("--default", "make this the user's default Codex account")
         .action(async (account, subject, opts, command) => {
+        assertLegacyManagementEnabled(deps.config);
         const client = deps.clientFor(serviceConnection(opts));
         const resolved = await resolveAdminAccount(client, account);
         const result = await client.bindAdminAssignment({
@@ -484,6 +1010,7 @@ export function registerCodexCommands(program, deps, options = {}) {
     serviceOptions(adminAssignments.command("unbind <assignment>")
         .description("Remove a ChatGPT/Codex account assignment"))
         .action(async (assignment, opts, command) => {
+        assertLegacyManagementEnabled(deps.config);
         const client = deps.clientFor(serviceConnection(opts));
         const assignmentList = await client.listAdminAssignments();
         const target = assignmentList.assignments.find((item) => item.id === assignment);