sneakoscope 10.7.1 → 10.7.2

package/dist/core/codex-lb/desktop-bridge/rejection-log.js

@@ -2,6 +2,58 @@ import { PACKAGE_VERSION } from '../../version.js';
 export const DESKTOP_BRIDGE_LOG_SCHEMA = 'sks.desktop-bridge-log.v2';
 export const REJECTION_LOG_BURST = 5;
 export const REJECTION_LOG_SUMMARY_INTERVAL_MS = 60_000;
+const SHAPE_TOKEN = /^[A-Za-z0-9_.[\]-]{1,64}$/;
+const MAX_SHAPE_KEYS = 64;
+const MAX_SHAPE_INCLUDE = 16;
+const MAX_SHAPE_INPUT_TYPES = 32;
+function shapeToken(value) {
+    return typeof value === 'string' && SHAPE_TOKEN.test(value) ? value : '<other>';
+}
+export function desktopBridgeRequestShape(payload) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+        return null;
+    const request = payload;
+    const inputTypes = {};
+    if (Array.isArray(request.input)) {
+        for (const item of request.input) {
+            const type = item && typeof item === 'object' && !Array.isArray(item) ? shapeToken(item.type) : '<other>';
+            if (inputTypes[type] === undefined && Object.keys(inputTypes).length >= MAX_SHAPE_INPUT_TYPES)
+                continue;
+            inputTypes[type] = (inputTypes[type] ?? 0) + 1;
+        }
+    }
+    else if (typeof request.input === 'string')
+        inputTypes['<text>'] = 1;
+    return {
+        keys: Object.keys(request).map(shapeToken).sort().slice(0, MAX_SHAPE_KEYS),
+        include: Array.isArray(request.include) ? request.include.slice(0, MAX_SHAPE_INCLUDE).map(shapeToken) : null,
+        input_types: inputTypes,
+    };
+}
+function safeRequestShape(shape) {
+    if (!shape || !Array.isArray(shape.keys))
+        return null;
+    const inputTypes = {};
+    for (const [type, count] of Object.entries(shape.input_types ?? {}).slice(0, MAX_SHAPE_INPUT_TYPES)) {
+        if (Number.isSafeInteger(count) && count > 0)
+            inputTypes[shapeToken(type)] = count;
+    }
+    return {
+        keys: shape.keys.slice(0, MAX_SHAPE_KEYS).map(shapeToken),
+        include: Array.isArray(shape.include) ? shape.include.slice(0, MAX_SHAPE_INCLUDE).map(shapeToken) : null,
+        input_types: inputTypes,
+    };
+}
+function safeUpstreamId(value) {
+    const text = String(value ?? '').trim();
+    return /^[A-Za-z0-9_.:-]{1,64}$/.test(text) ? text : null;
+}
+export function safeUpstreamParam(value) {
+    if (typeof value !== 'string')
+        return null;
+    const text = value.slice(0, 64);
+    return /^[A-Za-z0-9_.[\]-]+$/.test(text) ? text : null;
+}
 function safeCatalogId(value) {
     const text = String(value ?? '').replace(/[\r\n\0]/g, '').trim().slice(0, 128);
     return text.length > 0 ? text : null;
@@ -69,6 +121,10 @@ export function createDesktopBridgeRejectionLogger(options = {}) {
         const method = safeMethod(event.method);
         const providerId = safeCatalogId(event.provider_id);
         const publicModel = safeCatalogId(event.public_model);
+        const upstreamCode = safeUpstreamId(event.upstream_code);
+        const upstreamType = safeUpstreamId(event.upstream_type);
+        const upstreamParam = safeUpstreamParam(event.upstream_param);
+        const requestShape = safeRequestShape(event.request_shape);
         emit({
             event: 'sks.desktop_bridge.rejected',
             code,
@@ -81,6 +137,11 @@ export function createDesktopBridgeRejectionLogger(options = {}) {
             ...(Number.isSafeInteger(event.max_request_body_bytes) && event.max_request_body_bytes > 0 ? { max_request_body_bytes: event.max_request_body_bytes } : {}),
             ...(Number.isSafeInteger(event.request_body_bytes) && event.request_body_bytes >= 0 ? { request_body_bytes: event.request_body_bytes } : {}),
             ...(event.request_body_stage === 'encoded' || event.request_body_stage === 'decoded' ? { request_body_stage: event.request_body_stage } : {}),
+            ...(Number.isInteger(event.upstream_status) && event.upstream_status >= 100 && event.upstream_status <= 599 ? { upstream_status: event.upstream_status } : {}),
+            ...(upstreamCode ? { upstream_code: upstreamCode } : {}),
+            ...(upstreamType ? { upstream_type: upstreamType } : {}),
+            ...(upstreamParam ? { upstream_param: upstreamParam } : {}),
+            ...(requestShape ? { request_shape: requestShape } : {}),
         });
     };
 }

package/dist/core/codex-lb/desktop-bridge/responses-websocket.js

@@ -3,14 +3,16 @@ import tls from 'node:tls';
 import WebSocket, { WebSocketServer } from 'ws';
 import { BRIDGE_OFFICIAL_ROUTE_ID, BRIDGE_REMOTE_COMPACTION } from '../bridge-contracts.js';
 import { buildOfficialPassthroughWebSocketHeaders, buildProviderWebSocketHeaders } from './header-policy.js';
-import { createDesktopBridgeRejectionLogger } from './rejection-log.js';
+import { createDesktopBridgeRejectionLogger, desktopBridgeRequestShape } from './rejection-log.js';
+import { adaptRequestForRoute, logRequestAdaptation, providerExtraInclude } from './provider-request-compat.js';
 import { assertDesktopBridgeRouteContext, ensureDesktopBridgeRemoteTarget, isUnreachableUpstreamError, refreshDesktopBridgeRemoteTarget, resolveAndBindDesktopBridgeRouteContext, resolveCodexSessionIdentity, resolveDesktopBridgeTarget, safeBridgeErrorCode, threadRouteMove } from './security.js';
 import { admitCodexLbTurnState } from './codex-lb-turn-state.js';
 import { ProviderHandoffRefusedError, assertProviderHandoffAllowed, providerHandoffRefusedEvent, stripProviderBoundItems, } from './provider-handoff.js';
 import { DEFAULT_DESKTOP_BRIDGE_MAX_REQUEST_BODY_BYTES, DesktopBridgeError } from './types.js';
-import { buildCompactionSummaryRequest, compactionCreatedEvent, compactionFailedEvent, compactionResponseEvents, expandBridgeCompactionItems, newCompactionResponseId, parseProviderSummary, requestsRemoteCompaction, ResponsesContinuationChain, summaryFailure, summaryWithinBounds, } from './compaction-adapter.js';
+import { buildCompactionSummaryRequest, compactionCreatedEvent, compactionFailedEvent, compactionResponseEvents, expandBridgeCompactionItems, newCompactionResponseId, parseProviderSummary, requestsRemoteCompaction, ResponsesContinuationChain, safeUpstreamErrorId, summaryFailure, summaryWithinBounds, } from './compaction-adapter.js';
 import { requestProviderCompactionSummary } from './http-forward.js';
 import { modelCapacityAdvisedFrame } from './capacity-retry-advice.js';
+import { desktopBridgeModelsEtag, frameWithModelsEtag } from './models-endpoint.js';
 const MAX_PENDING_MESSAGES = 256;
 const CLOSE_GRACE_MS = 1_000;
 const INITIAL_CREATE_TIMEOUT_MS = 60 * 60_000;
@@ -22,6 +24,25 @@ export function isResponsesWebSocketRequest(req) {
 function bytes(data) {
     return Buffer.isBuffer(data) ? data : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
 }
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function upstreamFailureEvent(frame) {
+    if (!frame.includes('"response.failed"') && !frame.includes('"type":"error"') && !frame.includes('"type": "error"'))
+        return null;
+    let event;
+    try {
+        event = JSON.parse(frame.toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(event) || (event.type !== 'error' && event.type !== 'response.failed'))
+        return null;
+    const error = event.type === 'error' ? event.error : isRecord(event.response) ? event.response.error : null;
+    const record = isRecord(error) ? error : {};
+    return { status: typeof event.status === 'number' ? event.status : undefined, code: record.code, type: record.type, param: record.param };
+}
 function withLineage(identity, next) {
     return {
         ...identity,
@@ -34,6 +55,7 @@ export function forwardResponsesWebSocket(req, socket, head, config) {
     const upgradeIdentity = resolveCodexSessionIdentity(req.headers);
     const maxBytes = config.maxRequestBodyBytes ?? DEFAULT_DESKTOP_BRIDGE_MAX_REQUEST_BODY_BYTES;
     const server = new WebSocketServer({ noServer: true, clientTracking: false, perMessageDeflate: false, maxPayload: maxBytes });
+    const modelsEtag = config.modelsCatalog ? desktopBridgeModelsEtag(config.modelsCatalog.generation) : null;
     try {
         server.handleUpgrade(req, socket, head, (client) => {
             bridge(client);
@@ -52,6 +74,7 @@ export function forwardResponsesWebSocket(req, socket, head, config) {
         let boundCredentialGeneration = null;
         let boundCredentialFingerprint = null;
         let routedModel = null;
+        let routedShape = null;
         let stopped = false;
         let processing = false;
         let pendingBytes = 0;
@@ -150,12 +173,19 @@ export function forwardResponsesWebSocket(req, socket, head, config) {
             let rewritten = expandBridgeCompactionItems(create);
             if (route.session_pin?.handoff_from && stripProviderBoundItems(create, Boolean(move)))
                 rewritten = true;
+            const adapted = adaptRequestForRoute(create, route, providerExtraInclude(config, route));
+            if (adapted.length) {
+                rewritten = true;
+                logRequestAdaptation(config, route, adapted, 'websocket');
+            }
             if (BRIDGE_REMOTE_COMPACTION[route.provider_id] === 'bridge_summary' && requestsRemoteCompaction(create)) {
                 message.compaction = create;
                 return;
             }
-            if (route.upstream_model !== model || rewritten)
+            if (route.upstream_model !== model || rewritten) {
                 message.data = Buffer.from(JSON.stringify(create));
+                message.binary = false;
+            }
             message.routed = create;
         }
         function refuseMove(message, error) {
@@ -181,7 +211,9 @@ export function forwardResponsesWebSocket(req, socket, head, config) {
                 send(compactionFailedEvent(responseId, route.public_model, 'bridge_compaction_history_unavailable'));
                 return;
             }
-            const body = Buffer.from(JSON.stringify(buildCompactionSummaryRequest({ ...create, input }, route.upstream_model)));
+            const summaryRequest = buildCompactionSummaryRequest({ ...create, input }, route.upstream_model);
+            adaptRequestForRoute(summaryRequest, route, providerExtraInclude(config, route));
+            const body = Buffer.from(JSON.stringify(summaryRequest));
             let accepted = false;
             try {
                 const call = await requestProviderCompactionSummary(config, { provider, credential, clientHeaders: req.headers, requestUrl: req.url || '/' }, body, () => {
@@ -282,6 +314,20 @@ export function forwardResponsesWebSocket(req, socket, head, config) {
                     frame = advised;
                     logRejection({ code: 'bridge_upstream_model_capacity_retry_advised', transport: 'websocket', provider_id: route.provider_id, public_model: routedModel ?? route.public_model, ...(req.url ? { url: req.url } : {}) });
                 }
+                const advertised = modelsEtag && !binary ? frameWithModelsEtag(frame, modelsEtag) : null;
+                if (advertised)
+                    frame = advertised;
+                const failure = binary ? null : upstreamFailureEvent(frame);
+                if (failure) {
+                    logRejection({
+                        code: 'bridge_upstream_request_rejected', transport: 'websocket',
+                        ...(failure.status === undefined ? {} : { status: failure.status, upstream_status: failure.status }),
+                        provider_id: route.provider_id, public_model: routedModel ?? route.public_model,
+                        upstream_code: safeUpstreamErrorId(failure.code), upstream_type: safeUpstreamErrorId(failure.type),
+                        upstream_param: typeof failure.param === 'string' ? failure.param : null,
+                        request_shape: routedShape, ...(req.url ? { url: req.url } : {}),
+                    });
+                }
                 if (summarizes)
                     chain.received(frame);
                 try {
@@ -350,6 +396,8 @@ export function forwardResponsesWebSocket(req, socket, head, config) {
                         await answerCompaction(message.compaction);
                     else {
                         relay(upstream, message.data, message.binary);
+                        if (message.routed)
+                            routedShape = desktopBridgeRequestShape(message.routed);
                         if (message.routed && bound && BRIDGE_REMOTE_COMPACTION[bound.provider_id] === 'bridge_summary')
                             chain.sent(message.routed, message.data);
                     }

package/dist/core/codex-lb/desktop-bridge/server.js

@@ -11,6 +11,7 @@ import { ProviderHandoffRefusedError, providerHandoffRefusalBody } from './provi
 import { PACKAGE_VERSION } from '../../version.js';
 import { DESKTOP_BRIDGE_CLIENT_PATH_PREFIX, DESKTOP_BRIDGE_DIAGNOSTIC_HEALTH_PATH, DESKTOP_BRIDGE_DIAGNOSTIC_PATH, DESKTOP_BRIDGE_DIAGNOSTIC_PROTOCOL, DESKTOP_BRIDGE_IMAGEGEN_PATH } from './types.js';
 import { handleDesktopBridgeImagegen } from './imagegen-endpoint.js';
+import { answerDesktopBridgeModels, isDesktopBridgeModelsRequest } from './models-endpoint.js';
 import { forwardWebSocket, safeEndUpgradeSocket } from './websocket-forward.js';
 function authenticateDesktopBridgeClient(req, input) {
     const raw = String(req.url || '/');
@@ -270,6 +271,10 @@ export async function startPreparedDesktopBridge(input, options = {}) {
                     return;
                 }
                 assertAllowedPath(authenticated.pathname, input.allowedPathPrefixes);
+                if (input.modelsCatalog && isDesktopBridgeModelsRequest(req, authenticated.pathname)) {
+                    answerDesktopBridgeModels(req, res, input.modelsCatalog);
+                    return;
+                }
                 const prepared = await prepareDesktopBridgeRequest(req, input);
                 await forwardHttp(req, res, input, prepared, `${desktopBridgeListenOrigin(input)}${authenticated.clientBasePath}`);
             }

package/dist/core/codex-lb/desktop-bridge-migration/historical-config.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { DESKTOP_BRIDGE_MANAGED_BASE_URL_MARKER, DESKTOP_BRIDGE_MANAGED_MARKER, DESKTOP_BRIDGE_MANAGED_MODEL_CATALOG_MARKER } from '../../../cli/install-helpers-codex-lb-config.js';
+import { DESKTOP_BRIDGE_MANAGED_BASE_URL_MARKER, DESKTOP_BRIDGE_MANAGED_MARKER } from '../../../cli/install-helpers-codex-lb-config.js';
 import { escapeRegExp } from '../../text/regex.js';
 import { CANONICAL_OPENROUTER_ENDPOINT, HISTORICAL_DESKTOP_BRIDGE_MARKER, HISTORICAL_DESKTOP_COMPAT_MARKER, HISTORICAL_MODEL_CATALOG_MARKER, HISTORICAL_OAUTH_SELECTION_MARKER, HISTORICAL_OPENAI_ROUTING_MARKER, HISTORICAL_PROVIDER_MODE_MARKER, HISTORICAL_PROVIDER_SELECTION_MARKER, hasTomlTable, hasTopLevelMarker, isHistoricalProviderMode, secretFreeProviderEndpoint, tomlTableBoolean, tomlTableContainsCustomHeader, tomlTableString, topLevelTomlString } from './historical-toml.js';
 export function inspectHistoricalDesktopBridgeIntent(configText) {
@@ -122,11 +122,7 @@ export function inspectHistoricalDesktopBridgeIntent(configText) {
 }
 export function prepareHistoricalConfigForDesktopBridgeWriter(text, state) {
     const source = String(text || '');
-    if ([
-        DESKTOP_BRIDGE_MANAGED_MARKER,
-        DESKTOP_BRIDGE_MANAGED_BASE_URL_MARKER,
-        DESKTOP_BRIDGE_MANAGED_MODEL_CATALOG_MARKER
-    ].every((marker) => hasTopLevelMarker(source, marker)))
+    if ([DESKTOP_BRIDGE_MANAGED_MARKER, DESKTOP_BRIDGE_MANAGED_BASE_URL_MARKER].every((marker) => hasTopLevelMarker(source, marker)))
         return source;
     const historicalMarkers = historicalManagedMarkers();
     const hasHistoricalMarker = historicalMarkers.some((marker) => hasTopLevelMarker(source, marker));

package/dist/core/codex-lb/desktop-bridge-migration.js

@@ -55,7 +55,8 @@ async function migrateDesktopBridgeConfigUnlocked(input) {
         const migrationInputConfig = prepareHistoricalConfigForDesktopBridgeWriter(currentConfig, historicalState);
         nextConfig = upsertDesktopBridgeManagedConfig(migrationInputConfig, {
             bridgeBaseUrl: input.bridgeBaseUrl,
-            combinedCatalogPath
+            combinedCatalogPath,
+            bindModelCatalog: input.bindModelCatalog !== false
         });
         validateMetadataUpdates(input.metadataUpdates || [], { home, configPath, authPath });
     }
@@ -74,6 +75,17 @@ async function migrateDesktopBridgeConfigUnlocked(input) {
             error: message
         };
     }
+    if (input.configWrite === 'forbid' && nextConfig !== currentConfig) {
+        return {
+            ...baseResult,
+            ok: false,
+            status: 'blocked',
+            managed_runtime: null,
+            receipt_path: null,
+            auth_semantic_identity_preserved: true,
+            blockers: ['desktop_bridge_config_write_deferred']
+        };
+    }
     const metadataUpdates = normalizedMetadataUpdates(input.metadataUpdates || []);
     const metadataAlreadyCurrent = await Promise.all(metadataUpdates.map(async (update) => {
         const currentSha = await fileSha256OrMissing(update.path);
@@ -82,7 +94,7 @@ async function migrateDesktopBridgeConfigUnlocked(input) {
     const hasUnifiedMarkers = [
         DESKTOP_BRIDGE_MANAGED_MARKER,
         DESKTOP_BRIDGE_MANAGED_BASE_URL_MARKER,
-        DESKTOP_BRIDGE_MANAGED_MODEL_CATALOG_MARKER
+        ...(input.bindModelCatalog === false ? [] : [DESKTOP_BRIDGE_MANAGED_MODEL_CATALOG_MARKER])
     ].every((marker) => hasTopLevelMarker(currentConfig, marker));
     if (nextConfig === currentConfig && hasUnifiedMarkers && metadataAlreadyCurrent.every(Boolean)) {
         const authAfter = await captureCodexAuthSnapshot({ home, authPath });

package/dist/core/codex-lb/desktop-controller-v3/catalog.js

@@ -1,5 +1,5 @@
 import { readText, writeJsonAtomic } from '../../fsx.js';
-import { repairManagedCodexLbClientSelection } from '../../../cli/install-helpers-codex-lb-config.js';
+import { codexReadsBridgeModels, hasUserOwnedModelCatalog, repairManagedCodexLbClientSelection } from '../../../cli/install-helpers-codex-lb-config.js';
 import { safeWriteCodexConfigToml } from '../../codex-runtime/codex-desktop-config-policy.js';
 import { readTopLevelTomlString } from '../../codex-app/codex-model-catalog.js';
 import { codexRestartBlockers, maybeRestartRunningCodexApp } from '../../codex-app/codex-app-restart-policy.js';
@@ -18,6 +18,7 @@ import { sha256Stable } from '../route-index.js';
 import { bridgeBaseUrl, commandResult, controllerEnv, controllerPaths, nowIso, providerCode, providerRegistrySnapshot, resolveRawCredentials, resolveValidatedCredentials, safeCode, serializedSettings, stringArray, timeoutMs, unique } from './shared.js';
 import { desktopBridgeStatusV3 } from './status.js';
 import { openRouterOnlyExposure, readControllerOpenRouterOnlyState, withoutCodexLbCatalog } from './openrouter-only-catalog.js';
+import { MODEL_REFRESH_RECOVERY_COMMAND, alignCodexModelSource, bridgeServesModels, listedModelSlugs, modelListDiff, modelRefreshLine, readModelRefreshState, refreshedRecently, writeModelRefreshState } from './model-refresh.js';
 export async function syncCatalog(options) {
     const result = await syncCatalogInternal(options);
     const status = await desktopBridgeStatusV3(options);
@@ -36,10 +37,11 @@ async function repairCodexLbClientSelection(configPath) {
 }
 export async function syncCatalogInternal(options, behavior = {}) {
     const paths = controllerPaths(options);
-    const repair = await repairCodexLbClientSelection(paths.configPath);
+    const repair = behavior.configWrites === false ? null : await repairCodexLbClientSelection(paths.configPath);
     if (repair)
         return blockedSync(inspectHistoricalDesktopBridgeIntent(''), [repair]);
-    const historicalIntent = inspectHistoricalDesktopBridgeIntent(await readText(paths.configPath, ''));
+    const configText = await readText(paths.configPath, '');
+    const historicalIntent = inspectHistoricalDesktopBridgeIntent(configText);
     if (historicalIntent.blockers.length > 0)
         return blockedSync(historicalIntent, historicalIntent.blockers);
     const rawCredentials = await resolveRawCredentials(options, paths);
@@ -68,6 +70,10 @@ export async function syncCatalogInternal(options, behavior = {}) {
         ? openRouterOnlyExposure(selection, openRouterOnly, await readText(paths.configPath, ''))
         : selection;
     const build = buildCombinedBridgeCatalog(catalogRegistry(registry), { catalogs, created_at: nowIso(options), selection: exposure });
+    const lost = providersLostToFailedFetch(await readActiveCombinedBridgeCatalog(paths.catalogPath, paths.routeIndexPath), catalogs, catalogRegistry(registry));
+    if (lost.length > 0) {
+        return { ...blockedSync(historicalIntent, lost.map((providerId) => `${providerCode(providerId)}_catalog_refresh_failed`)), build, active_generation_preserved: true };
+    }
     if (!selectionState.stored)
         await writeBridgeModelSelection(paths.home, selection).catch(() => undefined);
     await writeJsonAtomic(bridgeAvailableModelsPath(paths.home), {
@@ -139,6 +145,8 @@ export async function syncCatalogInternal(options, behavior = {}) {
         receiptDir: paths.receiptDir,
         bridgeBaseUrl: managedBridgeBaseUrl,
         combinedCatalogPath: staging.catalog_path,
+        bindModelCatalog: !codexReadsBridgeModels(configText) && !hasUserOwnedModelCatalog(configText),
+        configWrite: behavior.configWrites === false ? 'forbid' : 'allow',
         newCatalogGeneration: build.catalog.generation,
         metadataUpdates: [
             {
@@ -316,6 +324,20 @@ function emptyProviderCatalog(providerId, state, checkedAt, blockers) {
         warnings: []
     };
 }
+function providersLostToFailedFetch(active, catalogs, registry) {
+    if (!active.ok)
+        return [];
+    return ['codex-lb', 'openrouter'].filter((providerId) => {
+        const blockers = catalogs[providerId].blockers || [];
+        return registry.profiles[providerId].enabled
+            && catalogs[providerId].state === 'failed'
+            && !blockers.some(refusesCredential)
+            && active.catalog.models.some((model) => model.provider_id === providerId);
+    });
+}
+function refusesCredential(blocker) {
+    return /unauthorized|credential_missing|key_missing|invalid_key|_http_40[13]\b/.test(blocker);
+}
 function validationFailureState(blockers) {
     return blockers.some((blocker) => /(?:401|403|auth|rejected|invalid_key|unauthorized)/i.test(blocker))
         ? 'rejected' : 'unavailable';
@@ -362,12 +384,14 @@ export async function selectExposedModels(publicIds, options) {
         updated_at: nowIso(options),
         openrouter: { mode: 'selected', public_ids: requested }
     });
-    const sync = await syncCatalogInternal(options);
+    const sync = await syncAsRefresh(options, 'models.select');
     const status = await desktopBridgeStatusV3(options);
     const activation = sync.activation && typeof sync.activation === 'object'
         ? sync.activation
         : {};
-    const changed = before.selection.openrouter.public_ids.join('\0') !== requested.join('\0');
+    const refresh = sync.model_refresh;
+    const changed = before.selection.openrouter.public_ids.join('\0') !== requested.join('\0')
+        && (refresh.codex_model_source !== 'bridge_models' || refresh.restart_codex_required);
     const restart = sync.ok === true
         ? await maybeRestartRunningCodexApp({
             env: controllerEnv(options),
@@ -387,3 +411,88 @@ function seedSelectionFromConfiguredModel(selection, configText) {
         return selection;
     return { ...selection, openrouter: { mode: 'selected', public_ids: [configured] } };
 }
+export async function refreshModelCatalog(options, input) {
+    const paths = controllerPaths(options);
+    const refreshedAt = nowIso(options);
+    const base = {
+        schema: 'sks.bridge-model-refresh.v1',
+        reason: input.reason,
+        refreshed_at: refreshedAt,
+        added: [],
+        removed: [],
+        restart_codex_required: false
+    };
+    try {
+        const registryGeneration = (await resolveBridgeProviderRegistry({
+            home: paths.home,
+            credentials: await resolveRawCredentials(options, paths)
+        })).generation;
+        const recent = input.force ? null : await readModelRefreshState(paths.home);
+        if (recent && refreshedRecently(recent, registryGeneration, Date.parse(refreshedAt))) {
+            return {
+                ...base, ok: true, skipped: true, generation: recent.generation, total: recent.total, codex_model_source: null,
+                line: `Model list refreshed recently: ${recent.total} models generation ${recent.generation.slice(0, 8)}`,
+                warnings: ['model_refresh_skipped_recent'], blockers: [], sync: null
+            };
+        }
+        const before = await readActiveCombinedBridgeCatalog(paths.catalogPath, paths.routeIndexPath);
+        const sync = await syncCatalogInternal(options, { ...(input.behavior || {}), configWrites: input.allowConfigWrites });
+        if (sync.ok !== true)
+            return refreshFailed(base, stringArray(sync.activation?.blockers), sync);
+        const build = sync.build;
+        const activation = sync.activation;
+        const diff = modelListDiff(listedModelSlugs(before.ok ? before.catalog : null), listedModelSlugs(build.catalog));
+        const source = await alignCodexModelSource({
+            home: paths.home,
+            configPath: paths.configPath,
+            authPath: paths.authPath,
+            catalog: build.catalog,
+            catalogPath: typeof activation.catalog_path === 'string' ? activation.catalog_path : null,
+            allowConfigWrites: input.allowConfigWrites,
+            selfCheck: options.modelsSelfCheckImpl || bridgeServesModels
+        });
+        const restart = source.changed || (source.source === 'model_catalog_json' && diff.added.length + diff.removed.length > 0);
+        const total = listedModelSlugs(build.catalog).length;
+        await writeModelRefreshState(paths.home, {
+            refreshed_at: refreshedAt,
+            provider_registry_generation: registryGeneration,
+            generation: build.catalog.generation,
+            total
+        }).catch(() => undefined);
+        return {
+            ...base, ok: true, skipped: false, generation: build.catalog.generation, total, added: diff.added, removed: diff.removed,
+            codex_model_source: source.source, restart_codex_required: restart,
+            line: modelRefreshLine({ total, added: diff.added.length, removed: diff.removed.length, generation: build.catalog.generation, restartCodex: restart }),
+            warnings: source.warnings, blockers: [], sync
+        };
+    }
+    catch (error) {
+        return refreshFailed(base, [safeCode(error, 'model_refresh_failed')], null);
+    }
+}
+function refreshFailed(base, blockers, sync) {
+    return {
+        ...base, ok: false, skipped: false, generation: null, total: 0, codex_model_source: null,
+        line: `Model list refresh failed; the previous list stays active. Run \`${MODEL_REFRESH_RECOVERY_COMMAND}\` to retry.`,
+        warnings: [`model_refresh_failed: run \`${MODEL_REFRESH_RECOVERY_COMMAND}\``],
+        blockers: unique(blockers.length > 0 ? blockers : ['model_refresh_failed']),
+        sync
+    };
+}
+export async function refreshModels(request, options) {
+    const refresh = await refreshModelCatalog(options, {
+        reason: request.reason || 'cli',
+        force: request.force !== false,
+        allowConfigWrites: request.allow_config_writes !== false
+    });
+    const { sync, ...model_refresh } = refresh;
+    const status = await desktopBridgeStatusV3(options);
+    return commandResult('models.refresh', refresh.ok, status, { model_refresh, catalog_sync: sync }, refresh.blockers, options);
+}
+export async function syncAsRefresh(options, reason, behavior = {}) {
+    const { sync, ...model_refresh } = await refreshModelCatalog(options, { reason, force: true, allowConfigWrites: true, behavior });
+    return {
+        ...(sync ?? blockedSync(null, model_refresh.blockers)),
+        model_refresh
+    };
+}

package/dist/core/codex-lb/desktop-controller-v3/model-refresh.js

@@ -0,0 +1,140 @@
+import http from 'node:http';
+import path from 'node:path';
+import { readText, writeJsonAtomic } from '../../fsx.js';
+import { safeWriteCodexConfigToml } from '../../codex-runtime/codex-desktop-config-policy.js';
+import { readTopLevelTomlString } from '../../codex-app/codex-model-catalog.js';
+import { codexReadsBridgeModels, hasUserOwnedModelCatalog, setDesktopBridgeManagedModelCatalog } from '../../../cli/install-helpers-codex-lb-config.js';
+import { captureCodexAuthSnapshot } from '../desktop-auth-invariant.js';
+import { desktopBridgeModelsEtag } from '../desktop-bridge/models-endpoint.js';
+export const MODEL_REFRESH_STATE_SCHEMA = 'sks.bridge-model-refresh-state.v1';
+export const MODEL_REFRESH_DEBOUNCE_MS = 60_000;
+export const MODEL_REFRESH_RECOVERY_COMMAND = 'sks bridge models refresh';
+export function modelRefreshStatePath(home) {
+    return path.join(path.resolve(home), '.codex', 'sks', 'sks-bridge-model-refresh.json');
+}
+export async function readModelRefreshState(home) {
+    try {
+        const parsed = JSON.parse(await readText(modelRefreshStatePath(home), ''));
+        return parsed?.schema === MODEL_REFRESH_STATE_SCHEMA && typeof parsed.refreshed_at === 'string'
+            && typeof parsed.provider_registry_generation === 'string' && typeof parsed.generation === 'string'
+            && Number.isSafeInteger(parsed.total)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeModelRefreshState(home, state) {
+    await writeJsonAtomic(modelRefreshStatePath(home), { schema: MODEL_REFRESH_STATE_SCHEMA, ...state }, { mode: 0o600 });
+}
+export function refreshedRecently(state, registryGeneration, nowMs) {
+    if (!state || state.provider_registry_generation !== registryGeneration)
+        return false;
+    const age = nowMs - Date.parse(state.refreshed_at);
+    return Number.isFinite(age) && age >= 0 && age < MODEL_REFRESH_DEBOUNCE_MS;
+}
+export function listedModelSlugs(catalog) {
+    if (!catalog)
+        return [];
+    return [...new Set(catalog.models
+            .filter((model) => !/^hid(?:e|den)$/i.test(String(model.visibility || 'list')))
+            .map((model) => String(model.slug || ''))
+            .filter(Boolean))].sort();
+}
+export function modelListDiff(before, after) {
+    const was = new Set(before);
+    const is = new Set(after);
+    return { added: after.filter((slug) => !was.has(slug)), removed: before.filter((slug) => !is.has(slug)) };
+}
+export function modelRefreshLine(input) {
+    const line = `Model list refreshed: ${input.total} models (+${input.added} −${input.removed}) generation ${input.generation.slice(0, 8)}`;
+    return input.restartCodex ? `${line}. Restart Codex to see the new model list.` : line;
+}
+export async function bridgeServesModels(baseUrl, catalog, options = {}) {
+    const expected = desktopBridgeModelsEtag(catalog.generation);
+    let failure = 'bridge_models_self_check_unreachable';
+    for (let attempt = 0; attempt < (options.attempts ?? 3); attempt += 1) {
+        if (attempt > 0)
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        failure = await new Promise((resolve) => {
+            let url;
+            try {
+                url = new URL(`${baseUrl.replace(/\/+$/, '')}/models`);
+            }
+            catch {
+                resolve('bridge_models_self_check_url_invalid');
+                return;
+            }
+            if (url.protocol !== 'http:' || !['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)) {
+                resolve('bridge_models_self_check_not_loopback');
+                return;
+            }
+            const request = http.get(url, { timeout: options.timeoutMs ?? 3_000 }, (response) => {
+                const chunks = [];
+                response.on('data', (chunk) => chunks.push(chunk));
+                response.once('end', () => {
+                    if (response.statusCode !== 200) {
+                        resolve(`bridge_models_self_check_status_${response.statusCode}`);
+                        return;
+                    }
+                    if (response.headers.etag !== expected) {
+                        resolve('bridge_models_self_check_generation_mismatch');
+                        return;
+                    }
+                    try {
+                        const models = JSON.parse(Buffer.concat(chunks).toString('utf8')).models;
+                        resolve(Array.isArray(models) && models.length === catalog.models.length ? null : 'bridge_models_self_check_rows_mismatch');
+                    }
+                    catch {
+                        resolve('bridge_models_self_check_body_invalid');
+                    }
+                });
+                response.once('error', () => resolve('bridge_models_self_check_unreachable'));
+            });
+            request.once('timeout', () => request.destroy());
+            request.once('error', () => resolve('bridge_models_self_check_unreachable'));
+        });
+        if (failure === null)
+            return null;
+    }
+    return failure;
+}
+export async function alignCodexModelSource(input) {
+    const current = await readText(input.configPath, '');
+    if (hasUserOwnedModelCatalog(current)) {
+        return { source: 'user_model_catalog_json', changed: false, warnings: ['codex_model_list_pinned_by_user_model_catalog_json'] };
+    }
+    const baseUrl = readTopLevelTomlString(current, 'openai_base_url');
+    if (!baseUrl || (!codexReadsBridgeModels(current) && !readTopLevelTomlString(current, 'model_catalog_json'))) {
+        return { source: 'not_managed', changed: false, warnings: [] };
+    }
+    const auth = await captureCodexAuthSnapshot({ home: input.home, authPath: input.authPath }).catch(() => null);
+    const warnings = [];
+    let wantBridge = auth?.mode === 'chatgpt_oauth';
+    if (wantBridge) {
+        const failure = await input.selfCheck(baseUrl, input.catalog);
+        if (failure) {
+            warnings.push(failure);
+            wantBridge = false;
+        }
+    }
+    if (!wantBridge && !input.catalogPath) {
+        return { source: codexReadsBridgeModels(current) ? 'bridge_models' : 'model_catalog_json', changed: false, warnings: [...warnings, 'codex_model_catalog_path_unavailable'] };
+    }
+    const next = setDesktopBridgeManagedModelCatalog(current, wantBridge ? null : input.catalogPath);
+    const source = wantBridge ? 'bridge_models' : 'model_catalog_json';
+    if (next === current)
+        return { source, changed: false, warnings };
+    if (!input.allowConfigWrites) {
+        return {
+            source: codexReadsBridgeModels(current) ? 'bridge_models' : 'model_catalog_json',
+            changed: false,
+            warnings: [...warnings, `codex_model_source_change_deferred:${source}`]
+        };
+    }
+    const write = await safeWriteCodexConfigToml(input.configPath, current, next, 'desktop-bridge-model-source', { verifyUnchangedBeforeWrite: true });
+    if (!write.ok)
+        return { source: codexReadsBridgeModels(current) ? 'bridge_models' : 'model_catalog_json', changed: false, warnings: [...warnings, `codex_model_source_write_refused:${write.status}`] };
+    return { source, changed: true, warnings };
+}

package/dist/core/codex-lb/desktop-controller-v3/openrouter-only-commands.js

@@ -9,7 +9,7 @@ import { readActiveCombinedBridgeCatalog } from '../combined-catalog.js';
 import { MAX_SELECTED_OPENROUTER_MODELS, bridgeAvailableModelsPath, readBridgeModelSelectionState, writeBridgeModelSelection } from '../combined-catalog/model-selection.js';
 import { ensureUserReadOnlyListRole } from '../../subagents/read-only-list-role.js';
 import { canonicalizeBridgeModelId } from '../route-index.js';
-import { syncCatalogInternal } from './catalog.js';
+import { syncAsRefresh } from './catalog.js';
 import { hasOpenRouterRoute, openRouterOnlyStoreLocation } from './openrouter-only-catalog.js';
 import { applyOpenRouterOnlyMainModel, openRouterOnlyMainModelTarget, restoreOpenRouterOnlyMainModel } from './openrouter-only-main-model.js';
 import { openRouterOnlyProviderBlocker, openRouterOnlyStatusFromCore } from './openrouter-only-status.js';
@@ -116,10 +116,10 @@ async function enableOpenRouterOnly(noRestart, options) {
     if (entries.length === 0) {
         return finish('openrouter-only.set', false, ['openrouter_only_no_openrouter_models'], {}, options);
     }
-    const sync = await syncCatalogInternal({
+    const sync = await syncAsRefresh({
         ...options,
         settings: { ...(options.settings || {}), auth_priority_enabled: false }
-    }, {
+    }, 'openrouter-only.set', {
         openRouterOnly: { ...before, enabled: true, subagent_models: entries },
         onActivated: async () => {
             await requireRoutableEntry(core.paths, { ...before, enabled: true, subagent_models: entries });
@@ -204,7 +204,7 @@ export async function turnOffOpenRouterOnly(options, behavior = {}) {
         return { ok: true, changed: false, catalog_sync: null, main_model: null, blockers: [] };
     }
     const off = { ...before, enabled: false };
-    const sync = (commit) => syncCatalogInternal(options, {
+    const sync = (commit) => syncAsRefresh(options, 'openrouter-only.off', {
         ...(behavior.restartService === undefined ? {} : { restartService: behavior.restartService }),
         openRouterOnly: off,
         ...(commit ? { onActivated: () => writeOpenRouterOnlyState({ enabled: false }, location) } : {})
@@ -319,7 +319,7 @@ export async function setSubagentModels(raw, noRestart, options, expectedProfile
         }, options);
     }
     const exposedBefore = await exposedModelIds(paths);
-    const sync = await syncCatalogInternal(options, {
+    const sync = await syncAsRefresh(options, 'subagent-models.set', {
         openRouterOnly: { ...before, subagent_models: entries },
         onActivated: async () => {
             if (entries.length > 0)