sneakoscope 8.1.2 → 8.2.0

package/dist/core/codex-lb/migration-receipt.js

@@ -1,16 +1,21 @@
 import { createHash, randomUUID } 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 { messageOf as errorMessage } from '../errors/message.js';
-import { ensureDir, exists, readText, writeTextAtomic } from '../fsx.js';
-export function codexLbMigrationReceiptDir(home = process.env.HOME || os.homedir()) {
-    return path.join(home, '.codex', 'sks-codex-lb-migrations');
+import { ensureDir, exists, writeTextAtomic } from '../fsx.js';
+import { withFileLock } from '../locks/file-lock.js';
+export function desktopBridgeUnificationReceiptDir(home = process.env.HOME || os.homedir()) {
+    return path.join(home, '.codex', 'sks-desktop-bridge-migrations');
 }
-export function createCodexLbMigrationReceiptId(now = new Date()) {
+export function desktopBridgeMigrationTransactionLockPath(home) {
+    return path.join(path.resolve(home), '.codex', 'sks', 'locks', 'desktop-bridge-migration.lock');
+}
+export function createDesktopBridgeUnificationReceiptId(now = new Date()) {
     return `${now.toISOString().replace(/[-:.TZ]/g, '')}-${randomUUID().slice(0, 8)}`;
 }
-export async function backupCodexLbMigrationFile(filePath, backupDir, ownedBySks) {
+export async function backupDesktopBridgeMigrationFile(filePath, backupDir, ownedBySks) {
     const before = await readRegularFileOrMissing(filePath);
     if (!before) {
         return {
@@ -20,7 +25,7 @@ export async function backupCodexLbMigrationFile(filePath, backupDir, ownedBySks
             owned_by_sks: ownedBySks
         };
     }
-    await ensureDir(backupDir);
+    await ensurePrivateDirectory(backupDir);
     const backupPath = path.join(backupDir, `${createHash('sha256').update(path.resolve(filePath)).digest('hex').slice(0, 16)}.before`);
     await writeBufferAtomic(backupPath, before, 0o600);
     return {
@@ -30,160 +35,337 @@ export async function backupCodexLbMigrationFile(filePath, backupDir, ownedBySks
         owned_by_sks: ownedBySks
     };
 }
-export async function finalizeCodexLbMigrationReceiptFiles(backups) {
+export async function finalizeDesktopBridgeMigrationReceiptFiles(backups) {
     return Promise.all(backups.map(async (backup) => ({
         ...backup,
         after_sha256: await fileSha256OrMissing(backup.path)
     })));
 }
-export async function writeCodexLbMigrationReceipt(receipt, input = {}) {
-    validateReceipt(receipt);
-    const receiptDir = input.receiptDir || codexLbMigrationReceiptDir();
-    const receiptPath = input.receiptPath || path.join(receiptDir, `${receipt.id}.json`);
+export async function writeDesktopBridgeUnificationReceipt(receipt, input = {}) {
+    normalizeHistoricalSelectionCompatibility(receipt);
+    validateDesktopBridgeUnificationReceipt(receipt);
+    const receiptDir = input.receiptDir || desktopBridgeUnificationReceiptDir();
+    const receiptPath = input.receiptPath || path.join(receiptDir, `${receipt.receipt_id}.json`);
+    await ensurePrivateDirectory(path.dirname(receiptPath));
     await writeTextAtomic(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
     await fsp.chmod(receiptPath, 0o600).catch(() => { });
     return receiptPath;
 }
-export async function readCodexLbMigrationReceipt(receiptPath) {
-    const text = await readText(receiptPath);
+export async function readDesktopBridgeUnificationReceipt(receiptPath) {
+    const text = (await readSecureOwnerFile(receiptPath, 1024 * 1024, 'desktop_bridge_receipt')).toString('utf8');
     let parsed;
     try {
         parsed = JSON.parse(text);
     }
     catch {
-        throw new Error('invalid_codex_lb_migration_receipt');
+        throw new Error('invalid_desktop_bridge_unification_receipt');
     }
-    validateReceipt(parsed);
+    normalizeHistoricalSelectionCompatibility(parsed);
+    validateDesktopBridgeUnificationReceipt(parsed);
     return parsed;
 }
-export async function rollbackCodexLbMigrationReceipt(input) {
+export async function rollbackDesktopBridgeUnificationReceipt(input) {
     let receipt;
     try {
         if (input.receipt) {
-            validateReceipt(input.receipt);
+            normalizeHistoricalSelectionCompatibility(input.receipt);
+            validateDesktopBridgeUnificationReceipt(input.receipt);
             receipt = input.receipt;
         }
         else if (input.receiptPath) {
-            receipt = await readCodexLbMigrationReceipt(input.receiptPath);
+            receipt = await readDesktopBridgeUnificationReceipt(input.receiptPath);
         }
         else {
-            throw new Error('missing_codex_lb_migration_receipt');
+            throw new Error('missing_desktop_bridge_unification_receipt');
         }
     }
     catch (error) {
         return {
-            schema: 'sks.codex-lb-migration-rollback.v1',
+            schema: 'sks.desktop-bridge-unification-rollback.v1',
             ok: false,
             status: 'invalid_receipt',
             receipt_id: null,
             restored_files: [],
+            credentials_overwritten: false,
+            auth_overwritten: false,
             conflicts: [],
             error: errorMessage(error)
         };
     }
-    const conflicts = [];
-    for (const file of receipt.files) {
-        const currentSha = await fileSha256OrMissing(file.path);
-        if (currentSha !== file.after_sha256) {
-            conflicts.push({
-                path: file.path,
-                expected_after_sha256: file.after_sha256,
-                current_sha256: currentSha,
-                reason: 'current_file_changed_after_migration'
-            });
-            continue;
-        }
-        if (file.before_sha256 !== null) {
-            if (!file.backup_path || !(await exists(file.backup_path))) {
-                conflicts.push({
-                    path: file.path,
-                    expected_after_sha256: file.after_sha256,
-                    current_sha256: currentSha,
-                    reason: 'before_backup_missing'
-                });
-                continue;
-            }
-            const backupSha = await fileSha256OrMissing(file.backup_path);
-            if (backupSha !== file.before_sha256) {
-                conflicts.push({
-                    path: file.path,
-                    expected_after_sha256: file.after_sha256,
-                    current_sha256: currentSha,
-                    reason: 'before_backup_hash_mismatch'
-                });
-            }
-        }
-    }
-    if (conflicts.length) {
+    if (receipt.migration_status === 'already_migrated') {
         return {
-            schema: 'sks.codex-lb-migration-rollback.v1',
-            ok: false,
-            status: 'rollback_conflict',
-            receipt_id: receipt.id,
+            schema: 'sks.desktop-bridge-unification-rollback.v1',
+            ok: true,
+            status: 'nothing_to_rollback',
+            receipt_id: receipt.receipt_id,
             restored_files: [],
-            conflicts
+            credentials_overwritten: false,
+            auth_overwritten: false,
+            conflicts: []
         };
     }
-    const currentBytes = new Map();
-    for (const file of receipt.files)
-        currentBytes.set(file.path, await readRegularFileOrMissing(file.path));
-    const restoredFiles = [];
+    if (input.transactionLockHeld !== true) {
+        const configTarget = receipt.rollback_metadata.files.find((file) => file.kind === 'config');
+        if (!configTarget) {
+            return {
+                schema: 'sks.desktop-bridge-unification-rollback.v1',
+                ok: false,
+                status: 'invalid_receipt',
+                receipt_id: receipt.receipt_id,
+                restored_files: [],
+                credentials_overwritten: false,
+                auth_overwritten: false,
+                conflicts: [],
+                error: 'desktop_bridge_rollback_config_target_missing'
+            };
+        }
+        const home = path.dirname(path.dirname(path.resolve(configTarget.path)));
+        return withFileLock({
+            lockPath: desktopBridgeMigrationTransactionLockPath(home),
+            timeoutMs: 30_000,
+            staleMs: 120_000
+        }, () => rollbackDesktopBridgeUnificationReceipt({
+            receipt,
+            ...(input.beforeTargetLocks ? { beforeTargetLocks: input.beforeTargetLocks } : {}),
+            transactionLockHeld: true
+        }));
+    }
+    const files = receipt.rollback_metadata.files;
+    const initial = await inspectRollbackFiles(files);
+    if (initial.conflicts.length)
+        return rollbackConflict(receipt.receipt_id, initial.conflicts);
     try {
-        for (const file of receipt.files) {
-            if (file.before_sha256 === null) {
-                await fsp.rm(file.path, { force: true });
-            }
-            else {
-                const backupPath = file.backup_path;
-                if (!backupPath)
-                    throw new Error(`before_backup_missing:${file.path}`);
-                await writeBufferAtomic(file.path, await fsp.readFile(backupPath), 0o600);
+        await input.beforeTargetLocks?.();
+        return await withRollbackTargetLocks(files, async () => {
+            const locked = await inspectRollbackFiles(files, initial.snapshots);
+            if (locked.conflicts.length)
+                return rollbackConflict(receipt.receipt_id, locked.conflicts);
+            const restoredFiles = [];
+            try {
+                for (const file of files) {
+                    if (file.before_sha256 === null) {
+                        await fsp.rm(file.path, { force: true });
+                    }
+                    else {
+                        if (!file.backup_path)
+                            throw new Error(`before_backup_missing:${file.path}`);
+                        const backup = locked.backupBytes.get(path.resolve(file.path));
+                        if (!backup)
+                            throw new Error(`before_backup_unavailable:${file.path}`);
+                        await writeBufferAtomic(file.path, backup, 0o600);
+                    }
+                    if ((await fileSha256OrMissing(file.path)) !== file.before_sha256) {
+                        throw new Error(`rollback_readback_failed:${file.path}`);
+                    }
+                    restoredFiles.push(file.path);
+                }
             }
-            if ((await fileSha256OrMissing(file.path)) !== file.before_sha256) {
-                throw new Error(`rollback_readback_failed:${file.path}`);
+            catch (error) {
+                for (const file of files) {
+                    const snapshot = locked.snapshots.get(path.resolve(file.path));
+                    try {
+                        if (!snapshot || snapshot.bytes === null)
+                            await fsp.rm(file.path, { force: true });
+                        else
+                            await writeBufferAtomic(file.path, snapshot.bytes, 0o600);
+                    }
+                    catch { }
+                }
+                return {
+                    schema: 'sks.desktop-bridge-unification-rollback.v1',
+                    ok: false,
+                    status: 'rollback_failed',
+                    receipt_id: receipt.receipt_id,
+                    restored_files: [],
+                    credentials_overwritten: false,
+                    auth_overwritten: false,
+                    conflicts: [],
+                    error: errorMessage(error)
+                };
             }
-            restoredFiles.push(file.path);
-        }
+            return {
+                schema: 'sks.desktop-bridge-unification-rollback.v1',
+                ok: true,
+                status: 'rolled_back',
+                receipt_id: receipt.receipt_id,
+                restored_files: restoredFiles,
+                credentials_overwritten: false,
+                auth_overwritten: false,
+                conflicts: []
+            };
+        });
     }
     catch (error) {
-        for (const [filePath, bytes] of currentBytes) {
-            try {
-                if (bytes === null)
-                    await fsp.rm(filePath, { force: true });
-                else
-                    await writeBufferAtomic(filePath, bytes, 0o600);
-            }
-            catch { }
-        }
         return {
-            schema: 'sks.codex-lb-migration-rollback.v1',
+            schema: 'sks.desktop-bridge-unification-rollback.v1',
             ok: false,
             status: 'rollback_failed',
-            receipt_id: receipt.id,
+            receipt_id: receipt.receipt_id,
             restored_files: [],
+            credentials_overwritten: false,
+            auth_overwritten: false,
             conflicts: [],
             error: errorMessage(error)
         };
     }
+}
+async function inspectRollbackFiles(files, expectedSnapshots) {
+    const backups = await inspectRollbackBackups(files);
+    const targets = await inspectRollbackTargets(files, expectedSnapshots);
     return {
-        schema: 'sks.codex-lb-migration-rollback.v1',
-        ok: true,
-        status: 'rolled_back',
-        receipt_id: receipt.id,
-        restored_files: restoredFiles,
-        conflicts: []
+        snapshots: targets.snapshots,
+        backupBytes: backups.backupBytes,
+        conflicts: [...backups.conflicts, ...targets.conflicts]
     };
 }
+async function inspectRollbackBackups(files) {
+    const backupBytes = new Map();
+    const conflicts = [];
+    for (const file of files) {
+        if (file.before_sha256 === null)
+            continue;
+        const resolved = path.resolve(file.path);
+        if (!file.backup_path || !(await exists(file.backup_path))) {
+            conflicts.push(rollbackFileConflict(file, null, 'before_backup_missing'));
+            continue;
+        }
+        let backup;
+        try {
+            backup = await readSecureOwnerFile(file.backup_path, 16 * 1024 * 1024, 'desktop_bridge_backup');
+        }
+        catch {
+            conflicts.push(rollbackFileConflict(file, null, 'before_backup_unsafe'));
+            continue;
+        }
+        if (sha256(backup) !== file.before_sha256) {
+            conflicts.push(rollbackFileConflict(file, null, 'before_backup_hash_mismatch'));
+            continue;
+        }
+        backupBytes.set(resolved, backup);
+    }
+    return { backupBytes, conflicts };
+}
+async function inspectRollbackTargets(files, expectedSnapshots) {
+    const snapshots = new Map();
+    const conflicts = [];
+    for (const file of files) {
+        const resolved = path.resolve(file.path);
+        let snapshot;
+        try {
+            snapshot = await readSecureRollbackTarget(resolved);
+            snapshots.set(resolved, snapshot);
+        }
+        catch {
+            conflicts.push(rollbackFileConflict(file, null, 'current_file_unsafe'));
+            continue;
+        }
+        if (snapshot.sha256 !== file.after_sha256) {
+            conflicts.push(rollbackFileConflict(file, snapshot.sha256, 'current_file_changed_after_migration'));
+            continue;
+        }
+        const expected = expectedSnapshots?.get(resolved);
+        if (expected && !sameRollbackTargetIdentity(expected, snapshot)) {
+            conflicts.push(rollbackFileConflict(file, snapshot.sha256, 'current_file_identity_changed_during_rollback'));
+        }
+    }
+    return { snapshots, conflicts };
+}
+async function readSecureRollbackTarget(filePath) {
+    const parent = await fsp.lstat(path.dirname(filePath));
+    const expectedUid = typeof process.getuid === 'function' ? process.getuid() : null;
+    if (!parent.isDirectory() || parent.isSymbolicLink() || (expectedUid !== null && parent.uid !== expectedUid)) {
+        throw new Error(`desktop_bridge_rollback_parent_unsafe:${filePath}`);
+    }
+    const parentIdentity = parentStatIdentity(parent);
+    let entry;
+    try {
+        entry = await fsp.lstat(filePath);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return { bytes: null, sha256: null, identity: null, parent_identity: parentIdentity };
+        }
+        throw error;
+    }
+    if (!entry.isFile() || entry.isSymbolicLink())
+        throw new Error(`desktop_bridge_rollback_target_unsafe:${filePath}`);
+    const flags = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0);
+    const handle = await fsp.open(filePath, flags);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile()
+            || stat.dev !== entry.dev
+            || stat.ino !== entry.ino
+            || (expectedUid !== null && stat.uid !== expectedUid)
+            || (process.platform !== 'win32' && (stat.mode & 0o077) !== 0)) {
+            throw new Error(`desktop_bridge_rollback_target_unsafe:${filePath}`);
+        }
+        const bytes = await handle.readFile();
+        return {
+            bytes,
+            sha256: sha256(bytes),
+            identity: statIdentity(stat),
+            parent_identity: parentIdentity
+        };
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+function statIdentity(stat) {
+    return [stat.dev, stat.ino, stat.uid, stat.mode & 0o777, stat.size, stat.mtimeMs, stat.ctimeMs].join(':');
+}
+function parentStatIdentity(stat) {
+    return [stat.dev, stat.ino, stat.uid, stat.mode & 0o777].join(':');
+}
+function sameRollbackTargetIdentity(before, after) {
+    return before.identity === after.identity && before.parent_identity === after.parent_identity;
+}
+function rollbackFileConflict(file, currentSha, reason) {
+    return {
+        path: file.path,
+        expected_after_sha256: file.after_sha256,
+        current_sha256: currentSha,
+        reason
+    };
+}
+function rollbackConflict(receiptId, conflicts) {
+    return {
+        schema: 'sks.desktop-bridge-unification-rollback.v1',
+        ok: false,
+        status: 'rollback_conflict',
+        receipt_id: receiptId,
+        restored_files: [],
+        credentials_overwritten: false,
+        auth_overwritten: false,
+        conflicts
+    };
+}
+export function desktopBridgeRollbackTargetLockPath(filePath) {
+    return `${path.resolve(filePath)}.lock`;
+}
+async function withRollbackTargetLocks(files, operation) {
+    const targets = [...new Set(files.map((file) => path.resolve(file.path)))]
+        .sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+    const acquire = async (index) => {
+        const target = targets[index];
+        if (!target)
+            return operation();
+        return withFileLock({
+            lockPath: desktopBridgeRollbackTargetLockPath(target),
+            timeoutMs: 10_000,
+            staleMs: 60_000
+        }, () => acquire(index + 1));
+    };
+    return acquire(0);
+}
 export async function fileSha256OrMissing(filePath) {
     const bytes = await readRegularFileOrMissing(filePath);
     return bytes === null ? null : sha256(bytes);
 }
 async function readRegularFileOrMissing(filePath) {
     try {
-        const stat = await fsp.lstat(filePath);
-        if (!stat.isFile() || stat.isSymbolicLink())
-            throw new Error(`migration_file_not_regular:${filePath}`);
-        return await fsp.readFile(filePath);
+        return await readFileWithoutFollowingSymlinks(filePath, Number.MAX_SAFE_INTEGER, 'migration_file');
     }
     catch (error) {
         if (isMissingFileError(error))
@@ -191,6 +373,44 @@ async function readRegularFileOrMissing(filePath) {
         throw error;
     }
 }
+async function readSecureOwnerFile(filePath, maxBytes, prefix) {
+    return readFileWithoutFollowingSymlinks(filePath, maxBytes, prefix, true);
+}
+async function readFileWithoutFollowingSymlinks(filePath, maxBytes, prefix, ownerOnly = false) {
+    const flags = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0);
+    const handle = await fsp.open(filePath, flags);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error(`${prefix}_not_regular:${filePath}`);
+        if (stat.size > maxBytes)
+            throw new Error(`${prefix}_too_large:${filePath}`);
+        if (ownerOnly) {
+            const expectedUid = typeof process.getuid === 'function' ? process.getuid() : null;
+            if (expectedUid !== null && stat.uid !== expectedUid)
+                throw new Error(`${prefix}_owner_mismatch:${filePath}`);
+            if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0)
+                throw new Error(`${prefix}_permissions_unsafe:${filePath}`);
+        }
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+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:${directory}`);
+    }
+    const expectedUid = typeof process.getuid === 'function' ? process.getuid() : null;
+    if (expectedUid !== null && stat.uid !== expectedUid) {
+        throw new Error(`desktop_bridge_private_directory_owner_mismatch:${directory}`);
+    }
+    if (process.platform !== 'win32')
+        await fsp.chmod(directory, 0o700);
+}
 async function writeBufferAtomic(filePath, bytes, mode) {
     await ensureDir(path.dirname(filePath));
     const tempPath = `${filePath}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
@@ -212,31 +432,253 @@ async function writeBufferAtomic(filePath, bytes, mode) {
         throw error;
     }
 }
-function validateReceipt(value) {
-    if (!value || typeof value !== 'object')
-        throw new Error('invalid_codex_lb_migration_receipt');
+function validateDesktopBridgeUnificationReceipt(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('invalid_desktop_bridge_unification_receipt');
+    }
     const receipt = value;
-    if (receipt.schema !== 'sks.codex-lb-migration-receipt.v1'
-        || typeof receipt.id !== 'string'
-        || !receipt.id
+    if (receipt.schema !== 'sks.desktop-bridge-unification-receipt.v1'
+        || typeof receipt.receipt_id !== 'string'
+        || !/^[A-Za-z0-9._-]{1,160}$/.test(receipt.receipt_id)
         || typeof receipt.created_at !== 'string'
-        || typeof receipt.from_mode !== 'string'
-        || typeof receipt.to_mode !== 'string'
-        || !Array.isArray(receipt.files)
-        || typeof receipt.oauth_preserved !== 'boolean') {
-        throw new Error('invalid_codex_lb_migration_receipt');
-    }
-    for (const file of receipt.files) {
-        if (!file
-            || typeof file.path !== 'string'
-            || !file.path
-            || (file.before_sha256 !== null && typeof file.before_sha256 !== 'string')
-            || (file.after_sha256 !== null && typeof file.after_sha256 !== 'string')
-            || (file.backup_path !== null && typeof file.backup_path !== 'string')
-            || typeof file.owned_by_sks !== 'boolean') {
-            throw new Error('invalid_codex_lb_migration_receipt_file');
+        || receipt.baseline_version !== '8.1.2'
+        || receipt.target_version !== '8.1.3'
+        || typeof receipt.config_before_sha256 !== 'string'
+        || typeof receipt.config_after_sha256 !== 'string'
+        || typeof receipt.auth_before_sha256 !== 'string'
+        || typeof receipt.auth_after_sha256 !== 'string'
+        || typeof receipt.auth_semantic_identity_preserved !== 'boolean'
+        || !receipt.historical_state
+        || typeof receipt.historical_state !== 'object'
+        || !Array.isArray(receipt.migrated_profiles)
+        || receipt.credentials_deleted !== false
+        || receipt.new_runtime !== 'desktop-bridge'
+        || !Array.isArray(receipt.backup_paths)
+        || typeof receipt.rollback_supported !== 'boolean'
+        || !Array.isArray(receipt.blockers)
+        || (receipt.migration_status !== 'migrated' && receipt.migration_status !== 'already_migrated')
+        || receipt.rollback_metadata?.schema !== 'sks.desktop-bridge-unification-rollback-metadata.v1'
+        || !Array.isArray(receipt.rollback_metadata.files)) {
+        throw new Error('invalid_desktop_bridge_unification_receipt');
+    }
+    for (const key of [
+        'desktop_mode',
+        'historical_provider_selection',
+        'model_provider',
+        'catalog_path'
+    ]) {
+        const entry = receipt.historical_state[key];
+        if (entry !== null && typeof entry !== 'string') {
+            throw new Error('invalid_desktop_bridge_unification_receipt_historical_state');
         }
     }
+    if (receipt.migrated_profiles.some((entry) => entry !== 'codex-lb' && entry !== 'openrouter')) {
+        throw new Error('invalid_desktop_bridge_unification_receipt_provider');
+    }
+    if (receipt.new_catalog_generation !== null
+        && typeof receipt.new_catalog_generation !== 'string') {
+        throw new Error('invalid_desktop_bridge_unification_receipt_catalog_generation');
+    }
+    const seenPaths = new Set();
+    const canonicalHomes = new Set();
+    for (const file of receipt.rollback_metadata.files) {
+        validateDesktopBridgeRollbackFile(file);
+        if (file.backup_path !== null) {
+            validateDesktopBridgeBackupPath(file.backup_path, receipt.receipt_id);
+        }
+        const resolved = path.resolve(file.path);
+        if (seenPaths.has(resolved)) {
+            throw new Error('invalid_desktop_bridge_unification_receipt_duplicate_path');
+        }
+        seenPaths.add(resolved);
+        canonicalHomes.add(canonicalHomeForRollbackFile(file));
+    }
+    if (canonicalHomes.size > 1) {
+        throw new Error('desktop_bridge_rollback_metadata_home_mismatch');
+    }
+    const metadataBackupPaths = new Set(receipt.rollback_metadata.files
+        .map((file) => file.backup_path)
+        .filter((entry) => typeof entry === 'string'));
+    if (receipt.backup_paths.some((entry) => typeof entry !== 'string' || !metadataBackupPaths.has(entry))
+        || metadataBackupPaths.size !== receipt.backup_paths.length) {
+        throw new Error('invalid_desktop_bridge_unification_receipt_backup_paths');
+    }
+    if (receipt.blockers.some((entry) => typeof entry !== 'string')) {
+        throw new Error('invalid_desktop_bridge_unification_receipt_blockers');
+    }
+    if (receipt.migration_status === 'already_migrated') {
+        if (receipt.rollback_supported !== false
+            || receipt.backup_paths.length !== 0
+            || receipt.rollback_metadata.files.length !== 0
+            || receipt.config_before_sha256 !== receipt.config_after_sha256
+            || receipt.auth_before_sha256 !== receipt.auth_after_sha256
+            || receipt.auth_semantic_identity_preserved !== true) {
+            throw new Error('invalid_desktop_bridge_unification_noop_receipt');
+        }
+    }
+    else if (receipt.rollback_supported !== true) {
+        throw new Error('invalid_desktop_bridge_unification_migrated_receipt');
+    }
+}
+function normalizeHistoricalSelectionCompatibility(value) {
+    if (!value || typeof value !== 'object')
+        return;
+    const historicalState = value.historical_state;
+    if (!historicalState || typeof historicalState !== 'object')
+        return;
+    const state = historicalState;
+    const compatibilityKey = ['provider', 'mode'].join('_');
+    const compatibilityValue = state[compatibilityKey];
+    if (compatibilityValue === undefined)
+        return;
+    const currentValue = state.historical_provider_selection;
+    if (currentValue !== undefined && currentValue !== compatibilityValue) {
+        throw new Error('invalid_desktop_bridge_unification_receipt_historical_selection_conflict');
+    }
+    if (currentValue === undefined) {
+        state.historical_provider_selection = compatibilityValue;
+    }
+    delete state[compatibilityKey];
+}
+function validateDesktopBridgeBackupPath(backupPath, receiptId) {
+    const resolved = path.resolve(backupPath);
+    const filesDir = path.dirname(resolved);
+    const receiptDir = path.dirname(filesDir);
+    if (path.basename(resolved).match(/^[a-f0-9]{16}\.before$/) === null
+        || path.basename(filesDir) !== 'files'
+        || path.basename(receiptDir) !== receiptId) {
+        throw new Error('desktop_bridge_rollback_backup_path_not_canonical');
+    }
+}
+function validateDesktopBridgeRollbackFile(file) {
+    if (!file || typeof file !== 'object') {
+        throw new Error('invalid_desktop_bridge_unification_rollback_file');
+    }
+    const entry = file;
+    const kinds = [
+        'config',
+        'bridge_settings',
+        'provider_registry',
+        'catalog_binding',
+        'route_policy',
+        'launchd_state'
+    ];
+    if (!entry.kind
+        || !kinds.includes(entry.kind)
+        || typeof entry.path !== 'string'
+        || !entry.path
+        || (entry.before_sha256 !== null && typeof entry.before_sha256 !== 'string')
+        || (entry.after_sha256 !== null && typeof entry.after_sha256 !== 'string')
+        || (entry.backup_path !== null && typeof entry.backup_path !== 'string')
+        || typeof entry.owned_by_sks !== 'boolean') {
+        throw new Error('invalid_desktop_bridge_unification_rollback_file');
+    }
+    const hashPattern = /^[a-f0-9]{64}$/;
+    if ((entry.before_sha256 !== null && !hashPattern.test(entry.before_sha256))
+        || (entry.after_sha256 !== null && !hashPattern.test(entry.after_sha256))
+        || (entry.before_sha256 === null && entry.backup_path !== null)
+        || (entry.before_sha256 !== null && entry.backup_path === null)
+        || (entry.backup_path !== null && !path.isAbsolute(entry.backup_path))) {
+        throw new Error('invalid_desktop_bridge_unification_rollback_file');
+    }
+    const resolved = path.resolve(entry.path);
+    const basename = path.basename(resolved).toLowerCase();
+    const segments = resolved.toLowerCase().split(path.sep);
+    const sensitiveBasenames = new Set([
+        'auth.json',
+        'sks-codex-lb.env',
+        'openrouter-api-key',
+        'openrouter-api-key.json'
+    ]);
+    if (sensitiveBasenames.has(basename)
+        || segments.includes('secrets')
+        || /(?:credential|api-key|secret)/i.test(basename)) {
+        throw new Error('desktop_bridge_rollback_secret_file_forbidden');
+    }
+    if (!path.isAbsolute(entry.path)) {
+        throw new Error('desktop_bridge_rollback_metadata_path_not_canonical');
+    }
+    if (entry.kind === 'config' ? entry.owned_by_sks : !entry.owned_by_sks) {
+        throw new Error('desktop_bridge_rollback_metadata_ownership_invalid');
+    }
+}
+function canonicalHomeForRollbackFile(file) {
+    const resolved = path.resolve(file.path);
+    const retiredArtifact = retiredDesktopBridgeRuntimeArtifact(resolved);
+    if (retiredArtifact !== null) {
+        throw new Error(`desktop_bridge_rollback_retired_runtime_target_forbidden:${retiredArtifact}`);
+    }
+    if (file.kind === 'config') {
+        const codexHome = path.dirname(resolved);
+        const home = path.dirname(codexHome);
+        if (path.basename(resolved) === 'config.toml'
+            && path.basename(codexHome) === '.codex'
+            && path.join(home, '.codex', 'config.toml') === resolved)
+            return home;
+    }
+    else if (file.kind === 'launchd_state') {
+        const launchAgents = path.dirname(resolved);
+        const library = path.dirname(launchAgents);
+        const home = path.dirname(library);
+        if (path.basename(resolved) === 'com.sneakoscope.desktop-bridge.plist'
+            && path.basename(launchAgents) === 'LaunchAgents'
+            && path.basename(library) === 'Library'
+            && path.join(home, 'Library', 'LaunchAgents', path.basename(resolved)) === resolved)
+            return home;
+    }
+    else {
+        const expectedBasename = {
+            bridge_settings: 'desktop-bridge-settings.json',
+            provider_registry: 'sks-bridge-provider-registry.json',
+            catalog_binding: 'sks-bridge-active-generation.json',
+            route_policy: 'sks-bridge-route-policy.json'
+        };
+        const sksDir = path.dirname(resolved);
+        const codexHome = path.dirname(sksDir);
+        const home = path.dirname(codexHome);
+        if (path.basename(resolved) === expectedBasename[file.kind]
+            && path.basename(sksDir) === 'sks'
+            && path.basename(codexHome) === '.codex'
+            && path.join(home, '.codex', 'sks', expectedBasename[file.kind]) === resolved)
+            return home;
+    }
+    throw new Error(`desktop_bridge_rollback_metadata_path_not_canonical:${file.kind}`);
+}
+function retiredDesktopBridgeRuntimeArtifact(resolvedPath) {
+    const basename = path.basename(resolvedPath);
+    const runtimeDir = path.dirname(resolvedPath);
+    const codexHome = path.dirname(runtimeDir);
+    const home = path.dirname(codexHome);
+    if (path.basename(runtimeDir) === 'sks'
+        && path.basename(codexHome) === '.codex'
+        && path.join(home, '.codex', 'sks', basename) === resolvedPath) {
+        if (basename === 'codex-lb-desktop-bridge-settings.json')
+            return 'settings';
+        if (basename === 'codex-lb-desktop-bridge.json')
+            return 'state';
+    }
+    const logsDir = path.dirname(resolvedPath);
+    const logsRuntimeDir = path.dirname(logsDir);
+    const logsCodexHome = path.dirname(logsRuntimeDir);
+    const logsHome = path.dirname(logsCodexHome);
+    if (path.basename(logsDir) === 'logs'
+        && path.basename(logsRuntimeDir) === 'sks'
+        && path.basename(logsCodexHome) === '.codex'
+        && path.join(logsHome, '.codex', 'sks', 'logs', basename) === resolvedPath) {
+        if (basename === 'codex-lb-desktop-bridge.out.log')
+            return 'stdout_log';
+        if (basename === 'codex-lb-desktop-bridge.err.log')
+            return 'stderr_log';
+    }
+    const launchAgents = path.dirname(resolvedPath);
+    const library = path.dirname(launchAgents);
+    const launchdHome = path.dirname(library);
+    if (basename === 'com.sneakoscope.codex-lb-desktop-bridge.plist'
+        && path.basename(launchAgents) === 'LaunchAgents'
+        && path.basename(library) === 'Library'
+        && path.join(launchdHome, 'Library', 'LaunchAgents', 'com.sneakoscope.codex-lb-desktop-bridge.plist') === resolvedPath)
+        return 'plist';
+    return null;
 }
 function sha256(bytes) {
     return createHash('sha256').update(bytes).digest('hex');