sneakoscope 8.1.2 → 8.2.0

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

@@ -0,0 +1,238 @@
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { DESKTOP_BRIDGE_MANAGED_BASE_URL_MARKER, DESKTOP_BRIDGE_MANAGED_MARKER, DESKTOP_BRIDGE_MANAGED_MODEL_CATALOG_MARKER, upsertDesktopBridgeManagedConfig } from '../../cli/install-helpers-codex-lb-config.js';
+import { safeWriteCodexConfigToml } from '../codex-runtime/codex-desktop-config-policy.js';
+import { messageOf as errorMessage } from '../errors/message.js';
+import { readText } from '../fsx.js';
+import { withFileLock } from '../locks/file-lock.js';
+import { captureCodexAuthSnapshot } from './desktop-auth-invariant.js';
+import { parseHistoricalProviderConfig, prepareHistoricalConfigForDesktopBridgeWriter } from './desktop-bridge-migration/historical-config.js';
+import { hasTopLevelMarker } from './desktop-bridge-migration/historical-toml.js';
+import { normalizedMetadataUpdates, sha256, validateMetadataUpdates, writeBufferAtomic } from './desktop-bridge-migration/metadata.js';
+import { authSemanticIdentityPreserved, buildDesktopBridgeMigrationReceipt } from './desktop-bridge-migration/receipt.js';
+import { backupDesktopBridgeMigrationFile, createDesktopBridgeUnificationReceiptId, desktopBridgeMigrationTransactionLockPath, desktopBridgeUnificationReceiptDir, fileSha256OrMissing, finalizeDesktopBridgeMigrationReceiptFiles, rollbackDesktopBridgeUnificationReceipt, writeDesktopBridgeUnificationReceipt } from './migration-receipt.js';
+export { inspectHistoricalDesktopBridgeIntent } from './desktop-bridge-migration/historical-config.js';
+export async function migrateDesktopBridgeConfig(input) {
+    const home = path.resolve(input.home || process.env.HOME || os.homedir());
+    return withFileLock({
+        lockPath: desktopBridgeMigrationTransactionLockPath(home),
+        timeoutMs: 30_000,
+        staleMs: 120_000
+    }, () => migrateDesktopBridgeConfigUnlocked(input));
+}
+async function migrateDesktopBridgeConfigUnlocked(input) {
+    const home = input.home || process.env.HOME || os.homedir();
+    const configPath = input.configPath || path.join(home, '.codex', 'config.toml');
+    const authPath = input.authPath || path.join(home, '.codex', 'auth.json');
+    const receiptDir = input.receiptDir || desktopBridgeUnificationReceiptDir(home);
+    const combinedCatalogPath = input.combinedCatalogPath
+        || path.join(home, '.codex', 'sks', 'sks-bridge-catalog.json');
+    const currentConfig = await readText(configPath, '');
+    const authBefore = await captureCodexAuthSnapshot({ home, authPath });
+    const historicalState = parseHistoricalProviderConfig(currentConfig);
+    const baseResult = {
+        schema: 'sks.desktop-bridge-unification-migration.v1',
+        config_path: configPath,
+        auth_path: authPath,
+        migrated_profiles: historicalState.migrated_profiles,
+        historical_gateway_auth_transport: historicalState.gateway_auth_transport,
+        credentials_deleted: false
+    };
+    if (historicalState.blockers.length > 0) {
+        return {
+            ...baseResult,
+            ok: false,
+            status: 'blocked',
+            managed_runtime: null,
+            receipt_path: null,
+            auth_semantic_identity_preserved: true,
+            blockers: historicalState.blockers
+        };
+    }
+    let nextConfig;
+    try {
+        validateConfigTarget(home, configPath);
+        const migrationInputConfig = prepareHistoricalConfigForDesktopBridgeWriter(currentConfig, historicalState);
+        nextConfig = upsertDesktopBridgeManagedConfig(migrationInputConfig, {
+            bridgeBaseUrl: input.bridgeBaseUrl,
+            combinedCatalogPath
+        });
+        validateMetadataUpdates(input.metadataUpdates || [], { home, configPath, authPath });
+    }
+    catch (error) {
+        const message = errorMessage(error);
+        return {
+            ...baseResult,
+            ok: false,
+            status: 'blocked',
+            managed_runtime: null,
+            receipt_path: null,
+            auth_semantic_identity_preserved: true,
+            blockers: [message.startsWith('historical_user_owned_config_conflict')
+                    ? 'historical_user_owned_config_conflict'
+                    : message],
+            error: message
+        };
+    }
+    const metadataUpdates = normalizedMetadataUpdates(input.metadataUpdates || []);
+    const metadataAlreadyCurrent = await Promise.all(metadataUpdates.map(async (update) => {
+        const currentSha = await fileSha256OrMissing(update.path);
+        return currentSha !== null && currentSha === sha256(update.text);
+    }));
+    const hasUnifiedMarkers = [
+        DESKTOP_BRIDGE_MANAGED_MARKER,
+        DESKTOP_BRIDGE_MANAGED_BASE_URL_MARKER,
+        DESKTOP_BRIDGE_MANAGED_MODEL_CATALOG_MARKER
+    ].every((marker) => hasTopLevelMarker(currentConfig, marker));
+    if (nextConfig === currentConfig && hasUnifiedMarkers && metadataAlreadyCurrent.every(Boolean)) {
+        const authAfter = await captureCodexAuthSnapshot({ home, authPath });
+        const authPreserved = authSemanticIdentityPreserved(authBefore, authAfter);
+        const configSha = sha256(currentConfig);
+        const configUnchanged = await fileSha256OrMissing(configPath) === configSha;
+        const authBytesUnchanged = authBefore.sha256 === authAfter.sha256;
+        if (!authPreserved || !configUnchanged || !authBytesUnchanged) {
+            return {
+                ...baseResult,
+                ok: false,
+                status: 'blocked',
+                managed_runtime: null,
+                receipt_path: null,
+                auth_semantic_identity_preserved: authPreserved,
+                blockers: [
+                    ...(!configUnchanged ? ['desktop_bridge_config_changed_during_noop'] : []),
+                    ...(!authPreserved ? ['desktop_oauth_identity_changed'] : []),
+                    ...(authPreserved && !authBytesUnchanged ? ['desktop_auth_changed_during_noop'] : [])
+                ]
+            };
+        }
+        return {
+            ...baseResult,
+            ok: true,
+            status: 'already_migrated',
+            managed_runtime: 'desktop-bridge',
+            receipt_path: null,
+            auth_semantic_identity_preserved: true,
+            blockers: []
+        };
+    }
+    const now = input.now || new Date();
+    const receiptId = createDesktopBridgeUnificationReceiptId(now);
+    const backupDir = path.join(receiptDir, receiptId, 'files');
+    const backupInputs = [
+        { kind: 'config', path: configPath, owned: false },
+        ...metadataUpdates.map((update) => ({ kind: update.kind, path: update.path, owned: true }))
+    ];
+    const backups = [];
+    const mutatedPaths = new Set();
+    try {
+        for (const entry of backupInputs) {
+            backups.push({
+                kind: entry.kind,
+                ...await backupDesktopBridgeMigrationFile(entry.path, backupDir, entry.owned)
+            });
+        }
+        const configWrite = await safeWriteCodexConfigToml(configPath, currentConfig, nextConfig, 'desktop-bridge-unification-migration', { verifyUnchangedBeforeWrite: true });
+        if (!configWrite.ok)
+            throw new Error(`desktop_bridge_config_write_failed:${configWrite.status}`);
+        if (configWrite.status === 'written')
+            mutatedPaths.add(path.resolve(configPath));
+        if (await fileSha256OrMissing(configPath) !== sha256(nextConfig)) {
+            throw new Error('desktop_bridge_config_readback_failed');
+        }
+        for (const update of metadataUpdates) {
+            const backup = backups.find((entry) => path.resolve(entry.path) === path.resolve(update.path));
+            if (!backup)
+                throw new Error(`desktop_bridge_metadata_backup_missing:${update.path}`);
+            if (await fileSha256OrMissing(update.path) !== backup.before_sha256) {
+                throw new Error(`desktop_bridge_metadata_changed_during_migration:${update.path}`);
+            }
+            if (sha256(update.text) !== backup.before_sha256) {
+                mutatedPaths.add(path.resolve(update.path));
+                await writeBufferAtomic(update.path, Buffer.from(update.text));
+                if (await fileSha256OrMissing(update.path) !== sha256(update.text)) {
+                    throw new Error(`desktop_bridge_metadata_readback_failed:${update.kind}`);
+                }
+            }
+        }
+        const authAfter = await captureCodexAuthSnapshot({ home, authPath });
+        if (!authSemanticIdentityPreserved(authBefore, authAfter)) {
+            throw new Error('desktop_oauth_identity_changed');
+        }
+        const finalized = await finalizeDesktopBridgeMigrationReceiptFiles(backups);
+        const rollbackFiles = finalized.map((file, index) => ({
+            ...file,
+            kind: backups[index].kind
+        }));
+        const receipt = buildDesktopBridgeMigrationReceipt({
+            receiptId,
+            createdAt: now.toISOString(),
+            configBeforeSha: sha256(currentConfig),
+            configAfterSha: sha256(nextConfig),
+            authBeforeSha: authBefore.sha256 || 'missing',
+            authAfterSha: authAfter.sha256 || 'missing',
+            historicalState,
+            newCatalogGeneration: input.newCatalogGeneration || null,
+            rollbackFiles
+        });
+        const receiptPath = await writeDesktopBridgeUnificationReceipt(receipt, { receiptDir });
+        return {
+            ...baseResult,
+            ok: true,
+            status: 'migrated',
+            managed_runtime: 'desktop-bridge',
+            receipt_path: receiptPath,
+            receipt,
+            auth_semantic_identity_preserved: true,
+            blockers: []
+        };
+    }
+    catch (error) {
+        const rollbackFiles = backups
+            .filter((file) => mutatedPaths.has(path.resolve(file.path)))
+            .map((file) => ({
+            ...file,
+            after_sha256: path.resolve(file.path) === path.resolve(configPath)
+                ? sha256(nextConfig)
+                : sha256(metadataUpdates.find((update) => path.resolve(update.path) === path.resolve(file.path))?.text || ''),
+            kind: file.kind
+        }));
+        const authAfter = await captureCodexAuthSnapshot({ home, authPath });
+        const provisional = buildDesktopBridgeMigrationReceipt({
+            receiptId,
+            createdAt: now.toISOString(),
+            configBeforeSha: sha256(currentConfig),
+            configAfterSha: await fileSha256OrMissing(configPath) || 'missing',
+            authBeforeSha: authBefore.sha256 || 'missing',
+            authAfterSha: authAfter.sha256 || 'missing',
+            historicalState,
+            newCatalogGeneration: input.newCatalogGeneration || null,
+            rollbackFiles,
+            blockers: ['desktop_bridge_unification_migration_failed'],
+            authSemanticIdentityPreserved: authSemanticIdentityPreserved(authBefore, authAfter)
+        });
+        const rollback = rollbackFiles.length > 0
+            ? await rollbackDesktopBridgeUnificationReceipt({ receipt: provisional, transactionLockHeld: true })
+            : undefined;
+        return {
+            ...baseResult,
+            ok: false,
+            status: 'failed',
+            managed_runtime: null,
+            receipt_path: null,
+            auth_semantic_identity_preserved: provisional.auth_semantic_identity_preserved,
+            blockers: [
+                'desktop_bridge_unification_migration_failed',
+                ...(rollback && !rollback.ok ? ['desktop_bridge_unification_rollback_failed'] : [])
+            ],
+            ...(rollback ? { rollback } : {}),
+            error: errorMessage(error)
+        };
+    }
+}
+function validateConfigTarget(home, configPath) {
+    const canonicalPath = path.join(path.resolve(home), '.codex', 'config.toml');
+    if (!path.isAbsolute(configPath) || path.resolve(configPath) !== canonicalPath) {
+        throw new Error('desktop_bridge_config_path_not_canonical');
+    }
+}

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

@@ -0,0 +1,257 @@
+import { readText } from '../../fsx.js';
+import { listOpenRouterModels } from '../../providers/openrouter/openrouter-account.js';
+import { buildCombinedBridgeCatalog, readActiveCombinedBridgeCatalog, stageCombinedBridgeCatalog } from '../combined-catalog.js';
+import { codexLbEnvPath, codexLbMetadataPath, loadCodexLbEnv, readCodexLbModelCatalog } from '../codex-lb-env.js';
+import { bootstrapExistingDesktopBridgeService, desktopBridgeServicePaths, desktopBridgeServiceStatus, resolveDesktopBridgeActivationSettings } from '../desktop-service.js';
+import { inspectHistoricalDesktopBridgeIntent, migrateDesktopBridgeConfig } from '../desktop-bridge-migration.js';
+import { rollbackDesktopBridgeUnificationReceipt } from '../migration-receipt.js';
+import { recordProviderCredentialValidation } from '../provider-credentials.js';
+import { bridgeProviderRegistryPath, buildStoredBridgeProviderRegistry, loadStoredBridgeProviderRegistry, resolveBridgeProviderRegistry, serializeStoredBridgeProviderRegistry } from '../provider-registry.js';
+import { buildBridgeRoutingPolicy, readBridgeRoutingPolicy } from '../provider-route-policy.js';
+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';
+export async function syncCatalog(options) {
+    const result = await syncCatalogInternal(options);
+    const status = await desktopBridgeStatusV3(options);
+    const activation = result.activation && typeof result.activation === 'object'
+        ? result.activation
+        : {};
+    return commandResult('catalog.sync', result.ok === true, status, { catalog_sync: result }, result.ok === true ? [] : stringArray(activation.blockers), options);
+}
+export async function syncCatalogInternal(options) {
+    const paths = controllerPaths(options);
+    const historicalIntent = inspectHistoricalDesktopBridgeIntent(await readText(paths.configPath, ''));
+    if (historicalIntent.blockers.length > 0)
+        return blockedSync(historicalIntent, historicalIntent.blockers);
+    const rawCredentials = await resolveRawCredentials(options, paths);
+    const storedRegistryRead = await loadStoredBridgeProviderRegistry({ home: paths.home });
+    if (storedRegistryRead.blockers.length > 0)
+        return blockedSync(historicalIntent, storedRegistryRead.blockers);
+    const storedRegistry = storedRegistryRead.registry || buildStoredBridgeProviderRegistry({
+        credentials: rawCredentials,
+        overrides: historicalIntent.providers
+    });
+    const initialRegistry = await resolveBridgeProviderRegistry({
+        home: paths.home,
+        credentials: rawCredentials,
+        storedRegistry
+    });
+    const catalogs = await fetchProviderCatalogs(initialRegistry, rawCredentials, paths, options);
+    const credentials = await resolveValidatedCredentials(options, paths);
+    const registry = await resolveBridgeProviderRegistry({ home: paths.home, credentials, storedRegistry });
+    const build = buildCombinedBridgeCatalog(registry, { catalogs, created_at: nowIso(options) });
+    const staging = await stageCombinedBridgeCatalog({
+        build,
+        catalogPath: paths.catalogPath,
+        routeIndexPath: paths.routeIndexPath
+    });
+    if (!staging.staged || !staging.catalog_path || !staging.pointer_text) {
+        return { ok: false, build, activation: activationResult(staging, false), migration: null };
+    }
+    const priorPolicy = await readBridgeRoutingPolicy(paths.routePolicyPath);
+    const readyProviders = ['codex-lb', 'openrouter'].filter((providerId) => registry.profiles[providerId].enabled
+        && registry.profiles[providerId].state === 'ready'
+        && Object.values(build.route_index.routes).some((route) => route.provider_id === providerId));
+    const previousDefault = priorPolicy.policy?.default_provider_id || null;
+    const historicalDefault = historicalIntent.default_provider_id;
+    const defaultProvider = previousDefault && readyProviders.includes(previousDefault)
+        ? previousDefault
+        : historicalDefault && readyProviders.includes(historicalDefault) ? historicalDefault
+            : readyProviders.length === 1 ? readyProviders[0] || null : null;
+    const policy = buildBridgeRoutingPolicy({
+        route_index: build.route_index,
+        catalog_generation: build.catalog.generation,
+        default_provider_id: defaultProvider,
+        changed_at: nowIso(options)
+    });
+    let settings;
+    let managedBridgeBaseUrl;
+    try {
+        settings = await resolveDesktopBridgeActivationSettings({
+            ...options,
+            home: paths.home,
+            providerRegistry: providerRegistrySnapshot(registry, build.route_index),
+            routePolicy: policy
+        });
+        managedBridgeBaseUrl = await bridgeBaseUrl(settings, { ...options, home: paths.home });
+    }
+    catch (error) {
+        const blocker = safeCode(error, 'desktop_bridge_client_capability_invalid');
+        return {
+            ok: false,
+            build,
+            activation: activationResult(staging, false, [blocker]),
+            migration: null,
+            active_generation_preserved: true
+        };
+    }
+    const migration = await migrateDesktopBridgeConfig({
+        home: paths.home,
+        configPath: paths.configPath,
+        authPath: paths.authPath,
+        receiptDir: paths.receiptDir,
+        bridgeBaseUrl: managedBridgeBaseUrl,
+        combinedCatalogPath: staging.catalog_path,
+        newCatalogGeneration: build.catalog.generation,
+        metadataUpdates: [
+            {
+                kind: 'provider_registry',
+                path: bridgeProviderRegistryPath(paths.home),
+                text: serializeStoredBridgeProviderRegistry(storedRegistry)
+            },
+            { kind: 'catalog_binding', path: staging.pointer_path, text: staging.pointer_text },
+            { kind: 'route_policy', path: paths.routePolicyPath, text: `${JSON.stringify(policy, null, 2)}\n` },
+            { kind: 'bridge_settings', path: desktopBridgeServicePaths(paths.home).settings_path, text: serializedSettings(settings) }
+        ]
+    });
+    if (!migration.ok) {
+        return {
+            ok: false,
+            build,
+            activation: activationResult(staging, false, migration.blockers),
+            migration,
+            active_generation_preserved: true
+        };
+    }
+    const active = await readActiveCombinedBridgeCatalog(paths.catalogPath, paths.routeIndexPath);
+    if (!active.ok
+        || active.catalog.generation !== build.catalog.generation
+        || active.route_index.generation !== build.route_index.generation) {
+        const rollback = migration.receipt
+            ? await rollbackDesktopBridgeUnificationReceipt({ receipt: migration.receipt })
+            : null;
+        return {
+            ok: false,
+            build,
+            activation: activationResult(staging, false, ['combined_catalog_activation_verification_failed']),
+            migration,
+            rollback,
+            active_generation_preserved: rollback?.ok === true
+        };
+    }
+    const serviceBefore = await (options.serviceStatusImpl || desktopBridgeServiceStatus)({ ...options, home: paths.home });
+    if (serviceBefore.installed || serviceBefore.running) {
+        await (options.bootstrapServiceImpl || bootstrapExistingDesktopBridgeService)({
+            ...options,
+            home: paths.home,
+            providerRegistry: providerRegistrySnapshot(registry, build.route_index),
+            routePolicy: policy
+        });
+    }
+    return { ok: true, build, activation: activationResult(staging, true), migration };
+}
+function blockedSync(historicalIntent, blockers) {
+    return {
+        ok: false,
+        historical_intent: historicalIntent,
+        activation: {
+            schema: 'sks.bridge-combined-catalog-activation.v1',
+            activated: false,
+            blockers
+        },
+        migration: null
+    };
+}
+function activationResult(staging, activated, blockers = staging.blockers) {
+    return {
+        schema: 'sks.bridge-combined-catalog-activation.v1',
+        activated,
+        generation: activated ? staging.generation : null,
+        previous_generation: staging.previous_generation,
+        catalog_path: activated ? staging.catalog_path : null,
+        route_index_path: activated ? staging.route_index_path : null,
+        pointer_path: staging.pointer_path,
+        blockers: unique(blockers)
+    };
+}
+async function fetchProviderCatalogs(registry, credentials, paths, options) {
+    const checkedAt = nowIso(options);
+    const expiresAt = new Date(new Date(checkedAt).getTime() + 15 * 60_000).toISOString();
+    const rows = await Promise.all(['codex-lb', 'openrouter'].map(async (providerId) => {
+        const profile = registry.profiles[providerId];
+        const credential = credentials[providerId];
+        if (!profile.enabled)
+            return [providerId, emptyProviderCatalog(providerId, 'not_started', checkedAt, [])];
+        if (!credential.secret) {
+            return [providerId, emptyProviderCatalog(providerId, 'failed', checkedAt, [`${providerCode(providerId)}_credential_missing`])];
+        }
+        if (providerId === 'codex-lb') {
+            const loaded = await loadCodexLbEnv({
+                home: paths.home,
+                envPath: options.envPath || codexLbEnvPath(paths.home),
+                metadataPath: options.metadataPath || codexLbMetadataPath(paths.home),
+                processEnv: controllerEnv(options)
+            });
+            const result = await readCodexLbModelCatalog({
+                loadedEnv: loaded,
+                ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+                ...(options.codexLbLookup ? { lookup: options.codexLbLookup } : {}),
+                timeoutMs: timeoutMs(options),
+                gatewayAuthTransport: profile.endpoint.auth_transport === 'x-codex-lb-api-key'
+                    ? 'x-codex-lb-api-key' : 'authorization-bearer'
+            });
+            await recordProviderCredentialValidation({
+                provider_id: providerId,
+                credential,
+                state: result.ok ? 'ready' : validationFailureState(result.blockers),
+                checked_at: checkedAt,
+                blockers: result.blockers,
+                home: paths.home,
+                validationPath: paths.validationPath
+            });
+            return [providerId, {
+                    provider_id: providerId,
+                    state: result.ok ? 'verified' : 'failed',
+                    generation: result.ok ? sha256Stable({ provider_id: providerId, models: result.models }) : null,
+                    models: { models: result.models },
+                    checked_at: checkedAt,
+                    expires_at: expiresAt,
+                    blockers: result.blockers,
+                    warnings: []
+                }];
+        }
+        const result = await listOpenRouterModels({
+            env: controllerEnv(options),
+            ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+            timeoutMs: timeoutMs(options)
+        });
+        await recordProviderCredentialValidation({
+            provider_id: providerId,
+            credential,
+            state: result.ok ? 'ready' : validationFailureState(result.blockers),
+            checked_at: checkedAt,
+            blockers: result.blockers,
+            warnings: result.warnings,
+            home: paths.home,
+            validationPath: paths.validationPath
+        });
+        return [providerId, {
+                provider_id: providerId,
+                state: result.ok ? 'verified' : 'failed',
+                generation: result.ok ? sha256Stable({ provider_id: providerId, models: result.models }) : null,
+                models: result.models,
+                checked_at: checkedAt,
+                expires_at: expiresAt,
+                blockers: result.blockers,
+                warnings: result.warnings
+            }];
+    }));
+    return Object.fromEntries(rows);
+}
+function emptyProviderCatalog(providerId, state, checkedAt, blockers) {
+    return {
+        provider_id: providerId,
+        state,
+        generation: null,
+        models: [],
+        checked_at: checkedAt,
+        expires_at: null,
+        blockers,
+        warnings: []
+    };
+}
+function validationFailureState(blockers) {
+    return blockers.some((blocker) => /(?:401|403|auth|rejected|invalid_key|unauthorized)/i.test(blocker))
+        ? 'rejected' : 'unavailable';
+}

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

@@ -0,0 +1,62 @@
+import fs from 'node:fs/promises';
+import { writeJsonAtomic } from '../../fsx.js';
+import { validateDesktopCapabilityReportV3 } from '../bridge-runtime-validation.js';
+const LAST_DIAGNOSTIC_SCHEMA = 'sks.desktop-bridge-last-diagnostic.v1';
+const MAX_DIAGNOSTIC_BYTES = 4 * 1024 * 1024;
+export async function writeLastDiagnostic(file, value) {
+    await writeJsonAtomic(file, value, { mode: 0o600 });
+    await fs.chmod(file, 0o600);
+}
+export async function readLastDiagnostic(file, currentCatalogGeneration, currentProcessGeneration, lastVerifiedProbeIds) {
+    const stat = await fs.lstat(file).catch(() => null);
+    if (!stat)
+        return null;
+    const expectedUid = typeof process.getuid === 'function' ? process.getuid() : null;
+    if (!stat.isFile() || stat.isSymbolicLink()
+        || stat.size > MAX_DIAGNOSTIC_BYTES
+        || (expectedUid !== null && stat.uid !== expectedUid)
+        || (process.platform !== 'win32' && (stat.mode & 0o777) !== 0o600))
+        return null;
+    try {
+        const value = JSON.parse(await fs.readFile(file, 'utf8'));
+        const validation = validateDesktopCapabilityReportV3(value.report);
+        if (value.schema !== LAST_DIAGNOSTIC_SCHEMA
+            || !validation.ok
+            || !desktopBridgeDiagnosticBindingCurrentV3(value, currentCatalogGeneration, currentProcessGeneration, lastVerifiedProbeIds))
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+export function desktopBridgeReportReadinessV3(report) {
+    const transportVerified = report?.summary.transport_level_satisfied === true
+        && (report.requested_level === 'transport' || report.requested_level === 'deep');
+    return {
+        bridge_ready: transportVerified && report?.summary.bridge_ready === true,
+        active_routes_ready: transportVerified && report?.summary.active_routes_ready === true
+    };
+}
+export function desktopBridgeDiagnosticBindingCurrentV3(value, currentCatalogGeneration, currentProcessGeneration, lastVerifiedProbeIds) {
+    const hasVerifiedProbeBinding = value.report.summary.transport_level_satisfied !== true
+        || lastVerifiedProbeIds.some((probeId) => probeId.startsWith(`${value.report.report_id}:`));
+    return Boolean(currentProcessGeneration
+        && value.catalog_generation === currentCatalogGeneration
+        && value.process_generation === currentProcessGeneration
+        && hasVerifiedProbeBinding);
+}
+export function verifiedLiveProbeIds(report) {
+    const scopes = [
+        report.bridge,
+        report.native_identity,
+        report.providers['codex-lb'],
+        report.providers.openrouter,
+        report.combined_catalog
+    ];
+    return scopes.flatMap((scope) => Object.values(scope.capabilities))
+        .filter((probe) => probe.state === 'verified'
+        && ['transport', 'deep_probe', 'artifact'].includes(probe.source))
+        .map((probe) => `${report.report_id}:${probe.scope}:${probe.capability}`)
+        .sort();
+}