sneakoscope 8.1.2 → 8.2.0

package/dist/core/codex-lb/desktop-service.js

@@ -1,93 +1,128 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
 import fsp from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { ensureDir, exists, runProcess, which, writeTextAtomic } from '../fsx.js';
-import { loadCodexLbEnv, readCodexLbModelCatalog } from './codex-lb-env.js';
+import { withFileLock } from '../locks/file-lock.js';
+import { loadCodexLbEnv } from './codex-lb-env.js';
 import { resolveOpenRouterApiKey } from '../providers/openrouter/openrouter-secret-store.js';
-import { ARCHITECTURE_HARDENING_CONTRACT_VERSION, credentialClassForMode, stableArchitectureHash, } from '../architecture-hardening/contracts/contracts.js';
-import { createChildPolicySnapshot } from '../codex-app/child-policy/child-policy.js';
-import { DESKTOP_BRIDGE_ALLOWED_PATH_PREFIXES, DESKTOP_BRIDGE_LAUNCHD_LABEL, desktopBridgeConfigGeneration, desktopBridgeLaunchdPlistPath, desktopBridgeProcessExists, desktopBridgeStatePath, getDesktopBridgeStatus, preflightDesktopBridge, readDesktopBridgeState, renderDesktopBridgeLaunchdPlist, safeBridgeErrorCode, selectAvailableDesktopBridgePort, startPreparedDesktopBridge } from './desktop-bridge/index.js';
-import { DEFAULT_CODEX_LB_GATEWAY_AUTH_TRANSPORT, parseCodexLbGatewayAuthTransport } from './desktop-mode.js';
-export const DEFAULT_CODEX_LB_DESKTOP_BRIDGE_HOST = '127.0.0.1';
-export const DEFAULT_CODEX_LB_DESKTOP_BRIDGE_PORT = 49_152;
-export const CODEX_LB_DESKTOP_BRIDGE_SETTINGS_SCHEMA = 'sks.codex-lb-desktop-bridge-settings.v1';
-export const CODEX_LB_DESKTOP_BRIDGE_SERVICE_SCHEMA = 'sks.codex-lb-desktop-bridge-service.v1';
+import { cleanupRetiredDesktopBridgeRuntime, prepareRetiredDesktopBridgeRuntime, } from './desktop-bridge-migration/retired-runtime-cleanup.js';
+import { canonicalizeBridgeModelId, normalizeBridgeUpstreamModelId, sha256Stable } from './route-index.js';
+import { DESKTOP_BRIDGE_ALLOWED_PATH_PREFIXES, DESKTOP_BRIDGE_LAUNCHD_LABEL, desktopBridgeConfigGeneration, desktopBridgeLaunchdPlistPath, desktopBridgeProcessExists, desktopBridgeStatePath, getDesktopBridgeStatus, preflightDesktopBridge, readDesktopBridgeState, safeBridgeErrorCode, writeDesktopBridgeLaunchdPlist, selectAvailableDesktopBridgePort, startPreparedDesktopBridge, DESKTOP_BRIDGE_STATE_SCHEMA, DesktopBridgeError, } from './desktop-bridge/index.js';
+export const DEFAULT_DESKTOP_BRIDGE_HOST = '127.0.0.1';
+export const DEFAULT_DESKTOP_BRIDGE_PORT = 49_152;
+export const DESKTOP_BRIDGE_SETTINGS_SCHEMA = 'sks.desktop-bridge-settings.v2';
+export const DESKTOP_BRIDGE_SERVICE_SCHEMA = 'sks.desktop-bridge-service.v2';
 const DEFAULT_ALLOWED_ORIGINS = ['app://codex'];
-const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
-const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60_000;
-const OPENROUTER_RESPONSES_BASE_URL = 'https://openrouter.ai/api/v1';
+const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
 export function desktopBridgeServicePaths(home = process.env.HOME || os.homedir()) {
-    const resolvedHome = path.resolve(home);
-    const runtimeDir = path.join(resolvedHome, '.codex', 'sks');
-    const logDir = path.join(runtimeDir, 'logs');
-    return {
-        settings_path: path.join(runtimeDir, 'codex-lb-desktop-bridge-settings.json'),
-        state_path: desktopBridgeStatePath(resolvedHome),
-        launch_agent_path: desktopBridgeLaunchdPlistPath(resolvedHome),
-        stdout_log_path: path.join(logDir, 'codex-lb-desktop-bridge.out.log'),
-        stderr_log_path: path.join(logDir, 'codex-lb-desktop-bridge.err.log')
-    };
+    const runtime = path.join(path.resolve(home), '.codex', 'sks');
+    const logs = path.join(runtime, 'logs');
+    return { settings_path: path.join(runtime, 'desktop-bridge-settings.json'), state_path: desktopBridgeStatePath(path.resolve(home)), client_capability_path: path.join(runtime, 'desktop-bridge-client-capability'), launch_agent_path: desktopBridgeLaunchdPlistPath(path.resolve(home)), stdout_log_path: path.join(logs, 'desktop-bridge.out.log'), stderr_log_path: path.join(logs, 'desktop-bridge.err.log') };
 }
-export function defaultDesktopBridgeServiceSettings(input = {}) {
-    return validateDesktopBridgeServiceSettings({
-        schema: CODEX_LB_DESKTOP_BRIDGE_SETTINGS_SCHEMA,
-        listen_host: input.listen_host || DEFAULT_CODEX_LB_DESKTOP_BRIDGE_HOST,
-        listen_port: input.listen_port ?? DEFAULT_CODEX_LB_DESKTOP_BRIDGE_PORT,
-        provider_mode: input.provider_mode || 'codex-lb',
-        allowed_models: [...(input.allowed_models || [])],
-        gateway_auth_transport: parseCodexLbGatewayAuthTransport(input.gateway_auth_transport || DEFAULT_CODEX_LB_GATEWAY_AUTH_TRANSPORT),
-        allowed_origins: [...(input.allowed_origins || DEFAULT_ALLOWED_ORIGINS)],
-        connect_timeout_ms: input.connect_timeout_ms ?? DEFAULT_CONNECT_TIMEOUT_MS,
-        idle_timeout_ms: input.idle_timeout_ms ?? DEFAULT_IDLE_TIMEOUT_MS,
-        catalog_version: input.catalog_version,
-        registered_child_models: input.registered_child_models,
-        session_pins: input.session_pins,
-        require_session_pin: input.require_session_pin
+function fingerprint(secret) { return createHash('sha256').update(secret).digest('hex').slice(0, 16); }
+function sha256(value) { return createHash('sha256').update(value).digest('hex'); }
+function generation(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+function validateClientCapability(value) {
+    const capability = String(value || '').trim();
+    if (!/^[A-Za-z0-9_-]{43}$/.test(capability))
+        throw new Error('desktop_bridge_client_capability_invalid');
+    return capability;
+}
+export async function readDesktopBridgeClientCapability(file) {
+    let handle;
+    try {
+        handle = await fsp.open(file, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new Error('desktop_bridge_client_capability_missing');
+        throw error;
+    }
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > 256)
+            throw new Error('desktop_bridge_client_capability_file_invalid');
+        const expectedUid = typeof process.getuid === 'function' ? process.getuid() : null;
+        if (expectedUid !== null && stat.uid !== expectedUid)
+            throw new Error('desktop_bridge_client_capability_owner_mismatch');
+        if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0)
+            throw new Error('desktop_bridge_client_capability_permissions_unsafe');
+        return validateClientCapability((await handle.readFile('utf8')).trim());
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+export async function ensureDesktopBridgeClientCapability(file) {
+    await ensurePrivateDirectory(path.dirname(file));
+    return withFileLock(settingsLockOptions(file), async () => {
+        try {
+            return await readDesktopBridgeClientCapability(file);
+        }
+        catch (error) {
+            if (!(error instanceof Error) || error.message !== 'desktop_bridge_client_capability_missing')
+                throw error;
+        }
+        const capability = randomBytes(32).toString('base64url');
+        await writeTextAtomic(file, `${capability}\n`, { mode: 0o600 });
+        if (process.platform !== 'win32')
+            await fsp.chmod(file, 0o600);
+        const verified = await readDesktopBridgeClientCapability(file);
+        if (verified !== capability)
+            throw new Error('desktop_bridge_client_capability_write_verification_failed');
+        return capability;
     });
 }
-export function desktopBridgeArchitecturePolicy(settings) {
-    const mode = settings.provider_mode;
-    const allowedModels = [...settings.allowed_models];
-    const catalogVersion = settings.catalog_version
-        || `catalog-${stableArchitectureHash({ mode, allowed_models: [...allowedModels].sort() }).slice(0, 24)}`;
-    const seed = {
-        schema: 'sks.provider-policy-snapshot.v1',
-        contract_version: ARCHITECTURE_HARDENING_CONTRACT_VERSION,
-        mode,
-        credential_class: credentialClassForMode(mode),
-        allowed_models: allowedModels,
-        child_policy_hash: '0'.repeat(64),
-        catalog_version: catalogVersion,
+function disabledProvider(id) {
+    return { provider_id: id, enabled: false, base_url: id === 'openrouter' ? OPENROUTER_BASE_URL : 'https://invalid.codex-lb.local', allowed_origins: [id === 'openrouter' ? 'https://openrouter.ai' : 'https://invalid.codex-lb.local'], auth_transport: id === 'openrouter' ? 'openrouter-bearer' : 'x-codex-lb-api-key', credential_state: 'not_configured', credential_fingerprint: null, credential_generation: 'not-configured', source_catalog_generation: null };
+}
+function emptyProviderRegistry() {
+    const providers = {
+        'codex-lb': disabledProvider('codex-lb'),
+        openrouter: disabledProvider('openrouter')
     };
-    const registered = settings.registered_child_models === undefined
-        ? allowedModels
-        : settings.registered_child_models;
-    const child = createChildPolicySnapshot(seed, registered);
-    const policy = { ...seed, child_policy_hash: child.policy_hash };
     return {
-        policy,
-        credential: { status: 'ready', reason_code: null },
-        child,
-        sessionPins: [...(settings.session_pins || [])],
-        requireSessionPin: settings.require_session_pin === true,
+        schema: 'sks.desktop-bridge-provider-registry.v1',
+        generation: sha256Stable(providers),
+        created_at: new Date(0).toISOString(),
+        providers
     };
 }
+function emptyRoutingPolicy() {
+    const modelRoutes = {};
+    return {
+        schema: 'sks.bridge-routing-policy.v1',
+        default_provider_id: null,
+        fallback: 'none',
+        model_routes: modelRoutes,
+        catalog_generation: 'not-configured',
+        policy_generation: generation(modelRoutes),
+        changed_at: new Date(0).toISOString()
+    };
+}
+export function defaultDesktopBridgeServiceSettings(input = {}) {
+    const registry = input.provider_registry || emptyProviderRegistry();
+    const policy = input.route_policy || emptyRoutingPolicy();
+    return validateDesktopBridgeServiceSettings({
+        schema: DESKTOP_BRIDGE_SETTINGS_SCHEMA, listen_host: input.listen_host || DEFAULT_DESKTOP_BRIDGE_HOST,
+        listen_port: input.listen_port ?? DEFAULT_DESKTOP_BRIDGE_PORT, provider_registry: registry, route_policy: policy,
+        provider_session_pins: [...(input.provider_session_pins || [])], client_capability_sha256: input.client_capability_sha256 || '0'.repeat(64), allowed_origins: [...(input.allowed_origins || DEFAULT_ALLOWED_ORIGINS)],
+        connect_timeout_ms: input.connect_timeout_ms ?? 10_000, idle_timeout_ms: input.idle_timeout_ms ?? 300_000
+    });
+}
 export async function resolveDesktopBridgeActivationSettings(options = {}) {
     const home = options.home || options.env?.HOME || process.env.HOME || os.homedir();
     const paths = overridePaths(desktopBridgeServicePaths(home), options);
+    const clientCapability = options.clientCapability
+        ? validateClientCapability(options.clientCapability)
+        : await ensureDesktopBridgeClientCapability(paths.client_capability_path);
     const persisted = await readDesktopBridgeServiceSettings(paths.settings_path);
-    const listenHost = options.settings?.listen_host
-        || persisted?.listen_host
-        || DEFAULT_CODEX_LB_DESKTOP_BRIDGE_HOST;
-    const listenPort = options.settings?.listen_port
-        ?? persisted?.listen_port
-        ?? await (options.selectAvailablePort || selectAvailableDesktopBridgePort)(listenHost);
-    return defaultDesktopBridgeServiceSettings({
-        ...(persisted || {}),
-        ...(options.settings || {}),
-        listen_host: listenHost,
-        listen_port: listenPort
-    });
+    const merged = { ...(persisted || {}), ...(options.settings || {}) };
+    const host = merged.listen_host || DEFAULT_DESKTOP_BRIDGE_HOST;
+    const port = merged.listen_port ?? await (options.selectAvailablePort || selectAvailableDesktopBridgePort)(host);
+    return defaultDesktopBridgeServiceSettings({ ...merged, ...(options.providerRegistry ? { provider_registry: options.providerRegistry } : {}), ...(options.routePolicy ? { route_policy: options.routePolicy } : {}), ...(options.providerSessionPins ? { provider_session_pins: [...options.providerSessionPins] } : {}), client_capability_sha256: sha256(clientCapability), listen_host: host, listen_port: port });
 }
 export async function readDesktopBridgeServiceSettings(file) {
     let stat;
@@ -95,17 +130,16 @@ export async function readDesktopBridgeServiceSettings(file) {
         stat = await fsp.lstat(file);
     }
     catch (error) {
-        if (errorCode(error) === 'ENOENT')
+        if (error.code === 'ENOENT')
             return null;
         throw error;
     }
-    if (!stat.isFile() || stat.isSymbolicLink()) {
+    if (!stat.isFile() || stat.isSymbolicLink())
         throw new Error('desktop_bridge_settings_not_regular_file');
-    }
     if ((stat.mode & 0o077) !== 0)
         throw new Error('desktop_bridge_settings_permissions_unsafe');
     const raw = await fsp.readFile(file, 'utf8');
-    if (Buffer.byteLength(raw) > 64 * 1024)
+    if (Buffer.byteLength(raw) > 256 * 1024)
         throw new Error('desktop_bridge_settings_too_large');
     let parsed;
     try {
@@ -117,636 +151,437 @@ export async function readDesktopBridgeServiceSettings(file) {
     return validateDesktopBridgeServiceSettings(parsed);
 }
 export async function writeDesktopBridgeServiceSettings(file, settings) {
+    await withFileLock(settingsLockOptions(file), async () => {
+        await writeDesktopBridgeServiceSettingsUnlocked(file, settings);
+    });
+}
+async function writeDesktopBridgeServiceSettingsUnlocked(file, settings) {
     const validated = validateDesktopBridgeServiceSettings(settings);
-    await writeTextAtomic(file, `${JSON.stringify(validated, null, 2)}\n`, { mode: 0o600 });
+    const persisted = { schema: validated.schema, listen_host: validated.listen_host, listen_port: validated.listen_port, provider_registry: validated.provider_registry, route_policy: validated.route_policy, provider_session_pins: validated.provider_session_pins, client_capability_sha256: validated.client_capability_sha256, allowed_origins: validated.allowed_origins, connect_timeout_ms: validated.connect_timeout_ms, idle_timeout_ms: validated.idle_timeout_ms };
+    await writeTextAtomic(file, `${JSON.stringify(persisted, null, 2)}\n`, { mode: 0o600 });
     await fsp.chmod(file, 0o600);
 }
+async function runtimeCredentials(settings, options) {
+    if (options.resolveProviderCredential) {
+        const sources = Object.fromEntries(['codex-lb', 'openrouter']
+            .filter((id) => settings.provider_registry.providers[id].credential_state === 'ready')
+            .map((id) => [id, 'injected-registry']));
+        return { registry: settings.provider_registry, resolver: options.resolveProviderCredential, sources, loaded: null };
+    }
+    const secrets = new Map();
+    let loaded = null;
+    try {
+        loaded = await loadCodexLbEnv({ home: options.home, ...(options.envPath ? { envPath: options.envPath } : {}), ...(options.metadataPath ? { metadataPath: options.metadataPath } : {}), ...(options.env ? { processEnv: options.env } : {}) });
+        if (loaded.configured && loaded.base_url && loaded.secret_api_key)
+            secrets.set('codex-lb', { value: loaded.secret_api_key, source: loaded.source, fingerprint: fingerprint(loaded.secret_api_key), generation: generation({ value: loaded.secret_api_key }) });
+    }
+    catch {
+        loaded = null;
+    }
+    const openrouter = await resolveOpenRouterApiKey({ env: options.env || process.env }).catch(() => ({ key: null, source: 'missing' }));
+    if (openrouter.key)
+        secrets.set('openrouter', { value: openrouter.key, source: openrouter.source === 'env' ? 'openrouter-env' : 'openrouter-user-secret-store', fingerprint: fingerprint(openrouter.key), generation: generation({ value: openrouter.key }) });
+    const providers = { ...settings.provider_registry.providers };
+    const adopted = new Map();
+    for (const id of ['codex-lb', 'openrouter']) {
+        const source = secrets.get(id);
+        const current = providers[id];
+        const endpointMatches = id !== 'codex-lb'
+            || !loaded?.base_url
+            || normalizeEndpointForBinding(loaded.base_url) === normalizeEndpointForBinding(current.base_url);
+        const identityMatches = Boolean(source
+            && current.credential_fingerprint
+            && source.fingerprint === current.credential_fingerprint
+            && endpointMatches);
+        const credentialState = !source
+            ? current.credential_state === 'ready' ? 'unavailable' : 'not_configured'
+            : current.credential_state === 'ready'
+                ? identityMatches ? 'ready' : 'stale'
+                : current.credential_state === 'not_configured'
+                    ? 'configured_unverified'
+                    : current.credential_state;
+        if (source && credentialState === 'ready')
+            adopted.set(id, source);
+        providers[id] = {
+            ...current,
+            credential_state: credentialState,
+            credential_fingerprint: source?.fingerprint || null,
+            credential_generation: current.credential_generation
+        };
+    }
+    const registry = { ...settings.provider_registry, generation: sha256Stable(providers), providers };
+    const resolver = options.resolveProviderCredential || (async (id, expected) => {
+        const secret = adopted.get(id);
+        if (!secret)
+            throw new Error(`${id.replace('-', '_')}_credential_unavailable`);
+        const profile = providers[id];
+        if (profile.credential_generation !== expected || profile.credential_fingerprint !== secret.fingerprint) {
+            throw new Error('bridge_provider_credential_generation_mismatch');
+        }
+        return { provider_id: id, value: secret.value, source: secret.source, fingerprint: secret.fingerprint, generation: expected };
+    });
+    return { registry, resolver, sources: Object.fromEntries([...adopted].map(([id, value]) => [id, value.source])), loaded };
+}
+function normalizeEndpointForBinding(value) {
+    try {
+        return new URL(value).toString().replace(/\/+$/, '');
+    }
+    catch {
+        return String(value || '').trim().replace(/\/+$/, '');
+    }
+}
 export async function resolveDesktopBridgeRuntimeConfig(options = {}) {
     const home = options.home || options.env?.HOME || process.env.HOME || os.homedir();
-    const defaults = desktopBridgeServicePaths(home);
-    const paths = overridePaths(defaults, options);
-    const persisted = await readDesktopBridgeServiceSettings(paths.settings_path);
-    const settings = defaultDesktopBridgeServiceSettings({
-        ...(persisted || {}),
-        ...(options.settings || {})
+    const paths = overridePaths(desktopBridgeServicePaths(home), options);
+    let settings = defaultDesktopBridgeServiceSettings({ ...((await readDesktopBridgeServiceSettings(paths.settings_path)) || {}), ...(options.settings || {}), ...(options.providerRegistry ? { provider_registry: options.providerRegistry } : {}), ...(options.routePolicy ? { route_policy: options.routePolicy } : {}), ...(options.providerSessionPins ? { provider_session_pins: [...options.providerSessionPins] } : {}) });
+    const clientCapability = options.clientCapability
+        ? validateClientCapability(options.clientCapability)
+        : await readDesktopBridgeClientCapability(paths.client_capability_path);
+    if (sha256(clientCapability) !== settings.client_capability_sha256)
+        throw new Error('desktop_bridge_client_capability_mismatch');
+    const credentials = await runtimeCredentials(settings, { ...options, home });
+    settings = defaultDesktopBridgeServiceSettings({ ...settings, provider_registry: credentials.registry });
+    if (!Object.keys(settings.route_policy.model_routes).length)
+        throw new Error('catalog_model_route_missing');
+    const enabledRoutes = new Set(Object.values(settings.route_policy.model_routes).map((route) => route.provider_id));
+    if (![...enabledRoutes].some((id) => credentials.registry.providers[id].credential_state === 'ready'))
+        throw new Error('desktop_bridge_provider_credentials_unavailable');
+    const persistProviderSessionPins = options.persistProviderSessionPins
+        || ((pins) => persistDesktopBridgeSessionPins(paths.settings_path, settings, pins));
+    const config = { providerRegistry: settings.provider_registry, routePolicy: settings.route_policy, providerSessionPins: settings.provider_session_pins, ...(options.resolveRequestRoute ? { resolveRequestRoute: options.resolveRequestRoute } : {}), persistProviderSessionPins, resolveProviderCredential: credentials.resolver, clientCapabilitySha256: settings.client_capability_sha256, listenHost: settings.listen_host, listenPort: settings.listen_port, allowedPathPrefixes: DESKTOP_BRIDGE_ALLOWED_PATH_PREFIXES, allowedOrigins: settings.allowed_origins, connectTimeoutMs: settings.connect_timeout_ms, idleTimeoutMs: settings.idle_timeout_ms };
+    const primary = credentials.sources['codex-lb'] || credentials.sources.openrouter;
+    if (!primary)
+        throw new Error('desktop_bridge_provider_credentials_unavailable');
+    return { config, settings, loaded_env: credentials.loaded, credential_source: primary, credential_sources: credentials.sources, paths };
+}
+async function persistDesktopBridgeSessionPins(file, expected, pins) {
+    await withFileLock(settingsLockOptions(file), async () => {
+        const current = await readDesktopBridgeServiceSettings(file);
+        if (!current
+            || current.listen_host !== expected.listen_host
+            || current.listen_port !== expected.listen_port
+            || current.provider_registry.generation !== expected.provider_registry.generation
+            || current.route_policy.policy_generation !== expected.route_policy.policy_generation
+            || current.route_policy.catalog_generation !== expected.route_policy.catalog_generation) {
+            throw new DesktopBridgeError('session_pin_route_unavailable');
+        }
+        await writeDesktopBridgeServiceSettingsUnlocked(file, {
+            ...current,
+            provider_session_pins: [...pins],
+        });
     });
-    if (!settings.allowed_models.length)
-        throw new Error('desktop_bridge_provider_model_allowlist_empty');
-    const credentials = await resolveDesktopBridgeCredentials(settings, { ...options, home });
-    const architecture = desktopBridgeArchitecturePolicy(settings);
+}
+function settingsLockOptions(file) {
     return {
-        config: {
-            listenHost: settings.listen_host,
-            listenPort: settings.listen_port,
-            providerMode: settings.provider_mode,
-            allowedModels: settings.allowed_models,
-            providerPolicy: architecture.policy,
-            credentialReadiness: architecture.credential,
-            childPolicy: architecture.child,
-            sessionPins: architecture.sessionPins,
-            requireSessionPin: architecture.requireSessionPin,
-            remoteBaseUrl: credentials.remote_base_url,
-            gatewayKey: credentials.key,
-            gatewayAuthTransport: credentials.auth_transport,
-            allowedPathPrefixes: DESKTOP_BRIDGE_ALLOWED_PATH_PREFIXES,
-            allowedOrigins: settings.allowed_origins,
-            connectTimeoutMs: settings.connect_timeout_ms,
-            idleTimeoutMs: settings.idle_timeout_ms
-        },
-        settings,
-        loaded_env: credentials.loaded_env,
-        credential_source: credentials.source,
-        paths
+        lockPath: `${path.resolve(file)}.lock`,
+        timeoutMs: 5_000,
+        staleMs: 30_000,
     };
 }
 export async function desktopBridgeServiceStatus(options = {}) {
     const home = options.home || options.env?.HOME || process.env.HOME || os.homedir();
     const paths = overridePaths(desktopBridgeServicePaths(home), options);
-    const service = desktopBridgeLaunchService(options.uid);
-    if ((options.platform || process.platform) !== 'darwin') {
-        return {
-            schema: CODEX_LB_DESKTOP_BRIDGE_SERVICE_SCHEMA,
-            ok: false,
-            supported: false,
-            installed: await exists(paths.launch_agent_path),
-            loaded: false,
-            running: false,
-            status: 'unsupported',
-            service,
-            paths,
-            state: await readDesktopBridgeState(paths.state_path).catch(() => null),
-            settings: await readDesktopBridgeServiceSettings(paths.settings_path).catch(() => null),
-            expected_config_generation: null,
-            credential_source: null,
-            blockers: ['desktop_bridge_service_requires_macos']
-        };
-    }
-    const installed = await exists(paths.launch_agent_path);
+    const service = launchService(options.uid);
     const settings = await readDesktopBridgeServiceSettings(paths.settings_path).catch(() => null);
-    let expectedConfigGeneration = null;
-    let credentialSource = null;
-    const credentialBlockers = [];
-    if (settings) {
+    if ((options.platform || process.platform) !== 'darwin')
+        return { schema: DESKTOP_BRIDGE_SERVICE_SCHEMA, ok: false, supported: false, installed: await exists(paths.launch_agent_path), loaded: false, running: false, status: 'unsupported', service, paths, state: await readDesktopBridgeState(paths.state_path).catch(() => null), settings, expected_config_generation: null, credential_source: null, blockers: ['desktop_bridge_service_requires_macos'] };
+    let expected = null;
+    let source = null;
+    let sources = {};
+    const blockers = [];
+    if (!settings)
+        blockers.push('desktop_bridge_settings_missing');
+    else
         try {
             const runtime = await resolveDesktopBridgeRuntimeConfig({ ...options, home, settingsPath: paths.settings_path });
-            expectedConfigGeneration = desktopBridgeConfigGeneration(runtime.config);
-            credentialSource = runtime.credential_source;
+            expected = desktopBridgeConfigGeneration(runtime.config);
+            source = runtime.credential_source;
+            sources = runtime.credential_sources;
         }
         catch (error) {
-            credentialBlockers.push(safeServiceError(error));
+            blockers.push(safeServiceError(error));
         }
-    }
-    const bridgeStatus = await getDesktopBridgeStatus({
-        statePath: paths.state_path,
-        ...(expectedConfigGeneration ? { expectedConfigGeneration } : {}),
-        ...(options.processExists ? { processExists: options.processExists } : {})
-    });
-    const launchd = await inspectLaunchdService(options, service);
-    const blockers = [
-        ...(settings ? [] : ['desktop_bridge_settings_missing']),
-        ...credentialBlockers,
-        ...(bridgeStatus.status === 'running' ? [] : [bridgeStatusBlocker(bridgeStatus)]),
-        ...(launchd.loaded && !launchd.running ? ['desktop_bridge_launchd_not_running'] : [])
-    ].filter(Boolean);
-    const running = bridgeStatus.status === 'running';
-    return {
-        schema: CODEX_LB_DESKTOP_BRIDGE_SERVICE_SCHEMA,
-        ok: running && blockers.length === 0,
-        supported: true,
-        installed,
-        loaded: launchd.loaded,
-        running,
-        status: !settings
-            ? 'settings_missing'
-            : credentialBlockers.length
-                ? 'credentials_unavailable'
-                : bridgeStatus.status,
-        service,
-        paths,
-        state: bridgeStatus.state,
-        settings,
-        expected_config_generation: expectedConfigGeneration,
-        credential_source: credentialSource,
-        blockers
-    };
+    const bridge = await getDesktopBridgeStatus({ statePath: paths.state_path, ...(expected ? { expectedConfigGeneration: expected } : {}), ...(options.processExists ? { processExists: options.processExists } : {}) });
+    const launchd = await inspectLaunchd(options, service);
+    if (bridge.status !== 'running')
+        blockers.push(bridgeStatusBlocker(bridge));
+    if (launchd.loaded && !launchd.running)
+        blockers.push('desktop_bridge_launchd_not_running');
+    return { schema: DESKTOP_BRIDGE_SERVICE_SCHEMA, ok: bridge.status === 'running' && blockers.length === 0, supported: true, installed: await exists(paths.launch_agent_path), loaded: launchd.loaded, running: bridge.status === 'running', status: !settings ? 'settings_missing' : blockers.some((b) => b.includes('credential')) ? 'credentials_unavailable' : bridge.status, service, paths, state: bridge.state, settings, expected_config_generation: expected, credential_source: source, credential_sources: sources, blockers: [...new Set(blockers.filter(Boolean))] };
 }
 export async function installAndStartDesktopBridgeService(options = {}) {
-    const platform = options.platform || process.platform;
     const home = options.home || options.env?.HOME || process.env.HOME || os.homedir();
-    const paths = overridePaths(desktopBridgeServicePaths(home), options);
-    if (platform !== 'darwin') {
+    const platform = options.platform || process.platform;
+    if (platform !== 'darwin')
         return desktopBridgeServiceStatus({ ...options, home, platform });
+    const paths = overridePaths(desktopBridgeServicePaths(home), options);
+    let retired;
+    try {
+        retired = await prepareRetiredDesktopBridgeRuntime({
+            home,
+            ...(options.uid === undefined ? {} : { uid: options.uid }),
+            ...(options.launchctl ? { launchctl: options.launchctl } : {}),
+            ...(options.run ? { run: options.run } : {}),
+        });
     }
-    let settings = await resolveDesktopBridgeActivationSettings({
-        ...options,
-        home,
-        settingsPath: paths.settings_path
+    catch (error) {
+        return failedStatus(paths, defaultDesktopBridgeServiceSettings(), launchService(options.uid), 'missing', safeServiceError(error));
+    }
+    const inheritedSettings = !(await exists(paths.settings_path)) && retired.settings
+        ? retired.settings
+        : {};
+    const settings = await resolveDesktopBridgeActivationSettings({
+        ...options, home, settingsPath: paths.settings_path,
+        settings: { ...inheritedSettings, ...(options.settings || {}) },
     });
-    let credentials;
+    let runtime;
     try {
-        credentials = await resolveDesktopBridgeCredentials(settings, { ...options, home });
+        runtime = await resolveDesktopBridgeRuntimeConfig({ ...options, home, settings: settings, settingsPath: paths.settings_path });
+        await preflightDesktopBridge(runtime.config);
     }
     catch (error) {
-        return {
-            schema: CODEX_LB_DESKTOP_BRIDGE_SERVICE_SCHEMA,
-            ok: false,
-            supported: true,
-            installed: await exists(paths.launch_agent_path),
-            loaded: false,
-            running: false,
-            status: 'credentials_unavailable',
-            service: desktopBridgeLaunchService(options.uid),
-            paths,
-            state: await readDesktopBridgeState(paths.state_path).catch(() => null),
-            settings,
-            expected_config_generation: null,
-            credential_source: null,
-            blockers: [safeServiceError(error)]
-        };
-    }
-    if (!settings.allowed_models.length && settings.provider_mode === 'codex-lb' && credentials.loaded_env) {
-        const catalog = await readCodexLbModelCatalog({
-            loadedEnv: credentials.loaded_env,
-            gatewayAuthTransport: credentials.auth_transport
-        });
-        if (!catalog.ok || !catalog.models.length) {
-            return failedServiceStatus({
-                paths,
-                settings,
-                service: desktopBridgeLaunchService(options.uid),
-                status: 'credentials_unavailable',
-                credentialSource: credentials.source,
-                expectedConfigGeneration: null,
-                blocker: catalog.blockers[0] || 'codex_lb_model_catalog_unavailable'
-            });
-        }
-        settings = defaultDesktopBridgeServiceSettings({ ...settings, allowed_models: catalog.models });
-    }
-    if (!settings.allowed_models.length) {
-        return failedServiceStatus({
-            paths,
-            settings,
-            service: desktopBridgeLaunchService(options.uid),
-            status: 'credentials_unavailable',
-            credentialSource: credentials.source,
-            expectedConfigGeneration: null,
-            blocker: 'desktop_bridge_provider_model_allowlist_empty'
-        });
+        return failedStatus(paths, settings, launchService(options.uid), 'credentials_unavailable', safeServiceError(error));
+    }
+    const command = await resolveLaunchCommand(options);
+    if (!command)
+        return failedStatus(paths, settings, launchService(options.uid), 'settings_missing', 'desktop_bridge_sks_executable_missing');
+    await prepareDesktopBridgeServicePaths(paths);
+    await writeDesktopBridgeServiceSettings(paths.settings_path, { ...settings, provider_registry: runtime.config.providerRegistry, route_policy: runtime.config.routePolicy });
+    await writeDesktopBridgeLaunchdPlist(paths.launch_agent_path, { executablePath: command.executable, arguments: [...command.arguments, 'bridge', 'serve', '--settings', paths.settings_path, '--json'], stdoutPath: paths.stdout_log_path, stderrPath: paths.stderr_log_path });
+    const run = options.run || runProcess;
+    const ctl = options.launchctl || '/bin/launchctl';
+    const service = launchService(options.uid);
+    const domain = launchDomain(options.uid);
+    await run(ctl, ['bootout', service], { timeoutMs: 5_000, maxOutputBytes: 16 * 1024 }).catch(() => undefined);
+    await removeStaleState(paths.state_path, options.processExists);
+    const bootstrap = await run(ctl, ['bootstrap', domain, paths.launch_agent_path], { timeoutMs: 10_000, maxOutputBytes: 32 * 1024 }).catch((error) => failedProcess(error));
+    if (bootstrap.code !== 0 && !bootstrap.timedOut)
+        return failedStatus(paths, settings, service, 'missing', 'desktop_bridge_launchd_bootstrap_failed');
+    await run(ctl, ['kickstart', '-k', service], { timeoutMs: 10_000, maxOutputBytes: 32 * 1024 }).catch(() => undefined);
+    const status = await waitForBridge({ ...options, home });
+    if (!status.ok) {
+        await run(ctl, ['bootout', service], { timeoutMs: 5_000, maxOutputBytes: 16 * 1024 }).catch(() => undefined);
+        return status;
     }
-    const config = {
-        listenHost: settings.listen_host,
-        listenPort: settings.listen_port,
-        providerMode: settings.provider_mode,
-        allowedModels: settings.allowed_models,
-        ...desktopBridgeConfigArchitectureFields(settings),
-        remoteBaseUrl: credentials.remote_base_url,
-        gatewayKey: credentials.key,
-        gatewayAuthTransport: credentials.auth_transport,
-        allowedPathPrefixes: DESKTOP_BRIDGE_ALLOWED_PATH_PREFIXES,
-        allowedOrigins: settings.allowed_origins,
-        connectTimeoutMs: settings.connect_timeout_ms,
-        idleTimeoutMs: settings.idle_timeout_ms
-    };
     try {
-        await preflightDesktopBridge(config);
+        await cleanupRetiredDesktopBridgeRuntime(retired);
+        return status;
     }
     catch (error) {
-        return failedServiceStatus({
-            paths,
-            settings,
-            service: desktopBridgeLaunchService(options.uid),
-            status: 'credentials_unavailable',
-            credentialSource: credentials.source,
-            expectedConfigGeneration: desktopBridgeConfigGeneration(config),
-            blocker: safeBridgeErrorCode(error)
-        });
-    }
-    const launchCommand = await resolveDesktopBridgeLaunchCommand(options);
-    if (!launchCommand) {
-        return failedServiceStatus({
-            paths,
-            settings,
-            service: desktopBridgeLaunchService(options.uid),
-            status: 'settings_missing',
-            credentialSource: credentials.source,
-            expectedConfigGeneration: desktopBridgeConfigGeneration(config),
-            blocker: 'desktop_bridge_sks_executable_missing'
-        });
-    }
-    await Promise.all([
-        ensureDir(path.dirname(paths.settings_path)),
-        ensureDir(path.dirname(paths.launch_agent_path)),
-        ensureDir(path.dirname(paths.stdout_log_path))
-    ]);
-    await writeDesktopBridgeServiceSettings(paths.settings_path, settings);
-    const launchArguments = [
-        ...launchCommand.arguments,
-        'codex-lb',
-        'bridge',
-        'serve',
-        '--settings',
-        paths.settings_path,
-        '--json'
-    ];
-    const plist = renderDesktopBridgeLaunchdPlist({
-        executablePath: launchCommand.executable,
-        arguments: launchArguments,
-        stdoutPath: paths.stdout_log_path,
-        stderrPath: paths.stderr_log_path
-    });
-    await writeTextAtomic(paths.launch_agent_path, plist, { mode: 0o600 });
-    const run = options.run || runProcess;
-    const launchctl = options.launchctl || '/bin/launchctl';
-    const domain = desktopBridgeLaunchDomain(options.uid);
-    const service = desktopBridgeLaunchService(options.uid);
-    await run(launchctl, ['bootout', service], {
-        timeoutMs: 5_000,
-        maxOutputBytes: 16 * 1024
-    }).catch(() => undefined);
-    await run(launchctl, ['bootout', domain, paths.launch_agent_path], {
-        timeoutMs: 5_000,
-        maxOutputBytes: 16 * 1024
-    }).catch(() => undefined);
-    await removeStaleBridgeState(paths.state_path, options.processExists);
-    const bootstrap = await run(launchctl, ['bootstrap', domain, paths.launch_agent_path], {
-        timeoutMs: 10_000,
-        maxOutputBytes: 32 * 1024
-    }).catch((error) => failedProcess(error));
-    if (bootstrap.code !== 0 && !bootstrap.timedOut) {
-        return failedServiceStatus({
-            paths,
-            settings,
-            service,
-            status: 'missing',
-            credentialSource: credentials.source,
-            expectedConfigGeneration: desktopBridgeConfigGeneration(config),
-            blocker: 'desktop_bridge_launchd_bootstrap_failed'
-        });
+        await run(ctl, ['bootout', service], { timeoutMs: 5_000, maxOutputBytes: 16 * 1024 }).catch(() => undefined);
+        await removeStaleState(paths.state_path, options.processExists);
+        return failedStatus(paths, settings, service, 'missing', safeServiceError(error));
     }
-    await run(launchctl, ['kickstart', '-k', service], {
-        timeoutMs: 10_000,
-        maxOutputBytes: 32 * 1024
-    }).catch(() => undefined);
-    const status = await waitForDesktopBridge({
-        ...options,
-        home,
-        platform,
-        settingsPath: paths.settings_path,
-        statePath: paths.state_path,
-        launchAgentPath: paths.launch_agent_path,
-        stdoutLogPath: paths.stdout_log_path,
-        stderrLogPath: paths.stderr_log_path
-    });
-    if (!status.ok) {
-        await run(launchctl, ['bootout', service], {
-            timeoutMs: 5_000,
-            maxOutputBytes: 16 * 1024
-        }).catch(() => undefined);
-    }
-    return status;
 }
 export async function bootstrapExistingDesktopBridgeService(options = {}) {
     const home = options.home || options.env?.HOME || process.env.HOME || os.homedir();
     const paths = overridePaths(desktopBridgeServicePaths(home), options);
-    if ((options.platform || process.platform) !== 'darwin') {
+    if ((options.platform || process.platform) !== 'darwin' || !(await exists(paths.launch_agent_path)) || !(await exists(paths.settings_path)))
         return desktopBridgeServiceStatus({ ...options, home });
-    }
-    if (!(await exists(paths.launch_agent_path)) || !(await exists(paths.settings_path))) {
-        return desktopBridgeServiceStatus({ ...options, home });
-    }
     const run = options.run || runProcess;
-    const launchctl = options.launchctl || '/bin/launchctl';
-    const domain = desktopBridgeLaunchDomain(options.uid);
-    const service = desktopBridgeLaunchService(options.uid);
-    await run(launchctl, ['bootout', service], {
-        timeoutMs: 5_000,
-        maxOutputBytes: 16 * 1024
-    }).catch(() => undefined);
-    const bootstrap = await run(launchctl, ['bootstrap', domain, paths.launch_agent_path], {
-        timeoutMs: 10_000,
-        maxOutputBytes: 32 * 1024
-    }).catch((error) => failedProcess(error));
-    if (bootstrap.code === 0 || bootstrap.timedOut) {
-        await run(launchctl, ['kickstart', '-k', service], {
-            timeoutMs: 10_000,
-            maxOutputBytes: 32 * 1024
-        }).catch(() => undefined);
-    }
-    return waitForDesktopBridge({ ...options, home });
+    const ctl = options.launchctl || '/bin/launchctl';
+    const service = launchService(options.uid);
+    await run(ctl, ['bootout', service], { timeoutMs: 5_000, maxOutputBytes: 16 * 1024 }).catch(() => undefined);
+    const result = await run(ctl, ['bootstrap', launchDomain(options.uid), paths.launch_agent_path], { timeoutMs: 10_000, maxOutputBytes: 32 * 1024 }).catch((error) => failedProcess(error));
+    if (result.code === 0 || result.timedOut)
+        await run(ctl, ['kickstart', '-k', service], { timeoutMs: 10_000, maxOutputBytes: 32 * 1024 }).catch(() => undefined);
+    return waitForBridge({ ...options, home });
 }
 export async function stopDesktopBridgeService(options = {}) {
     const home = options.home || options.env?.HOME || process.env.HOME || os.homedir();
-    const paths = overridePaths(desktopBridgeServicePaths(home), options);
-    if ((options.platform || process.platform) !== 'darwin') {
+    if ((options.platform || process.platform) !== 'darwin')
         return desktopBridgeServiceStatus({ ...options, home });
-    }
-    const run = options.run || runProcess;
-    const launchctl = options.launchctl || '/bin/launchctl';
-    const service = desktopBridgeLaunchService(options.uid);
-    await run(launchctl, ['bootout', service], {
-        timeoutMs: 8_000,
-        maxOutputBytes: 32 * 1024
-    }).catch(() => undefined);
+    const paths = overridePaths(desktopBridgeServicePaths(home), options);
+    await (options.run || runProcess)(options.launchctl || '/bin/launchctl', ['bootout', launchService(options.uid)], { timeoutMs: 8_000, maxOutputBytes: 32 * 1024 }).catch(() => undefined);
     for (let attempt = 0; attempt < 20; attempt += 1) {
         const state = await readDesktopBridgeState(paths.state_path).catch(() => null);
         if (!state || !(options.processExists || desktopBridgeProcessExists)(state.pid))
             break;
         await delay(100);
     }
-    await removeStaleBridgeState(paths.state_path, options.processExists);
-    if (options.removePlist === true)
+    await removeStaleState(paths.state_path, options.processExists);
+    if (options.removePlist)
         await fsp.unlink(paths.launch_agent_path).catch(() => undefined);
-    if (options.removeSettings === true)
+    if (options.removeSettings) {
         await fsp.unlink(paths.settings_path).catch(() => undefined);
+        await fsp.unlink(paths.client_capability_path).catch(() => undefined);
+    }
     const status = await desktopBridgeServiceStatus({ ...options, home });
-    return {
-        ...status,
-        ok: !status.running,
-        blockers: status.running ? ['desktop_bridge_process_still_running'] : []
-    };
+    return { ...status, ok: !status.running, blockers: status.running ? ['desktop_bridge_process_still_running'] : [] };
 }
 export async function serveDesktopBridge(options = {}) {
     let handle = null;
     try {
         const runtime = await resolveDesktopBridgeRuntimeConfig(options);
-        const prepared = await preflightDesktopBridge(runtime.config);
-        handle = await startPreparedDesktopBridge(prepared, { statePath: runtime.paths.state_path });
-        process.stdout.write(`${JSON.stringify({
-            schema: 'sks.codex-lb-desktop-bridge-log.v1',
-            event: 'sks.codex_lb.bridge.started',
-            pid: handle.state.pid,
-            listen_origin: handle.state.listen_origin,
-            remote_origin_sha256: handle.state.remote_origin_sha256,
-            gateway_auth_transport: handle.state.gateway_auth_transport,
-            secret_fields_redacted: true
-        })}\n`);
-        await waitForShutdownSignal(handle);
-        return {
-            schema: 'sks.codex-lb-desktop-bridge-serve.v1',
-            ok: true,
-            status: 'stopped',
-            state: handle.state
-        };
+        handle = await startPreparedDesktopBridge(await preflightDesktopBridge(runtime.config), { statePath: runtime.paths.state_path });
+        process.stdout.write(`${JSON.stringify({ schema: 'sks.desktop-bridge-log.v2', event: 'sks.desktop_bridge.started', pid: handle.state.pid, process_generation: handle.state.schema === DESKTOP_BRIDGE_STATE_SCHEMA ? handle.state.process_generation : null, provider_registry_generation: runtime.config.providerRegistry?.generation, route_policy_generation: runtime.config.routePolicy?.policy_generation, secret_fields_redacted: true })}\n`);
+        await waitForShutdown(handle);
+        return { schema: 'sks.desktop-bridge-serve.v1', ok: true, status: 'stopped', state: handle.state };
     }
     catch (error) {
-        return {
-            schema: 'sks.codex-lb-desktop-bridge-serve.v1',
-            ok: false,
-            status: 'failed',
-            state: handle?.state || null,
-            blocker: safeServiceError(error)
-        };
+        return { schema: 'sks.desktop-bridge-serve.v1', ok: false, status: 'failed', state: handle?.state || null, blocker: safeServiceError(error) };
     }
     finally {
         if (handle)
             await handle.stop().catch(() => undefined);
     }
 }
-async function resolveDesktopBridgeCredentials(settings, options) {
-    if (settings.provider_mode === 'openrouter') {
-        const resolved = await resolveOpenRouterApiKey({ env: options.env || process.env });
-        if (!resolved.key)
-            throw new Error('openrouter_key_missing');
-        return {
-            remote_base_url: OPENROUTER_RESPONSES_BASE_URL,
-            key: resolved.key,
-            auth_transport: 'authorization-bearer-compat',
-            source: resolved.source === 'env' ? 'openrouter-env' : 'openrouter-user-secret-store',
-            loaded_env: null
-        };
-    }
-    const loaded = await loadCodexLbEnv({
-        home: options.home,
-        ...(options.envPath ? { envPath: options.envPath } : {}),
-        ...(options.metadataPath ? { metadataPath: options.metadataPath } : {}),
-        ...(options.env ? { processEnv: options.env } : {})
-    });
-    if (!loaded.base_url || !loaded.secret_api_key || !loaded.configured) {
-        throw new Error(loaded.credential_binding.blockers[0]
-            || loaded.missing[0]
-            || 'codex_lb_credentials_unavailable');
-    }
-    return {
-        remote_base_url: loaded.base_url,
-        key: loaded.secret_api_key,
-        auth_transport: settings.gateway_auth_transport,
-        source: loaded.source,
-        loaded_env: loaded
-    };
-}
 function validateDesktopBridgeServiceSettings(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('desktop_bridge_settings_invalid');
-    }
     const row = value;
-    if (row.schema !== CODEX_LB_DESKTOP_BRIDGE_SETTINGS_SCHEMA) {
+    const input = row;
+    if (input.schema !== DESKTOP_BRIDGE_SETTINGS_SCHEMA)
         throw new Error('desktop_bridge_settings_schema_invalid');
-    }
-    const listenHost = row.listen_host;
-    const listenPort = Number(row.listen_port);
-    const providerMode = row.provider_mode === undefined ? 'codex-lb' : row.provider_mode;
-    const allowedModels = Array.isArray(row.allowed_models)
-        ? [...new Set(row.allowed_models.map((entry) => String(entry || '').trim()).filter(Boolean))]
-        : [];
-    const gatewayAuthTransport = parseCodexLbGatewayAuthTransport(row.gateway_auth_transport);
-    const allowedOrigins = Array.isArray(row.allowed_origins)
-        ? row.allowed_origins.map((entry) => String(entry || '').trim()).filter(Boolean)
-        : [];
-    const connectTimeoutMs = Number(row.connect_timeout_ms);
-    const idleTimeoutMs = Number(row.idle_timeout_ms);
-    const catalogVersion = row.catalog_version === undefined ? undefined : String(row.catalog_version || '').trim();
-    const registeredChildModels = row.registered_child_models === undefined
-        ? undefined
-        : Array.isArray(row.registered_child_models)
-            ? [...new Set(row.registered_child_models.map((entry) => String(entry || '').trim()).filter(Boolean))]
-            : null;
-    const sessionPins = row.session_pins === undefined
-        ? undefined
-        : Array.isArray(row.session_pins) ? row.session_pins : null;
-    const requireSessionPin = row.require_session_pin === true;
-    if (listenHost !== '127.0.0.1' && listenHost !== '::1') {
+    const allowedKeys = new Set(['schema', 'listen_host', 'listen_port', 'provider_registry', 'route_policy', 'provider_session_pins', 'client_capability_sha256', 'allowed_origins', 'connect_timeout_ms', 'idle_timeout_ms']);
+    if (Object.keys(input).some((key) => !allowedKeys.has(key)))
+        throw new Error('desktop_bridge_settings_unknown_field');
+    const serialized = JSON.stringify(input);
+    if (/"(?:api_?key|secret|authorization|cookie|access_token|refresh_token|gatewayKey)"\s*:/i.test(serialized) || /Bearer\s+[A-Za-z0-9._~-]{8,}/i.test(serialized)) {
+        throw new Error('desktop_bridge_settings_secret_forbidden');
+    }
+    const host = input.listen_host;
+    const port = Number(input.listen_port);
+    if (host !== '127.0.0.1' && host !== '::1')
         throw new Error('desktop_bridge_settings_listen_host_invalid');
-    }
-    if (!Number.isInteger(listenPort) || listenPort < 49_152 || listenPort > 65_535) {
+    if (!Number.isInteger(port) || port < 49_152 || port > 65_535)
         throw new Error('desktop_bridge_settings_listen_port_invalid');
-    }
-    if (providerMode !== 'codex-lb' && providerMode !== 'openrouter') {
-        throw new Error('desktop_bridge_settings_provider_mode_invalid');
-    }
-    if (allowedModels.length > 512)
-        throw new Error('desktop_bridge_settings_allowed_models_too_many');
-    if (!allowedOrigins.length)
+    const registry = normalizeProviderRegistrySnapshot(input.provider_registry);
+    const policy = input.route_policy;
+    if (!registry || registry.schema !== 'sks.desktop-bridge-provider-registry.v1' || !registry.providers?.['codex-lb'] || !registry.providers.openrouter)
+        throw new Error('desktop_bridge_settings_provider_registry_invalid');
+    if (!policy || policy.schema !== 'sks.bridge-routing-policy.v1' || policy.fallback !== 'none')
+        throw new Error('desktop_bridge_settings_route_policy_invalid');
+    const pins = validateProviderSessionPins(input.provider_session_pins);
+    const clientCapabilitySha256 = typeof input.client_capability_sha256 === 'string' ? input.client_capability_sha256 : '0'.repeat(64);
+    if (!/^[a-f0-9]{64}$/.test(clientCapabilitySha256))
+        throw new Error('desktop_bridge_settings_client_capability_invalid');
+    const origins = Array.isArray(input.allowed_origins) ? input.allowed_origins.map(String).filter(Boolean) : [];
+    if (!origins.length)
         throw new Error('desktop_bridge_settings_allowed_origins_empty');
-    if (!Number.isFinite(connectTimeoutMs) || connectTimeoutMs < 100 || connectTimeoutMs > 120_000) {
+    const connect = Number(input.connect_timeout_ms);
+    const idle = Number(input.idle_timeout_ms);
+    if (!Number.isFinite(connect) || connect < 100 || connect > 120_000)
         throw new Error('desktop_bridge_settings_connect_timeout_invalid');
-    }
-    if (!Number.isFinite(idleTimeoutMs) || idleTimeoutMs < 1_000 || idleTimeoutMs > 86_400_000) {
+    if (!Number.isFinite(idle) || idle < 1_000 || idle > 86_400_000)
         throw new Error('desktop_bridge_settings_idle_timeout_invalid');
-    }
-    if (catalogVersion !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(catalogVersion)) {
-        throw new Error('desktop_bridge_settings_catalog_version_invalid');
-    }
-    if (registeredChildModels === null || (registeredChildModels?.length ?? 0) > 512) {
-        throw new Error('desktop_bridge_settings_child_models_invalid');
-    }
-    if (sessionPins === null || (sessionPins?.length ?? 0) > 10_000) {
-        throw new Error('desktop_bridge_settings_session_pins_invalid');
-    }
-    return {
-        schema: CODEX_LB_DESKTOP_BRIDGE_SETTINGS_SCHEMA,
-        listen_host: listenHost,
-        listen_port: listenPort,
-        provider_mode: providerMode,
-        allowed_models: allowedModels,
-        gateway_auth_transport: gatewayAuthTransport,
-        allowed_origins: [...new Set(allowedOrigins)],
-        connect_timeout_ms: connectTimeoutMs,
-        idle_timeout_ms: idleTimeoutMs,
-        ...(catalogVersion === undefined ? {} : { catalog_version: catalogVersion }),
-        ...(registeredChildModels === undefined ? {} : { registered_child_models: registeredChildModels }),
-        ...(sessionPins === undefined ? {} : { session_pins: sessionPins }),
-        require_session_pin: requireSessionPin
-    };
-}
-function desktopBridgeConfigArchitectureFields(settings) {
-    const architecture = desktopBridgeArchitecturePolicy(settings);
-    return {
-        providerPolicy: architecture.policy,
-        credentialReadiness: architecture.credential,
-        childPolicy: architecture.child,
-        sessionPins: architecture.sessionPins,
-        requireSessionPin: architecture.requireSessionPin,
-    };
-}
-function overridePaths(defaults, options) {
-    return {
-        settings_path: options.settingsPath || defaults.settings_path,
-        state_path: options.statePath || defaults.state_path,
-        launch_agent_path: options.launchAgentPath || defaults.launch_agent_path,
-        stdout_log_path: options.stdoutLogPath || defaults.stdout_log_path,
-        stderr_log_path: options.stderrLogPath || defaults.stderr_log_path
-    };
+    return { schema: DESKTOP_BRIDGE_SETTINGS_SCHEMA, listen_host: host, listen_port: port, provider_registry: registry, route_policy: policy, provider_session_pins: pins, client_capability_sha256: clientCapabilitySha256, allowed_origins: [...new Set(origins)], connect_timeout_ms: connect, idle_timeout_ms: idle };
 }
-function desktopBridgeLaunchDomain(uid = typeof process.getuid === 'function' ? process.getuid() : 0) {
-    return `gui/${uid}`;
-}
-function desktopBridgeLaunchService(uid) {
-    return `${desktopBridgeLaunchDomain(uid)}/${DESKTOP_BRIDGE_LAUNCHD_LABEL}`;
-}
-async function resolveDesktopBridgeLaunchCommand(options) {
-    if (options.executablePath) {
-        const executable = path.resolve(options.executablePath);
-        return await exists(executable)
-            ? { executable, arguments: [...(options.executableArguments || [])] }
-            : null;
-    }
-    const entry = String(process.argv[1] || '').trim();
-    const entryName = path.basename(entry).replace(/\.js$/i, '');
-    if (entry
-        && (entryName === 'sks' || entryName === 'sneakoscope')
-        && await exists(entry)) {
+function validateProviderSessionPins(value) {
+    const pins = Array.isArray(value) ? value : [];
+    if (pins.length > 10_000)
+        throw new Error('desktop_bridge_settings_session_pins_invalid');
+    const seen = new Set();
+    return pins.map((value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error('desktop_bridge_settings_session_pins_invalid');
+        const pin = value;
+        const allowed = new Set([
+            'thread_id', 'provider_id', 'public_model', 'upstream_model',
+            'catalog_generation', 'route_policy_generation', 'created_at'
+        ]);
+        const threadId = typeof pin.thread_id === 'string' ? pin.thread_id.trim() : '';
+        if (Object.keys(pin).some((key) => !allowed.has(key))
+            || !threadId
+            || threadId !== pin.thread_id
+            || threadId.length > 256
+            || !/^[A-Za-z0-9._:/-]+$/.test(threadId)
+            || seen.has(threadId)
+            || (pin.provider_id !== 'codex-lb' && pin.provider_id !== 'openrouter')
+            || canonicalizeBridgeModelId(pin.public_model) !== pin.public_model
+            || normalizeBridgeUpstreamModelId(pin.upstream_model) !== pin.upstream_model
+            || typeof pin.catalog_generation !== 'string'
+            || !pin.catalog_generation.trim()
+            || typeof pin.route_policy_generation !== 'string'
+            || !pin.route_policy_generation.trim()
+            || typeof pin.created_at !== 'string'
+            || !Number.isFinite(Date.parse(pin.created_at))) {
+            throw new Error('desktop_bridge_settings_session_pins_invalid');
+        }
+        seen.add(threadId);
         return {
-            executable: path.resolve(process.execPath),
-            arguments: [path.resolve(entry)]
+            thread_id: threadId,
+            provider_id: pin.provider_id,
+            public_model: pin.public_model,
+            upstream_model: pin.upstream_model,
+            catalog_generation: pin.catalog_generation,
+            route_policy_generation: pin.route_policy_generation,
+            created_at: pin.created_at
         };
-    }
-    const sks = await which('sks').catch(() => null);
-    if (sks)
-        return { executable: path.resolve(sks), arguments: [] };
-    return null;
-}
-async function inspectLaunchdService(options, service) {
-    if ((options.platform || process.platform) !== 'darwin')
-        return { loaded: false, running: false };
-    const run = options.run || runProcess;
-    const launchctl = options.launchctl || '/bin/launchctl';
-    const result = await run(launchctl, ['print', service], {
-        timeoutMs: 3_000,
-        maxOutputBytes: 32 * 1024
-    }).catch(() => null);
-    if (!result || result.code !== 0)
-        return { loaded: false, running: false };
-    const text = `${result.stdout || ''}\n${result.stderr || ''}`;
-    const state = text.match(/^[ \t]*state = ([^\n]+)/m)?.[1]?.trim() || null;
-    const pid = Number(text.match(/^[ \t]*pid = (\d+)/m)?.[1] || 0);
-    return { loaded: true, running: state === 'running' && pid > 0 };
-}
-async function waitForDesktopBridge(options) {
-    let status = await desktopBridgeServiceStatus(options);
-    for (let attempt = 0; attempt < 40 && !status.ok; attempt += 1) {
-        await delay(100);
-        status = await desktopBridgeServiceStatus(options);
-    }
-    return status;
-}
-async function removeStaleBridgeState(statePath, processExists) {
-    const state = await readDesktopBridgeState(statePath).catch(() => null);
-    if (!state || !(processExists || desktopBridgeProcessExists)(state.pid)) {
-        await fsp.unlink(statePath).catch(() => undefined);
-    }
-}
-async function waitForShutdownSignal(handle) {
-    await new Promise((resolve) => {
-        let settled = false;
-        const finish = () => {
-            if (settled)
-                return;
-            settled = true;
-            process.off('SIGINT', finish);
-            process.off('SIGTERM', finish);
-            resolve();
-        };
-        process.once('SIGINT', finish);
-        process.once('SIGTERM', finish);
-        handle.server.once('close', finish);
     });
 }
-function failedServiceStatus(input) {
-    return {
-        schema: CODEX_LB_DESKTOP_BRIDGE_SERVICE_SCHEMA,
-        ok: false,
-        supported: true,
-        installed: false,
-        loaded: false,
-        running: false,
-        status: input.status,
-        service: input.service,
-        paths: input.paths,
-        state: null,
-        settings: input.settings,
-        expected_config_generation: input.expectedConfigGeneration,
-        credential_source: input.credentialSource,
-        blockers: [input.blocker]
-    };
-}
-function bridgeStatusBlocker(status) {
-    if (status.status === 'missing')
-        return 'desktop_bridge_state_missing';
-    if (status.status === 'running')
-        return '';
-    return status.blocker;
-}
-function safeServiceError(error) {
-    const bridge = safeBridgeErrorCode(error);
-    if (bridge !== 'bridge_upstream_unavailable')
-        return bridge;
-    const message = error instanceof Error ? error.message : String(error);
-    return /^[a-z0-9_:-]+$/i.test(message) ? message : 'desktop_bridge_service_failed';
+async function prepareDesktopBridgeServicePaths(paths) {
+    await Promise.all([
+        ensurePrivateDirectory(path.dirname(paths.settings_path)),
+        ensurePrivateDirectory(path.dirname(paths.stdout_log_path)),
+        ensureDir(path.dirname(paths.launch_agent_path))
+    ]);
+    await Promise.all([
+        ensurePrivateLogFile(paths.stdout_log_path),
+        ensurePrivateLogFile(paths.stderr_log_path)
+    ]);
 }
-function failedProcess(error) {
-    return {
-        code: 1,
-        stdout: '',
-        stderr: safeServiceError(error),
-        stdoutBytes: 0,
-        stderrBytes: 0,
-        truncated: false,
-        timedOut: false
-    };
+async function ensurePrivateDirectory(directory) {
+    await fsp.mkdir(directory, { recursive: true, mode: 0o700 });
+    const stat = await fsp.lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('desktop_bridge_private_directory_invalid');
+    const expectedUid = typeof process.getuid === 'function' ? process.getuid() : null;
+    if (expectedUid !== null && stat.uid !== expectedUid)
+        throw new Error('desktop_bridge_private_directory_owner_mismatch');
+    if (process.platform !== 'win32')
+        await fsp.chmod(directory, 0o700);
 }
-function errorCode(error) {
-    return error && typeof error === 'object' && 'code' in error ? String(error.code) : '';
+async function ensurePrivateLogFile(file) {
+    const flags = fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT | (fsConstants.O_NOFOLLOW || 0);
+    const handle = await fsp.open(file, flags, 0o600);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error('desktop_bridge_log_not_regular_file');
+        const expectedUid = typeof process.getuid === 'function' ? process.getuid() : null;
+        if (expectedUid !== null && stat.uid !== expectedUid)
+            throw new Error('desktop_bridge_log_owner_mismatch');
+        if (process.platform !== 'win32')
+            await handle.chmod(0o600);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
 }
-function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+function normalizeProviderRegistrySnapshot(value) {
+    const registry = value;
+    if (!registry || registry.schema !== 'sks.desktop-bridge-provider-registry.v1'
+        || !registry.providers?.['codex-lb'] || !registry.providers.openrouter) {
+        throw new Error('desktop_bridge_settings_provider_registry_invalid');
+    }
+    const providers = Object.fromEntries(['codex-lb', 'openrouter'].map((providerId) => {
+        const provider = registry.providers[providerId];
+        const sourceCatalogGeneration = provider.source_catalog_generation ?? provider.catalog_generation ?? null;
+        const { catalog_generation: _legacyCatalogGeneration, ...rest } = provider;
+        return [providerId, { ...rest, source_catalog_generation: sourceCatalogGeneration }];
+    }));
+    return { ...registry, providers };
 }
+function overridePaths(base, options) { return { settings_path: options.settingsPath || base.settings_path, state_path: options.statePath || base.state_path, client_capability_path: options.clientCapabilityPath || base.client_capability_path, launch_agent_path: options.launchAgentPath || base.launch_agent_path, stdout_log_path: options.stdoutLogPath || base.stdout_log_path, stderr_log_path: options.stderrLogPath || base.stderr_log_path }; }
+function launchDomain(uid = typeof process.getuid === 'function' ? process.getuid() : 0) { return `gui/${uid}`; }
+function launchService(uid) { return `${launchDomain(uid)}/${DESKTOP_BRIDGE_LAUNCHD_LABEL}`; }
+async function resolveLaunchCommand(options) { if (options.executablePath)
+    return await exists(path.resolve(options.executablePath)) ? { executable: path.resolve(options.executablePath), arguments: [...(options.executableArguments || [])] } : null; const entry = String(process.argv[1] || ''); if (entry && ['sks', 'sneakoscope'].includes(path.basename(entry).replace(/\.js$/i, '')) && await exists(entry))
+    return { executable: path.resolve(process.execPath), arguments: [path.resolve(entry)] }; const sks = await which('sks').catch(() => null); return sks ? { executable: path.resolve(sks), arguments: [] } : null; }
+async function inspectLaunchd(options, service) { if ((options.platform || process.platform) !== 'darwin')
+    return { loaded: false, running: false }; const result = await (options.run || runProcess)(options.launchctl || '/bin/launchctl', ['print', service], { timeoutMs: 3_000, maxOutputBytes: 32 * 1024 }).catch(() => null); if (!result || result.code !== 0)
+    return { loaded: false, running: false }; const text = `${result.stdout}\n${result.stderr}`; return { loaded: true, running: /state = running/.test(text) && /pid = \d+/.test(text) }; }
+async function waitForBridge(options) { let status = await desktopBridgeServiceStatus(options); for (let i = 0; i < 40 && !status.ok; i += 1) {
+    await delay(100);
+    status = await desktopBridgeServiceStatus(options);
+} return status; }
+async function removeStaleState(file, probe) { const state = await readDesktopBridgeState(file).catch(() => null); if (!state || !(probe || desktopBridgeProcessExists)(state.pid))
+    await fsp.unlink(file).catch(() => undefined); }
+async function waitForShutdown(handle) { await new Promise((resolve) => { const done = () => { process.off('SIGINT', done); process.off('SIGTERM', done); resolve(); }; process.once('SIGINT', done); process.once('SIGTERM', done); handle.server.once('close', done); }); }
+function failedStatus(paths, settings, service, status, blocker) { return { schema: DESKTOP_BRIDGE_SERVICE_SCHEMA, ok: false, supported: true, installed: false, loaded: false, running: false, status, service, paths, state: null, settings, expected_config_generation: null, credential_source: null, blockers: [blocker] }; }
+function bridgeStatusBlocker(status) { return status.status === 'missing' ? 'desktop_bridge_state_missing' : status.status === 'running' ? '' : status.blocker; }
+function safeServiceError(error) { const bridge = safeBridgeErrorCode(error); if (bridge !== 'bridge_upstream_unavailable')
+    return bridge; const message = error instanceof Error ? error.message : String(error); return /^[a-z0-9_:-]+$/i.test(message) ? message : 'desktop_bridge_service_failed'; }
+function failedProcess(error) { return { code: 1, stdout: '', stderr: safeServiceError(error), stdoutBytes: 0, stderrBytes: 0, truncated: false, timedOut: false }; }
+function delay(ms) { return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms))); }