diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 57340b5..f6d2375 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -8,10 +8,13 @@ on:
 
 jobs:
   test:
-    runs-on: windows-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
+        os:
+          - windows-latest
+          - ubuntu-latest
         node-version:
           - "16"
           - "24"
@@ -33,3 +36,13 @@ jobs:
           dotnet-version: "10.0.x"
       - run: dotnet test desktop/CodexProviderSync.Core.Tests/CodexProviderSync.Core.Tests.csproj
       - run: dotnet test desktop/CodexProviderSync.App.Tests/CodexProviderSync.App.Tests.csproj
+
+  desktop-macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: "10.0.x"
+      - run: dotnet test desktop/CodexProviderSync.Core.Tests/CodexProviderSync.Core.Tests.csproj
+      - run: dotnet build desktop/CodexProviderSync.Mac/CodexProviderSync.Mac.csproj --configuration Release
diff --git a/AGENTS.md b/AGENTS.md
index 19ef19d..566263f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,9 +15,11 @@ For normal Windows users, prefer the GUI app when it is available. Use the CLI w
 The tool works by updating both:
 
 - rollout metadata under `~/.codex/sessions` and `~/.codex/archived_sessions`
-- SQLite thread metadata in the detected Codex state database, normally
-  `~/.codex/sqlite/state_5.sqlite` with legacy fallback to
-  `~/.codex/state_5.sqlite`
+- SQLite thread metadata in the resolved Codex state database
+
+Resolve SQLite Home in this order: explicit CLI/GUI override, root `sqlite_home` in `config.toml`, `CODEX_SQLITE_HOME`, then `<codex-home>/sqlite`. Only the default layout may fall back to `<codex-home>/state_5.sqlite`. Never fall back when an explicit/config/environment SQLite Home is missing.
+
+On Windows, `\\wsl.localhost\...` and `\\wsl$\...` SQLite Homes are diagnostic-only. SQLite operations for these paths run inside WSL and use the corresponding Linux path.
 
 Do not solve this by manually editing rollout files only unless the user explicitly asks for manual intervention.
 
@@ -87,6 +89,9 @@ GUI mapping:
 - `Execute` with config checkbox = switch-like behavior
 - `Restore Backup` = restore a previous backup
 - backup retention defaults to 5 and can be customized in the GUI
+- SQLite Home overrides are stored per Codex Home in app settings and are passed to refresh, sync, switch, and restore
+- Windows GUI refresh reports WSL UNC SQLite Homes as diagnostic-only paths; Execute and Restore are disabled for that layout
+- restoring a metadata v2 backup to a different SQLite Home requires a second confirmation showing source and target
 - `Clean Old Backups` = prune managed backups down to the selected retention count
 
 ## Important Behavior
@@ -107,6 +112,12 @@ If the output says `state_5.sqlite is currently in use`:
 - tell the user to close Codex, Codex App, and app-server
 - then rerun the same command
 
+If the output says Windows cannot safely access SQLite through a WSL UNC path:
+
+- identify the message as a WSL UNC path safety diagnostic
+- open the corresponding WSL distribution
+- run the CLI there with the Windows Codex Home mounted under `/mnt/<drive>/...` and SQLite Home expressed as a Linux `/home/...` path
+
 If sync reports `Skipped locked rollout files`:
 
 - treat the sync as mostly successful
@@ -128,6 +139,9 @@ If `switch <provider-id>` fails because the provider is missing:
 - by default the tool keeps the most recent 5 managed backups
 - use GUI retention settings or CLI `--keep <n>` when the user wants a different retention count
 - do not edit `state_5.sqlite` or rollout files manually if the tool can do it
+- classify WSL UNC messages as path safety diagnostics and route SQLite operations through WSL with Linux paths
+- metadata v2 backups record `sqliteHome` and `sqliteDbFiles`; a missing default-layout database may be rebuilt from a valid backup, but a missing explicit/config/environment database remains an error
+- CLI restore to a different SQLite Home requires `--sqlite-home`, `--allow-sqlite-home-relocation`, and `--no-config`; desktop apps must reject relocation while config restore is selected
 - GUI settings live in `%AppData%\codex-provider-sync\settings.json`
 
 ## Recommended Commands
@@ -152,6 +166,13 @@ codex-provider sync --codex-home C:\Users\you\.codex
 codex-provider switch openai --codex-home C:\Users\you\.codex
 ```
 
+From WSL when Codex Home is on Windows and SQLite Home is in WSL:
+
+```bash
+codex-provider status --codex-home /mnt/c/Users/you/.codex --sqlite-home /home/you/.codex/sqlite
+codex-provider sync --codex-home /mnt/c/Users/you/.codex --sqlite-home /home/you/.codex/sqlite
+```
+
 ## One-Shot Prompt Template
 
 Use this prompt in another AI tool if the user wants one-step handling:
diff --git a/README.md b/README.md
index 381f95a..c0377ad 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,7 @@ Codex 切换 `model_provider` 后，旧会话可能从 Desktop 或 `/resume` 中
 ## 它会处理什么
 
 - 同步 `~/.codex/sessions` 和 `~/.codex/archived_sessions` 中的 rollout metadata。
-- 同步 Codex SQLite 线程记录；优先检测 `~/.codex/sqlite/state_5.sqlite`，并兼容旧路径 `~/.codex/state_5.sqlite`。
+- 同步 Codex SQLite 线程记录，并支持 SQLite 与 `Codex Home` 分开存放。
 - 修复项目可见性相关路径信息，并在需要时同步相关 model metadata。
 - 每次同步前自动备份，支持恢复和清理旧备份。
 - 大型 rollout 文件在满足条件时原地更新，否则自动使用完整安全重写。
@@ -49,6 +49,8 @@ Codex 切换 `model_provider` 后，旧会话可能从 Desktop 或 `/resume` 中
 
 GUI 会保留备份并显示同步结果。每天首次启动会在后台检查一次稳定版更新，网络查询最多等待 10 秒；也可以随时手动检查。执行日志保存在 `%AppData%\codex-provider-sync\logs`。
 
+Windows GUI 支持为每个 Codex Home 单独指定 Windows 文件系统中的 SQLite Home。`\\wsl.localhost\...` 和 `\\wsl$\...` 一类 WSL UNC 路径仅用于安全诊断；GUI 会显示诊断信息并禁用同步和恢复。Windows Codex Home + WSL SQLite Home 场景应在 WSL 内运行 CLI。
+
 项目目前未做 Windows 代码签名，从浏览器下载后可能出现 SmartScreen 提示。请从本项目 Release 下载，并按需核对同版本 SHA-256。
 
 Windows 完整说明见 [README_GUI_ZH.md](docs/README_GUI_ZH.md)。macOS 用户可自行构建 Avalonia 桌面版，参见 [README_MAC_GUI_ZH.md](docs/README_MAC_GUI_ZH.md)。
@@ -75,7 +77,18 @@ codex-provider sync
 | `codex-provider watch` | 监听配置、SQLite 和 WAL 变化并自动同步 |
 | `codex-provider watch --once` | 第一次变化并成功同步后退出 |
 
-`switch` 支持 `--model <NAME>` 显式设置根级 model，或使用 `--keep-root-model` 只切换 Provider。所有主要命令都支持 `--codex-home <PATH>`。
+`switch` 支持 `--model <NAME>` 显式设置根级 model，或使用 `--keep-root-model` 只切换 Provider。所有主要命令都支持 `--codex-home <PATH>` 和 `--sqlite-home <PATH>`。
+
+SQLite Home 按以下顺序解析：命令行 override → `config.toml` 根级 `sqlite_home` → `CODEX_SQLITE_HOME` → `<Codex Home>/sqlite`。只有最后一种默认布局会继续检查旧路径 `<Codex Home>/state_5.sqlite`；一旦显式指定 SQLite Home，就不会回退到 Codex Home 中的旧数据库。
+
+例如 Codex App 使用 Windows 配置、app-server 与 SQLite 位于 WSL 时，可在 WSL CLI 中直接传入：
+
+```bash
+codex-provider status --codex-home /mnt/c/Users/you/.codex --sqlite-home /home/you/.codex/sqlite
+codex-provider sync --codex-home /mnt/c/Users/you/.codex --sqlite-home /home/you/.codex/sqlite
+```
+
+`status` 会显示 effective SQLite Home 和来源。显式路径缺少 `state_5.sqlite` 时，状态查询只报告诊断，`sync`、`switch` 和数据库恢复不会偷偷回退到其它位置。默认布局中的数据库被删除时，`restore` 可以根据备份 metadata 在原默认位置重建数据库。
 
 ## 安全与限制
 
@@ -88,6 +101,8 @@ codex-provider sync
 - 不修改消息历史、会话标题、认证信息、`auth.json` 或 `updated_at`。
 - 不在多台设备之间复制配置或会话文件；它只修复当前 Codex Home 的 metadata。
 - SQLite 被占用时，需要先关闭 Codex、Codex App 和 app-server 后重试。
+- Windows 进程检测到 WSL UNC SQLite Home 时会立即显示专用安全诊断并停止操作。后续操作应进入对应 WSL 发行版，并使用 `/home/...` 形式的 Linux 路径运行 CLI。
+- 新备份使用 metadata v2 记录独立 SQLite Home；恢复到其它 SQLite Home 默认拒绝。CLI 需要同时传入 `--sqlite-home`、`--allow-sqlite-home-relocation` 和 `--no-config`，避免恢复后的 `config.toml` 重新指向原 SQLite Home。
 - 活跃会话锁住 rollout 文件时，工具会跳过该文件并继续处理其它会话；结束活跃会话后可再次同步。
 - 含 `encrypted_content` 的会话跨 Provider/account 后，可能只能恢复列表可见性，继续对话或 compact 仍可能报 `invalid_encrypted_content`。
 - Codex Desktop 首屏目前只显示最近 50 条会话。若 `/resume` 可见但项目侧仍不显示，请查看状态中的 `first page` / `ranks` 诊断；本工具不会修改时间戳来绕过此限制。
@@ -106,10 +121,13 @@ git clone https://github.com/Dailin521/codex-provider-sync.git
 cd codex-provider-sync
 npm test
 dotnet test desktop/CodexProviderSync.Core.Tests/CodexProviderSync.Core.Tests.csproj
+./scripts/test-wsl-unc-safety.sh
 pwsh ./scripts/publish-gui.ps1
 ./scripts/publish-gui-macos.sh
 ```
 
+`test-wsl-unc-safety.sh` 需要从 WSL 运行，并调用 Windows `dotnet.exe` 验证真实 WSL ext4 SQLite 的安全阻断。
+
 ## License
 
 MIT
diff --git a/desktop/CodexProviderSync.App.Tests/MainFormPresentationTests.cs b/desktop/CodexProviderSync.App.Tests/MainFormPresentationTests.cs
index 9027d58..f83e39f 100644
--- a/desktop/CodexProviderSync.App.Tests/MainFormPresentationTests.cs
+++ b/desktop/CodexProviderSync.App.Tests/MainFormPresentationTests.cs
@@ -1,6 +1,7 @@
 using System.Drawing;
 using System.Reflection;
 using System.Windows.Forms;
+using CodexProviderSync.Core;
 
 namespace CodexProviderSync.App.Tests;
 
@@ -25,6 +26,8 @@ public void MainForm_UsesChineseChromeAndGreenPrimaryAction()
             Assert.Equal(FlatStyle.Flat, execute.FlatStyle);
 
             Assert.Equal("浏览...", Field<Button>(form, "_browseButton").Text);
+            Assert.Equal("浏览...", Field<Button>(form, "_browseSqliteHomeButton").Text);
+            Assert.True(string.IsNullOrEmpty(Field<TextBox>(form, "_sqliteHomeText").Text));
             Assert.Equal("刷新", Field<Button>(form, "_refreshButton").Text);
             Assert.Equal("打开日志目录", Field<Button>(form, "_openLogButton").Text);
             Assert.Equal("就绪", Field<Label>(form, "_busyLabel").Text);
@@ -35,6 +38,77 @@ public void MainForm_UsesChineseChromeAndGreenPrimaryAction()
         }
     }
 
+    [Fact]
+    public void CaptureStorageSelection_RebindsSqliteOverrideBeforeReturningNewCodexHome()
+    {
+        string root = Path.Combine(Path.GetTempPath(), $"codex-provider-ui-test-{Guid.NewGuid():N}");
+        string codexHomeA = Path.Combine(root, "home-a");
+        string codexHomeB = Path.Combine(root, "home-b");
+        string sqliteHomeA = Path.Combine(root, "sqlite-a");
+        string sqliteHomeB = Path.Combine(root, "sqlite-b");
+        Directory.CreateDirectory(root);
+        try
+        {
+            SettingsService settingsService = new(Path.Combine(root, "settings.json"));
+            AppSettings settings = settingsService.RecordSqliteHomeOverride(
+                settingsService.RecordSqliteHomeOverride(new AppSettings(), codexHomeA, sqliteHomeA),
+                codexHomeB,
+                sqliteHomeB);
+            using MainForm form = new(new ExecutionLogService(root), settingsService);
+            SetField(form, "_settings", settings);
+
+            ComboBox codexHome = Field<ComboBox>(form, "_codexHomeCombo");
+            TextBox sqliteHome = Field<TextBox>(form, "_sqliteHomeText");
+            codexHome.Text = codexHomeA;
+            Assert.Equal((codexHomeA, sqliteHomeA), form.CaptureStorageSelection());
+            Assert.Equal(sqliteHomeA, sqliteHome.Text);
+
+            codexHome.Text = codexHomeB;
+            Assert.Equal((codexHomeB, sqliteHomeB), form.CaptureStorageSelection());
+            Assert.Equal(sqliteHomeB, sqliteHome.Text);
+        }
+        finally
+        {
+            Directory.Delete(root, recursive: true);
+        }
+    }
+
+    [Fact]
+    public void MainForm_DisablesSqliteActionsForUnsupportedStorage()
+    {
+        string root = Path.Combine(Path.GetTempPath(), $"codex-provider-ui-test-{Guid.NewGuid():N}");
+        Directory.CreateDirectory(root);
+        try
+        {
+            using MainForm form = new(new ExecutionLogService(root));
+            SetField(form, "_currentStatus", new StatusSnapshot
+            {
+                CodexHome = @"C:\Users\user\.codex",
+                SqliteAccess = new SqliteAccessInfo(false, "windows-wsl-unc", "unsupported"),
+                CurrentProvider = new CurrentProviderInfo("openai", false),
+                ConfiguredProviders = ["openai"],
+                RolloutCounts = new ProviderCounts(),
+                LockedRolloutFiles = [],
+                UnreadableRolloutFiles = [],
+                EncryptedContentCounts = new ProviderCounts(),
+                SqliteCounts = null,
+                BackupRoot = root,
+                BackupSummary = new BackupSummary { Count = 0, TotalBytes = 0 }
+            });
+
+            Invoke(form, "SetBusy", false, "就绪");
+
+            Assert.False(Field<Button>(form, "_executeButton").Enabled);
+            Assert.False(Field<Button>(form, "_restoreButton").Enabled);
+            Assert.True(Field<Button>(form, "_refreshButton").Enabled);
+            Assert.True(Field<Button>(form, "_pruneBackupsButton").Enabled);
+        }
+        finally
+        {
+            Directory.Delete(root, recursive: true);
+        }
+    }
+
     private static T Field<T>(MainForm form, string name) where T : class
     {
         return typeof(MainForm)
@@ -42,4 +116,18 @@ private static T Field<T>(MainForm form, string name) where T : class
             .GetValue(form) as T
             ?? throw new InvalidOperationException($"Unable to read {name}.");
     }
+
+    private static void SetField<T>(MainForm form, string name, T value)
+    {
+        FieldInfo field = typeof(MainForm).GetField(name, BindingFlags.Instance | BindingFlags.NonPublic)
+            ?? throw new InvalidOperationException($"Unable to find {name}.");
+        field.SetValue(form, value);
+    }
+
+    private static void Invoke(MainForm form, string name, params object[] arguments)
+    {
+        MethodInfo method = typeof(MainForm).GetMethod(name, BindingFlags.Instance | BindingFlags.NonPublic)
+            ?? throw new InvalidOperationException($"Unable to find {name}.");
+        method.Invoke(form, arguments);
+    }
 }
diff --git a/desktop/CodexProviderSync.App/MainForm.cs b/desktop/CodexProviderSync.App/MainForm.cs
index fa280fe..336f16e 100644
--- a/desktop/CodexProviderSync.App/MainForm.cs
+++ b/desktop/CodexProviderSync.App/MainForm.cs
@@ -14,6 +14,8 @@ public sealed class MainForm : Form
     private readonly ComboBox _codexHomeCombo = new() { Dock = DockStyle.Fill, DropDownStyle = ComboBoxStyle.DropDown };
     private readonly Button _browseButton = new() { Text = "浏览...", AutoSize = true };
     private readonly Button _refreshButton = new() { Text = "刷新", AutoSize = true };
+    private readonly TextBox _sqliteHomeText = new() { Dock = DockStyle.Fill };
+    private readonly Button _browseSqliteHomeButton = new() { Text = "浏览...", AutoSize = true };
     private readonly RichTextBox _statusBox = new()
     {
         Dock = DockStyle.Fill,
@@ -128,6 +130,7 @@ public sealed class MainForm : Form
     private bool _logFailureReported;
     private bool _busy;
     private bool _updateCheckInProgress;
+    private string? _sqliteOverrideCodexHome;
 
     public MainForm() : this(new ExecutionLogService())
     {
@@ -228,7 +231,7 @@ private Control BuildTopPanel()
     {
         GroupBox group = new()
         {
-            Text = "Codex Home",
+            Text = "存储位置",
             Dock = DockStyle.Top,
             AutoSize = true,
             AutoSizeMode = AutoSizeMode.GrowAndShrink
@@ -238,11 +241,12 @@ private Control BuildTopPanel()
         {
             Dock = DockStyle.Top,
             ColumnCount = 4,
+            RowCount = 2,
             AutoSize = true,
             Padding = new Padding(10)
         };
-        panel.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100));
         panel.ColumnStyles.Add(new ColumnStyle(SizeType.AutoSize));
+        panel.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100));
         panel.ColumnStyles.Add(new ColumnStyle(SizeType.AutoSize));
         panel.ColumnStyles.Add(new ColumnStyle(SizeType.AutoSize));
 
@@ -254,10 +258,14 @@ private Control BuildTopPanel()
             Anchor = AnchorStyles.Left
         };
 
-        panel.Controls.Add(_codexHomeCombo, 0, 0);
-        panel.Controls.Add(_browseButton, 1, 0);
-        panel.Controls.Add(_refreshButton, 2, 0);
-        panel.Controls.Add(recentLabel, 3, 0);
+        panel.Controls.Add(new Label { Text = "Codex Home", AutoSize = true, Anchor = AnchorStyles.Left }, 0, 0);
+        panel.Controls.Add(_codexHomeCombo, 1, 0);
+        panel.Controls.Add(_browseButton, 2, 0);
+        panel.Controls.Add(_refreshButton, 3, 0);
+        panel.Controls.Add(new Label { Text = "SQLite Home（留空时按配置自动解析）", AutoSize = true, Anchor = AnchorStyles.Left }, 0, 1);
+        panel.Controls.Add(_sqliteHomeText, 1, 1);
+        panel.Controls.Add(_browseSqliteHomeButton, 2, 1);
+        panel.Controls.Add(recentLabel, 3, 1);
         group.Controls.Add(panel);
         return group;
     }
@@ -547,6 +555,7 @@ private Control BuildLogPanel()
     private void WireEvents()
     {
         _browseButton.Click += async (_, _) => await BrowseCodexHomeAsync();
+        _browseSqliteHomeButton.Click += async (_, _) => await BrowseSqliteHomeAsync();
         _refreshButton.Click += async (_, _) => await RefreshStatusAsync();
         _addProviderButton.Click += async (_, _) => await AddManualProviderAsync();
         _removeProviderButton.Click += async (_, _) => await RemoveManualProviderAsync();
@@ -559,6 +568,7 @@ private void WireEvents()
         _openLogButton.Click += (_, _) => OpenLogFolder();
         _providerList.SelectedIndexChanged += (_, _) => UpdateSelectionLabel();
         _codexHomeCombo.Leave += async (_, _) => await PersistHomeSelectionAsync();
+        _sqliteHomeText.Leave += async (_, _) => await PersistSqliteHomeOverrideAsync(CaptureStorageSelection());
     }
 
     private async Task LoadStateAsync()
@@ -568,6 +578,7 @@ private async Task LoadStateAsync()
         ApplyWindowBounds(_settings.WindowBounds);
         ReloadRecentHomes();
         _codexHomeCombo.Text = _settings.LastCodexHome ?? AppConstants.DefaultCodexHome();
+        LoadSqliteHomeOverride(CurrentCodexHome());
         _backupRetentionInput.Value = Math.Max(_backupRetentionInput.Minimum, Math.Min(_backupRetentionInput.Maximum, _settings.BackupRetentionCount));
         AppendLog($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] 已加载设置: {_settingsService.SettingsPath}");
         AppendLog($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] 执行日志文件: {_executionLogService.CurrentLogPath}");
@@ -577,8 +588,9 @@ private async Task LoadStateAsync()
 
     private async Task RefreshStatusAsync()
     {
-        string codexHome = CurrentCodexHome();
-        await RunBusyAsync("刷新中...", () => RefreshStatusCoreAsync(codexHome));
+        (string codexHome, string? sqliteHome) = CaptureStorageSelection();
+        await PersistSqliteHomeOverrideAsync((codexHome, sqliteHome));
+        await RunBusyAsync("刷新中...", () => RefreshStatusCoreAsync(codexHome, sqliteHome));
     }
 
     private async Task BrowseCodexHomeAsync()
@@ -603,7 +615,7 @@ private async Task BrowseCodexHomeAsync()
 
     private async Task PersistHomeSelectionAsync()
     {
-        string codexHome = CurrentCodexHome();
+        (string codexHome, _) = CaptureStorageSelection();
         if (string.IsNullOrWhiteSpace(codexHome))
         {
             return;
@@ -615,6 +627,48 @@ private async Task PersistHomeSelectionAsync()
         ReloadRecentHomes();
     }
 
+    private async Task BrowseSqliteHomeAsync()
+    {
+        (_, string? sqliteHome) = CaptureStorageSelection();
+        using FolderBrowserDialog dialog = new()
+        {
+            Description = "选择包含 state_5.sqlite 的目录",
+            UseDescriptionForTitle = true,
+            InitialDirectory = Directory.Exists(sqliteHome)
+                ? sqliteHome!
+                : CurrentCodexHome(),
+            ShowNewFolderButton = false
+        };
+        if (dialog.ShowDialog(this) != DialogResult.OK)
+        {
+            return;
+        }
+
+        (string codexHome, _) = CaptureStorageSelection();
+        _sqliteHomeText.Text = dialog.SelectedPath;
+        await PersistSqliteHomeOverrideAsync((codexHome, dialog.SelectedPath));
+        await RefreshStatusAsync();
+    }
+
+    private async Task PersistSqliteHomeOverrideAsync((string CodexHome, string? SqliteHome) selection)
+    {
+        if (_loadingSettings)
+        {
+            return;
+        }
+        _settings = _settingsService.RecordSqliteHomeOverride(
+            _settings,
+            selection.CodexHome,
+            selection.SqliteHome);
+        await _settingsService.SaveAsync(_settings);
+    }
+
+    private void LoadSqliteHomeOverride(string codexHome)
+    {
+        _sqliteOverrideCodexHome = Path.GetFullPath(codexHome);
+        _sqliteHomeText.Text = _settingsService.GetSqliteHomeOverride(_settings, codexHome) ?? string.Empty;
+    }
+
     private async Task PersistBackupRetentionAsync()
     {
         if (_loadingSettings)
@@ -667,6 +721,7 @@ private async Task RemoveManualProviderAsync()
 
     private async Task ExecuteSyncOrSwitchAsync()
     {
+        (string codexHome, string? sqliteHome) = CaptureStorageSelection();
         string? provider = SelectedProvider();
         if (string.IsNullOrWhiteSpace(provider))
         {
@@ -681,7 +736,7 @@ private async Task ExecuteSyncOrSwitchAsync()
 
         await RunBusyAsync("执行中...", async () =>
         {
-            string codexHome = CurrentCodexHome();
+            await PersistSqliteHomeOverrideAsync((codexHome, sqliteHome));
             int backupRetentionCount = CurrentBackupRetentionCount();
             SyncResult result;
             if (_updateConfigCheck.Checked)
@@ -698,11 +753,16 @@ await RunBusyAsync("执行中...", async () =>
                     provider,
                     backupRetentionCount,
                     model: explicitModel,
-                    keepRootModel: keepRootModel));
+                    keepRootModel: keepRootModel,
+                    explicitSqliteHome: sqliteHome));
             }
             else
             {
-                result = await Task.Run(async () => await _syncService.RunSyncAsync(codexHome, provider: provider, keepCount: backupRetentionCount));
+                result = await Task.Run(async () => await _syncService.RunSyncAsync(
+                    codexHome,
+                    provider: provider,
+                    keepCount: backupRetentionCount,
+                    explicitSqliteHome: sqliteHome));
             }
 
             _settings = _settingsService.UpdateState(_settings, provider, result.BackupDir, CaptureWindowBounds(), backupRetentionCount);
@@ -714,14 +774,15 @@ await RunBusyAsync("执行中...", async () =>
                 TextFormatter.ChineseSimplified));
             AppendLog(FormatModelSyncOutcome(result.ModelSync));
             AppendLog(string.Empty);
-            await RefreshStatusCoreAsync(codexHome);
+            await RefreshStatusCoreAsync(codexHome, sqliteHome);
             SelectProvider(provider);
         });
     }
 
     private async Task RestoreBackupAsync()
     {
-        string backupRoot = _currentStatus?.BackupRoot ?? AppConstants.DefaultBackupRoot(CurrentCodexHome());
+        (string codexHome, string? sqliteHome) = CaptureStorageSelection();
+        string backupRoot = _currentStatus?.BackupRoot ?? AppConstants.DefaultBackupRoot(codexHome);
         string initialBackupDir = Directory.Exists(_settings.LastBackupDirectory)
             ? _settings.LastBackupDirectory!
             : backupRoot;
@@ -768,9 +829,58 @@ private async Task RestoreBackupAsync()
             return;
         }
 
+        bool allowSqliteHomeRelocation = false;
+        try
+        {
+            if (_restoreDatabaseCheck.Checked)
+            {
+                BackupStorageInfo backupStorage = await _syncService.GetBackupStorageInfoAsync(dialog.SelectedPath);
+                StatusSnapshot targetStatus = await _syncService.GetStatusAsync(codexHome, sqliteHome);
+                if (backupStorage.Version >= 2
+                    && !string.IsNullOrWhiteSpace(backupStorage.SqliteHome)
+                    && !PathsEqual(backupStorage.SqliteHome, targetStatus.StateDbLocation is null
+                        ? targetStatus.SqliteHome
+                        : Path.GetDirectoryName(targetStatus.StateDbLocation.Path)!))
+                {
+                    string targetSqliteHome = targetStatus.StateDbLocation is null
+                        ? targetStatus.SqliteHome
+                        : Path.GetDirectoryName(targetStatus.StateDbLocation.Path)!;
+                    if (_restoreConfigCheck.Checked)
+                    {
+                        MessageBox.Show(
+                            this,
+                            "恢复到不同 SQLite Home 时不能同时恢复 config.toml。请取消勾选“恢复配置文件”后重试，以保留当前目标配置。",
+                            Text,
+                            MessageBoxButtons.OK,
+                            MessageBoxIcon.Warning);
+                        return;
+                    }
+                    DialogResult relocationConfirm = MessageBox.Show(
+                        this,
+                        $"备份中的 SQLite Home 与当前目标不同。{Environment.NewLine}{Environment.NewLine}"
+                        + $"备份来源: {backupStorage.SqliteHome}{Environment.NewLine}"
+                        + $"恢复目标: {targetSqliteHome}{Environment.NewLine}{Environment.NewLine}"
+                        + "确认将数据库恢复到当前目标吗？",
+                        Text,
+                        MessageBoxButtons.OKCancel,
+                        MessageBoxIcon.Warning);
+                    if (relocationConfirm != DialogResult.OK)
+                    {
+                        return;
+                    }
+                    allowSqliteHomeRelocation = true;
+                }
+            }
+        }
+        catch (Exception error)
+        {
+            AppendLog($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] 读取备份信息失败: {error}");
+            MessageBox.Show(this, $"无法读取备份信息。{Environment.NewLine}{Environment.NewLine}{error.Message}", Text, MessageBoxButtons.OK, MessageBoxIcon.Error);
+            return;
+        }
+
         await RunBusyAsync("恢复中...", async () =>
         {
-            string codexHome = CurrentCodexHome();
             RestoreResult result = await Task.Run(async () => await _syncService.RunRestoreAsync(
                 codexHome,
                 dialog.SelectedPath,
@@ -778,14 +888,16 @@ await RunBusyAsync("恢复中...", async () =>
                 {
                     RestoreConfig = _restoreConfigCheck.Checked,
                     RestoreDatabase = _restoreDatabaseCheck.Checked,
-                    RestoreSessions = _restoreSessionsCheck.Checked
-                }));
+                    RestoreSessions = _restoreSessionsCheck.Checked,
+                    AllowSqliteHomeRelocation = allowSqliteHomeRelocation
+                },
+                sqliteHome));
             _settings = _settingsService.UpdateState(_settings, SelectedProvider(), dialog.SelectedPath, CaptureWindowBounds(), CurrentBackupRetentionCount());
             await _settingsService.SaveAsync(_settings);
             AppendLog($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] 恢复完成");
             AppendLog(TextFormatter.FormatRestoreResult(result, TextFormatter.ChineseSimplified));
             AppendLog(string.Empty);
-            await RefreshStatusCoreAsync(codexHome);
+            await RefreshStatusCoreAsync(codexHome, sqliteHome);
         });
     }
 
@@ -821,6 +933,7 @@ private void OpenLogFolder()
 
     private async Task PruneBackupsAsync()
     {
+        (string codexHome, string? sqliteHome) = CaptureStorageSelection();
         if (!ConfirmBackupPrune())
         {
             return;
@@ -828,12 +941,11 @@ private async Task PruneBackupsAsync()
 
         await RunBusyAsync("正在清理备份...", async () =>
         {
-            string codexHome = CurrentCodexHome();
             BackupPruneResult result = await Task.Run(async () => await _syncService.RunPruneBackupsAsync(codexHome, CurrentBackupRetentionCount()));
             AppendLog($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] 旧备份清理完成");
             AppendLog(TextFormatter.FormatBackupPruneResult(result, TextFormatter.ChineseSimplified));
             AppendLog(string.Empty);
-            await RefreshStatusCoreAsync(codexHome);
+            await RefreshStatusCoreAsync(codexHome, sqliteHome);
         });
     }
 
@@ -1100,6 +1212,22 @@ private string CurrentCodexHome()
         return string.IsNullOrWhiteSpace(text) ? AppConstants.DefaultCodexHome() : text;
     }
 
+    private string? CurrentSqliteHomeOverride()
+    {
+        string text = _sqliteHomeText.Text.Trim();
+        return string.IsNullOrWhiteSpace(text) ? null : text;
+    }
+
+    internal (string CodexHome, string? SqliteHome) CaptureStorageSelection()
+    {
+        string codexHome = CurrentCodexHome();
+        if (_sqliteOverrideCodexHome is null || !PathsEqual(_sqliteOverrideCodexHome, codexHome))
+        {
+            LoadSqliteHomeOverride(codexHome);
+        }
+        return (codexHome, CurrentSqliteHomeOverride());
+    }
+
     private int CurrentBackupRetentionCount()
     {
         return Decimal.ToInt32(_backupRetentionInput.Value);
@@ -1109,7 +1237,12 @@ private void PersistUiState()
     {
         try
         {
-            _settings = _settingsService.RecordCodexHome(_settings, CurrentCodexHome());
+            (string codexHome, string? sqliteHome) = CaptureStorageSelection();
+            _settings = _settingsService.RecordCodexHome(_settings, codexHome);
+            _settings = _settingsService.RecordSqliteHomeOverride(
+                _settings,
+                codexHome,
+                sqliteHome);
             _settings = _settingsService.UpdateState(_settings, SelectedProvider(), _settings.LastBackupDirectory, CaptureWindowBounds(), CurrentBackupRetentionCount());
             _settingsService.Save(_settings);
         }
@@ -1119,9 +1252,11 @@ private void PersistUiState()
         }
     }
 
-    private async Task RefreshStatusCoreAsync(string codexHome)
+    private async Task RefreshStatusCoreAsync(string codexHome, string? sqliteHome)
     {
-        _currentStatus = await Task.Run(async () => await _syncService.GetStatusAsync(codexHome));
+        _currentStatus = await Task.Run(async () => await _syncService.GetStatusAsync(
+            codexHome,
+            sqliteHome));
         _settings = _settingsService.RecordCodexHome(_settings, _currentStatus.CodexHome);
         _settings = _settingsService.MergeDetectedProviders(_settings, _syncService.ExtractDetectedProviderIds(_currentStatus));
         _settings = _settingsService.UpdateState(_settings, SelectedProvider(), _settings.LastBackupDirectory, CaptureWindowBounds(), CurrentBackupRetentionCount());
@@ -1183,11 +1318,13 @@ private async Task RunBusyAsync(string stateText, Func<Task> action)
 
     private void SetBusy(bool busy, string stateText)
     {
+        bool sqliteActionsSupported = _currentStatus?.SqliteAccess.Supported != false;
         _busy = busy;
         UseWaitCursor = busy;
         _busyLabel.Text = stateText;
         _busyLabel.ForeColor = busy ? Color.DarkOrange : Color.DarkGreen;
         _browseButton.Enabled = !busy;
+        _browseSqliteHomeButton.Enabled = !busy;
         _refreshButton.Enabled = !busy;
         _addProviderButton.Enabled = !busy;
         _removeProviderButton.Enabled = !busy;
@@ -1196,8 +1333,8 @@ private void SetBusy(bool busy, string stateText)
         _restoreConfigCheck.Enabled = !busy;
         _restoreDatabaseCheck.Enabled = !busy;
         _restoreSessionsCheck.Enabled = !busy;
-        _executeButton.Enabled = !busy;
-        _restoreButton.Enabled = !busy;
+        _executeButton.Enabled = !busy && sqliteActionsSupported;
+        _restoreButton.Enabled = !busy && sqliteActionsSupported;
         _openBackupButton.Enabled = !busy;
         _pruneBackupsButton.Enabled = !busy;
         UpdateCheckButtonState();
@@ -1205,6 +1342,15 @@ private void SetBusy(bool busy, string stateText)
         _providerList.Enabled = !busy;
         _manualProviderText.Enabled = !busy;
         _codexHomeCombo.Enabled = !busy;
+        _sqliteHomeText.Enabled = !busy;
+    }
+
+    private static bool PathsEqual(string left, string right)
+    {
+        return string.Equals(
+            Path.GetFullPath(left),
+            Path.GetFullPath(right),
+            OperatingSystem.IsWindows() ? StringComparison.OrdinalIgnoreCase : StringComparison.Ordinal);
     }
 
     private void UpdateCheckButtonState()
diff --git a/desktop/CodexProviderSync.Core.Tests/CoreIntegrationTests.cs b/desktop/CodexProviderSync.Core.Tests/CoreIntegrationTests.cs
index 98748e5..8d7f816 100644
--- a/desktop/CodexProviderSync.Core.Tests/CoreIntegrationTests.cs
+++ b/desktop/CodexProviderSync.Core.Tests/CoreIntegrationTests.cs
@@ -1,10 +1,104 @@
 using System.Text.Json;
+using System.Diagnostics;
 using Microsoft.Data.Sqlite;
 
 namespace CodexProviderSync.Core.Tests;
 
 public sealed class CoreIntegrationTests
 {
+    [Fact]
+    public async Task GetStatus_ReportsWindowsWslUncSqliteHomeWithoutOpeningDatabase()
+    {
+        if (!OperatingSystem.IsWindows())
+        {
+            return;
+        }
+
+        TestCodexHomeFixture fixture = await TestCodexHomeFixture.CreateAsync();
+        await fixture.WriteConfigAsync("model_provider = \"openai\"");
+        string sqliteHome = $@"\\wsl.localhost\Ubuntu\tmp\codex-provider-sync-{Guid.NewGuid():N}";
+        Stopwatch timer = Stopwatch.StartNew();
+
+        StatusSnapshot status = await new CodexSyncService().GetStatusAsync(fixture.CodexHome, sqliteHome);
+
+        timer.Stop();
+        Assert.False(status.SqliteAccess.Supported);
+        Assert.Null(status.StateDbLocation);
+        Assert.Null(status.SqliteCounts);
+        Assert.Contains("Windows cannot safely access SQLite", TextFormatter.FormatStatus(status));
+        string chineseStatus = TextFormatter.FormatStatus(status, TextFormatter.ChineseSimplified);
+        Assert.Contains("Windows 进程无法通过 WSL UNC 路径安全访问 SQLite", chineseStatus);
+        Assert.Contains("请在 WSL 内运行 codex-provider", chineseStatus);
+        Assert.DoesNotContain("currently in use", TextFormatter.FormatStatus(status));
+        Assert.True(timer.Elapsed < TimeSpan.FromSeconds(5), $"Status took {timer.Elapsed}.");
+    }
+
+    [Fact]
+    public async Task RunSync_BlocksWindowsWslUncBeforeCreatingBackup()
+    {
+        if (!OperatingSystem.IsWindows())
+        {
+            return;
+        }
+
+        TestCodexHomeFixture fixture = await TestCodexHomeFixture.CreateAsync();
+        await fixture.WriteConfigAsync("model_provider = \"openai\"");
+
+        InvalidOperationException error = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => new CodexSyncService().RunSyncAsync(
+                fixture.CodexHome,
+                explicitSqliteHome: @"\\wsl.localhost\Ubuntu\home\user\.codex\sqlite"));
+
+        Assert.Contains("Cannot sync", error.Message);
+        Assert.Contains("Run codex-provider inside WSL", error.Message);
+        Assert.False(Directory.Exists(fixture.BackupRoot()));
+    }
+
+    [Fact]
+    public async Task RunSwitch_BlocksWindowsWslUncBeforeUpdatingConfig()
+    {
+        if (!OperatingSystem.IsWindows())
+        {
+            return;
+        }
+
+        TestCodexHomeFixture fixture = await TestCodexHomeFixture.CreateAsync();
+        await fixture.WriteConfigAsync("model_provider = \"openai\"");
+        string configPath = Path.Combine(fixture.CodexHome, "config.toml");
+        string originalConfig = await File.ReadAllTextAsync(configPath);
+
+        InvalidOperationException error = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => new CodexSyncService().RunSwitchAsync(
+                fixture.CodexHome,
+                "apigather",
+                explicitSqliteHome: @"\\wsl$\Ubuntu\home\user\.codex\sqlite"));
+
+        Assert.Contains("Cannot switch", error.Message);
+        Assert.Equal(originalConfig, await File.ReadAllTextAsync(configPath));
+        Assert.False(Directory.Exists(fixture.BackupRoot()));
+    }
+
+    [Fact]
+    public async Task RunRestore_BlocksWindowsWslUncBeforeReadingBackup()
+    {
+        if (!OperatingSystem.IsWindows())
+        {
+            return;
+        }
+
+        TestCodexHomeFixture fixture = await TestCodexHomeFixture.CreateAsync();
+        await fixture.WriteConfigAsync("model_provider = \"openai\"");
+
+        InvalidOperationException error = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => new CodexSyncService().RunRestoreAsync(
+                fixture.CodexHome,
+                Path.Combine(fixture.Root, "missing-backup"),
+                @"\\wsl.localhost\Ubuntu\home\user\.codex\sqlite"));
+
+        Assert.Contains("Cannot restore", error.Message);
+        Assert.Contains("Run codex-provider inside WSL", error.Message);
+    }
+
     [Fact]
     public async Task RunSync_RewritesRolloutFilesAndSqlite_ThenRestoreRevertsBoth()
     {
@@ -1352,7 +1446,10 @@ await File.AppendAllTextAsync(sessionPath, JsonSerializer.Serialize(new
                 payload.GetProperty("collaboration_mode").GetProperty("settings").GetProperty("model").GetString());
         }
 
-        await service.RunRestoreAsync(fixture.CodexHome, result.BackupDir);
+        await service.RunRestoreAsync(
+            fixture.CodexHome,
+            result.BackupDir,
+            new RestoreBackupOptions { RestoreDatabase = false });
         string restoredStaleLine = (await File.ReadAllLinesAsync(sessionPath))
             .Single(line => line.Contains("\"stale-turn\"", StringComparison.Ordinal));
         using JsonDocument restoredDocument = JsonDocument.Parse(restoredStaleLine);
@@ -1398,8 +1495,259 @@ await fixture.WriteBackupAsync(
         CodexSyncService service = new();
         await service.RunRestoreAsync(
             fixture.CodexHome,
-            fixture.BackupPath("20260723T000000000Z"));
+            fixture.BackupPath("20260723T000000000Z"),
+            new RestoreBackupOptions { RestoreDatabase = false });
 
         Assert.Equal(originalFirstLine, (await File.ReadAllLinesAsync(sessionPath))[0]);
     }
+
+    [Fact]
+    public async Task RunSync_UsesExplicitSqliteHomeWithoutTouchingDefaultDatabase()
+    {
+        TestCodexHomeFixture fixture = await TestCodexHomeFixture.CreateAsync();
+        await fixture.WriteConfigAsync("model_provider = \"openai\"");
+        await fixture.WriteStateDbAsync([("default-thread", "default-provider", false)]);
+        string sqliteHome = Path.Combine(fixture.Root, "external-sqlite");
+        string externalDbPath = Path.Combine(sqliteHome, AppConstants.DbFileBasename);
+        await fixture.WriteStateDbAtAsync(
+            externalDbPath,
+            [("external-thread", "custom", false)],
+            model: "old-model");
+
+        CodexSyncService service = new();
+        SyncResult result = await service.RunSyncAsync(
+            fixture.CodexHome,
+            model: "new-model",
+            explicitSqliteHome: sqliteHome);
+
+        Assert.Equal(Path.GetFullPath(sqliteHome), result.SqliteHome);
+        Assert.Equal("gui", result.SqliteHomeSource);
+        Assert.Equal("openai", await ReadProviderAsync(externalDbPath, "external-thread"));
+        Assert.Equal("default-provider", await ReadProviderAsync(fixture.StateDbPath(), "default-thread"));
+
+        BackupMetadataFile metadata = JsonSerializer.Deserialize<BackupMetadataFile>(
+            await File.ReadAllTextAsync(Path.Combine(result.BackupDir, "metadata.json")),
+            new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase })!;
+        Assert.Equal(2, metadata.Version);
+        Assert.Equal(Path.GetFullPath(sqliteHome), metadata.SqliteHome);
+        Assert.Empty(metadata.DbFiles);
+        Assert.Equal([AppConstants.DbFileBasename], metadata.SqliteDbFiles);
+    }
+
+    [Fact]
+    public async Task ConfiguredSqliteHomeWithoutDatabase_IsDiagnosticForStatusButBlocksSync()
+    {
+        TestCodexHomeFixture fixture = await TestCodexHomeFixture.CreateAsync();
+        string sqliteHome = Path.Combine(fixture.Root, "missing-sqlite");
+        await fixture.WriteConfigAsync($"model_provider = \"openai\"\nsqlite_home = '{sqliteHome}'");
+        await fixture.WriteStateDbAsync([("stale-thread", "custom", false)]);
+
+        CodexSyncService service = new();
+        StatusSnapshot status = await service.GetStatusAsync(fixture.CodexHome);
+
+        Assert.Equal(Path.GetFullPath(sqliteHome), status.SqliteHome);
+        Assert.Equal("config", status.SqliteHomeSource);
+        Assert.Null(status.StateDbLocation);
+        Assert.Single(status.CheckedStateDbPaths);
+        await Assert.ThrowsAsync<InvalidOperationException>(() => service.RunSyncAsync(fixture.CodexHome));
+        Assert.Equal("custom", await ReadProviderAsync(fixture.StateDbPath(), "stale-thread"));
+    }
+
+    [Fact]
+    public async Task RestoreVersionTwo_RebuildsMissingDefaultSqliteDatabase()
+    {
+        TestCodexHomeFixture fixture = await TestCodexHomeFixture.CreateAsync();
+        await fixture.WriteConfigAsync("model_provider = \"openai\"");
+        await fixture.WriteStateDbAsync([("thread-missing-default", "custom", false)]);
+
+        CodexSyncService service = new();
+        SyncResult syncResult = await service.RunSyncAsync(fixture.CodexHome);
+        File.Delete(fixture.StateDbPath());
+
+        await service.RunRestoreAsync(
+            fixture.CodexHome,
+            syncResult.BackupDir,
+            new RestoreBackupOptions
+            {
+                RestoreConfig = false,
+                RestoreDatabase = true,
+                RestoreSessions = false
+            });
+
+        Assert.Equal("custom", await ReadProviderAsync(fixture.StateDbPath(), "thread-missing-default"));
+    }
+
+    [Fact]
+    public async Task RestoreVersionTwo_RebuildsMissingLegacyRootSqliteDatabaseInPlace()
+    {
+        TestCodexHomeFixture fixture = await TestCodexHomeFixture.CreateAsync();
+        await fixture.WriteConfigAsync("model_provider = \"openai\"");
+        await fixture.WriteLegacyStateDbAsync([("thread-missing-legacy", "custom", false)]);
+
+        CodexSyncService service = new();
+        SyncResult syncResult = await service.RunSyncAsync(fixture.CodexHome);
+        File.Delete(fixture.LegacyStateDbPath());
+
+        await service.RunRestoreAsync(
+            fixture.CodexHome,
+            syncResult.BackupDir,
+            new RestoreBackupOptions
+            {
+                RestoreConfig = false,
+                RestoreDatabase = true,
+                RestoreSessions = false
+            });
+
+        Assert.False(File.Exists(fixture.StateDbPath()));
+        Assert.Equal("custom", await ReadProviderAsync(fixture.LegacyStateDbPath(), "thread-missing-legacy"));
+    }
+
+    [Fact]
+    public async Task RestoreVersionOne_RebuildsMissingDefaultSqliteDatabase()
+    {
+        TestCodexHomeFixture fixture = await TestCodexHomeFixture.CreateAsync();
+        await fixture.WriteConfigAsync("model_provider = \"openai\"");
+        string backupDir = fixture.BackupPath("20260728T010000000Z");
+        string relativeDbPath = Path.Combine(AppConstants.SqliteDirBasename, AppConstants.DbFileBasename);
+        string backupDbPath = Path.Combine(backupDir, "db", relativeDbPath);
+        await fixture.WriteStateDbAtAsync(
+            backupDbPath,
+            [("thread-v1-missing", "custom", false)],
+            model: null);
+        string metadata = JsonSerializer.Serialize(new
+        {
+            version = 1,
+            @namespace = AppConstants.BackupNamespace,
+            codexHome = fixture.CodexHome,
+            targetProvider = "custom",
+            createdAt = DateTimeOffset.UtcNow,
+            dbFiles = new[] { relativeDbPath },
+            changedSessionFiles = 0
+        });
+        await File.WriteAllTextAsync(Path.Combine(backupDir, "metadata.json"), metadata);
+
+        CodexSyncService service = new();
+        await service.RunRestoreAsync(
+            fixture.CodexHome,
+            backupDir,
+            new RestoreBackupOptions
+            {
+                RestoreConfig = false,
+                RestoreDatabase = true,
+                RestoreSessions = false
+            });
+
+        Assert.Equal("custom", await ReadProviderAsync(fixture.StateDbPath(), "thread-v1-missing"));
+    }
+
+    [Fact]
+    public async Task RestoreVersionTwo_RequiresExplicitRelocationConfirmation()
+    {
+        TestCodexHomeFixture fixture = await TestCodexHomeFixture.CreateAsync();
+        await fixture.WriteConfigAsync("model_provider = \"openai\"");
+        string sourceSqliteHome = Path.Combine(fixture.Root, "source-sqlite");
+        string sourceDbPath = Path.Combine(sourceSqliteHome, AppConstants.DbFileBasename);
+        await fixture.WriteStateDbAtAsync(sourceDbPath, [("thread-a", "custom", false)], model: null);
+
+        CodexSyncService service = new();
+        SyncResult syncResult = await service.RunSyncAsync(
+            fixture.CodexHome,
+            explicitSqliteHome: sourceSqliteHome);
+
+        string targetSqliteHome = Path.Combine(fixture.Root, "target-sqlite");
+        string targetDbPath = Path.Combine(targetSqliteHome, AppConstants.DbFileBasename);
+        await fixture.WriteStateDbAtAsync(targetDbPath, [("thread-a", "target", false)], model: null);
+        RestoreBackupOptions deniedOptions = new()
+        {
+            RestoreConfig = false,
+            RestoreDatabase = true,
+            RestoreSessions = false
+        };
+
+        await Assert.ThrowsAsync<InvalidOperationException>(() => service.RunRestoreAsync(
+            fixture.CodexHome,
+            syncResult.BackupDir,
+            deniedOptions,
+            targetSqliteHome));
+        Assert.Equal("target", await ReadProviderAsync(targetDbPath, "thread-a"));
+
+        InvalidOperationException configError = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => service.RunRestoreAsync(
+                fixture.CodexHome,
+                syncResult.BackupDir,
+                new RestoreBackupOptions
+                {
+                    RestoreConfig = true,
+                    RestoreDatabase = true,
+                    RestoreSessions = false,
+                    AllowSqliteHomeRelocation = true
+                },
+                targetSqliteHome));
+        Assert.Contains("Cannot restore config.toml while relocating SQLite home", configError.Message);
+        Assert.Equal("target", await ReadProviderAsync(targetDbPath, "thread-a"));
+
+        await service.RunRestoreAsync(
+            fixture.CodexHome,
+            syncResult.BackupDir,
+            new RestoreBackupOptions
+            {
+                RestoreConfig = false,
+                RestoreDatabase = true,
+                RestoreSessions = false,
+                AllowSqliteHomeRelocation = true
+            },
+            targetSqliteHome);
+        Assert.Equal("custom", await ReadProviderAsync(targetDbPath, "thread-a"));
+    }
+
+    [Fact]
+    public async Task RestoreVersionTwo_ValidatesDatabaseFilesBeforeRestoringConfig()
+    {
+        TestCodexHomeFixture fixture = await TestCodexHomeFixture.CreateAsync();
+        await fixture.WriteConfigAsync("model_provider = \"current\"");
+        await fixture.WriteStateDbAsync([("thread-a", "current", false)]);
+        string backupDir = fixture.BackupPath("20260728T000000000Z");
+        string metadata = JsonSerializer.Serialize(new
+        {
+            version = 2,
+            @namespace = AppConstants.BackupNamespace,
+            codexHome = fixture.CodexHome,
+            sqliteHome = Path.GetDirectoryName(fixture.StateDbPath()),
+            targetProvider = "backup",
+            createdAt = DateTimeOffset.UtcNow,
+            dbFiles = Array.Empty<string>(),
+            sqliteDbFiles = new[] { AppConstants.DbFileBasename },
+            changedSessionFiles = 0
+        });
+        await fixture.WriteBackupAsync(
+            "20260728T000000000Z",
+            ("metadata.json", metadata),
+            ("config.toml", "model_provider = \"backup\"\n"));
+
+        CodexSyncService service = new();
+        await Assert.ThrowsAsync<InvalidOperationException>(() => service.RunRestoreAsync(
+            fixture.CodexHome,
+            backupDir,
+            new RestoreBackupOptions { RestoreSessions = false }));
+
+        Assert.Contains(
+            "model_provider = \"current\"",
+            await File.ReadAllTextAsync(Path.Combine(fixture.CodexHome, "config.toml")));
+    }
+
+    private static async Task<string> ReadProviderAsync(string dbPath, string threadId)
+    {
+        SqliteConnectionStringBuilder builder = new()
+        {
+            DataSource = dbPath,
+            Mode = SqliteOpenMode.ReadOnly,
+            Pooling = false
+        };
+        await using SqliteConnection connection = new(builder.ConnectionString);
+        await connection.OpenAsync();
+        SqliteCommand command = connection.CreateCommand();
+        command.CommandText = "SELECT model_provider FROM threads WHERE id = $id";
+        command.Parameters.AddWithValue("$id", threadId);
+        return Convert.ToString(await command.ExecuteScalarAsync())!;
+    }
 }
diff --git a/desktop/CodexProviderSync.Core.Tests/SettingsAndDiscoveryTests.cs b/desktop/CodexProviderSync.Core.Tests/SettingsAndDiscoveryTests.cs
index 01bfbb0..7a3f958 100644
--- a/desktop/CodexProviderSync.Core.Tests/SettingsAndDiscoveryTests.cs
+++ b/desktop/CodexProviderSync.Core.Tests/SettingsAndDiscoveryTests.cs
@@ -2,6 +2,74 @@ namespace CodexProviderSync.Core.Tests;
 
 public sealed class SettingsAndDiscoveryTests
 {
+    [Fact]
+    public void ConfigFileService_ReadsBasicAndLiteralSqliteHome()
+    {
+        ConfigFileService service = new();
+
+        Assert.Equal(
+            @"C:\Users\cheng\.codex\sqlite",
+            service.ReadSqliteHomeFromConfigText("sqlite_home = 'C:\\Users\\cheng\\.codex\\sqlite'\n[model_providers.custom]\n"));
+        Assert.Equal(
+            "C:\\Users\\cheng\\.codex\\sqlite",
+            service.ReadSqliteHomeFromConfigText("sqlite_home = \"C:\\\\Users\\\\cheng\\\\.codex\\\\sqlite\" # comment\n"));
+    }
+
+    [Fact]
+    public void StorageLayout_UsesExplicitConfigEnvironmentAndDefaultPrecedence()
+    {
+        string root = Path.Combine(Path.GetTempPath(), $"storage-layout-{Guid.NewGuid():N}");
+        string codexHome = Path.Combine(root, ".codex");
+        CodexStorageLayoutService service = new();
+        Dictionary<string, string?> environment = new()
+        {
+            ["CODEX_SQLITE_HOME"] = Path.Combine(root, "env")
+        };
+
+        CodexStorageLayout explicitLayout = service.Resolve(
+            codexHome,
+            Path.Combine(root, "explicit"),
+            $"sqlite_home = '{Path.Combine(root, "config")}'\n",
+            environment);
+        CodexStorageLayout configLayout = service.Resolve(
+            codexHome,
+            null,
+            $"sqlite_home = '{Path.Combine(root, "config")}'\n",
+            environment);
+        CodexStorageLayout environmentLayout = service.Resolve(codexHome, null, string.Empty, environment);
+        CodexStorageLayout defaultLayout = service.Resolve(
+            codexHome,
+            null,
+            string.Empty,
+            new Dictionary<string, string?>());
+
+        Assert.Equal("gui", explicitLayout.SqliteHomeSource);
+        Assert.Equal("config", configLayout.SqliteHomeSource);
+        Assert.Equal("env", environmentLayout.SqliteHomeSource);
+        Assert.Equal("default", defaultLayout.SqliteHomeSource);
+        Assert.Single(explicitLayout.StateDbCandidates);
+        Assert.Equal(2, defaultLayout.StateDbCandidates.Count);
+    }
+
+    [Theory]
+    [InlineData(@"\\wsl.localhost\Ubuntu\home\user\.codex\sqlite")]
+    [InlineData(@"\\WSL$\Ubuntu\home\user\.codex\sqlite")]
+    [InlineData(@"\\?\UNC\wsl.localhost\Ubuntu\home\user\.codex\sqlite")]
+    public void StorageLayout_RejectsWslUncSqliteHomesOnlyForWindowsProcesses(string sqliteHome)
+    {
+        string codexHome = Path.Combine(Path.GetTempPath(), $"storage-layout-{Guid.NewGuid():N}", ".codex");
+        CodexStorageLayout layout = new CodexStorageLayoutService().Resolve(
+            codexHome,
+            sqliteHome,
+            string.Empty,
+            new Dictionary<string, string?>());
+
+        Assert.Equal(!OperatingSystem.IsWindows(), layout.SqliteAccess.Supported);
+        Assert.Equal(
+            OperatingSystem.IsWindows() ? "windows-wsl-unc" : null,
+            layout.SqliteAccess.Reason);
+    }
+
     [Fact]
     public void ConfigFileService_UpdatesCompactRootModelAssignment()
     {
@@ -52,6 +120,24 @@ public async Task SettingsService_PersistsRecentPathsAndProviders()
         Assert.Equal(new DateOnly(2026, 7, 23), loaded.LastAutomaticUpdateCheckDate);
     }
 
+    [Fact]
+    public async Task SettingsService_PersistsSqliteHomeOverridePerCodexHome()
+    {
+        string root = Path.Combine(Path.GetTempPath(), $"codex-provider-settings-{Guid.NewGuid():N}");
+        SettingsService service = new(Path.Combine(root, "settings.json"));
+        string codexHomeA = Path.Combine(root, "codex-a");
+        string codexHomeB = Path.Combine(root, "codex-b");
+        string sqliteHomeA = Path.Combine(root, "sqlite-a");
+
+        AppSettings settings = service.RecordSqliteHomeOverride(new AppSettings(), codexHomeA, sqliteHomeA);
+        settings = service.RecordCodexHome(settings, codexHomeB);
+        await service.SaveAsync(settings);
+        AppSettings loaded = await service.LoadAsync();
+
+        Assert.Equal(Path.GetFullPath(sqliteHomeA), service.GetSqliteHomeOverride(loaded, codexHomeA));
+        Assert.Null(service.GetSqliteHomeOverride(loaded, codexHomeB));
+    }
+
     [Fact]
     public async Task SettingsService_OldSettingsDefaultToNoAutomaticUpdateCheck()
     {
diff --git a/desktop/CodexProviderSync.Core.Tests/TestEnvironment.cs b/desktop/CodexProviderSync.Core.Tests/TestEnvironment.cs
new file mode 100644
index 0000000..6e7a31f
--- /dev/null
+++ b/desktop/CodexProviderSync.Core.Tests/TestEnvironment.cs
@@ -0,0 +1,12 @@
+using System.Runtime.CompilerServices;
+
+namespace CodexProviderSync.Core.Tests;
+
+internal static class TestEnvironment
+{
+    [ModuleInitializer]
+    internal static void Initialize()
+    {
+        Environment.SetEnvironmentVariable("CODEX_SQLITE_HOME", null);
+    }
+}
diff --git a/desktop/CodexProviderSync.Core.Tests/UpdateServiceTests.cs b/desktop/CodexProviderSync.Core.Tests/UpdateServiceTests.cs
index 029c63c..c73744e 100644
--- a/desktop/CodexProviderSync.Core.Tests/UpdateServiceTests.cs
+++ b/desktop/CodexProviderSync.Core.Tests/UpdateServiceTests.cs
@@ -2,7 +2,6 @@
 using System.Net.Http;
 using System.Security.Cryptography;
 using System.Text;
-using System.Diagnostics;
 
 namespace CodexProviderSync.Core.Tests;
 
@@ -75,7 +74,7 @@ public async Task CheckForUpdate_TimesOutUsingConfiguredDeadline()
     }
 
     [Fact]
-    public async Task CheckForUpdate_ApiFallbackSharesOneTotalDeadline()
+    public async Task CheckForUpdate_ApiFallbackHonorsConfiguredDeadline()
     {
         CancellationToken firstToken = default;
         CancellationToken fallbackToken = default;
@@ -84,24 +83,20 @@ public async Task CheckForUpdate_ApiFallbackSharesOneTotalDeadline()
             if (request.RequestUri!.Host == "api.github.com")
             {
                 firstToken = cancellationToken;
-                await Task.Delay(300, cancellationToken);
                 return new HttpResponseMessage(HttpStatusCode.Forbidden);
             }
 
             fallbackToken = cancellationToken;
             await Task.Delay(Timeout.InfiniteTimeSpan, cancellationToken);
-            throw new InvalidOperationException("The shared deadline should stop the fallback request.");
+            throw new InvalidOperationException("The configured deadline should stop the fallback request.");
         });
-        UpdateService service = new(client, TimeSpan.FromMilliseconds(400));
-        Stopwatch timer = Stopwatch.StartNew();
+        UpdateService service = new(client, TimeSpan.FromMilliseconds(100));
 
         await Assert.ThrowsAsync<TimeoutException>(
             () => service.CheckForUpdateAsync(new Version(0, 3, 1)));
 
-        timer.Stop();
         Assert.True(firstToken.CanBeCanceled);
         Assert.True(fallbackToken.CanBeCanceled);
-        Assert.InRange(timer.ElapsedMilliseconds, 350, 550);
     }
 
     [Fact]
diff --git a/desktop/CodexProviderSync.Core.Tests/WslSqliteSafetyTests.cs b/desktop/CodexProviderSync.Core.Tests/WslSqliteSafetyTests.cs
new file mode 100644
index 0000000..b266c6a
--- /dev/null
+++ b/desktop/CodexProviderSync.Core.Tests/WslSqliteSafetyTests.cs
@@ -0,0 +1,73 @@
+using System.Diagnostics;
+
+namespace CodexProviderSync.Core.Tests;
+
+public sealed class WslSqliteSafetyTests
+{
+    [WindowsWslIntegrationFact]
+    [Trait("Category", "WindowsWslIntegration")]
+    public async Task WindowsCore_DoesNotTouchRealWslSqliteHome()
+    {
+        string sqliteHome = Environment.GetEnvironmentVariable("CODEX_PROVIDER_SYNC_WSL_SQLITE_HOME")!;
+
+        Assert.True(OperatingSystem.IsWindows(), "This integration test must run in a Windows process.");
+        TestCodexHomeFixture fixture = await TestCodexHomeFixture.CreateAsync();
+        await fixture.WriteConfigAsync("model_provider = \"openai\"");
+        string rolloutPath = fixture.RolloutPath("sessions", "rollout-wsl-safety.jsonl");
+        await fixture.WriteRolloutAsync(rolloutPath, "thread-wsl-safety", "apigather");
+        string configPath = Path.Combine(fixture.CodexHome, "config.toml");
+        string originalConfig = await File.ReadAllTextAsync(configPath);
+        string originalRollout = await File.ReadAllTextAsync(rolloutPath);
+        CodexSyncService syncService = new();
+
+        Stopwatch timer = Stopwatch.StartNew();
+        StatusSnapshot status = await syncService.GetStatusAsync(fixture.CodexHome, sqliteHome);
+        timer.Stop();
+
+        Assert.False(status.SqliteAccess.Supported);
+        Assert.Equal("windows-wsl-unc", status.SqliteAccess.Reason);
+        Assert.Null(status.SqliteCounts);
+        Assert.True(timer.Elapsed < TimeSpan.FromSeconds(5), $"Status took {timer.Elapsed}.");
+
+        InvalidOperationException syncError = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => syncService.RunSyncAsync(fixture.CodexHome, explicitSqliteHome: sqliteHome));
+        InvalidOperationException switchError = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => syncService.RunSwitchAsync(fixture.CodexHome, "apigather", explicitSqliteHome: sqliteHome));
+        InvalidOperationException restoreError = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => syncService.RunRestoreAsync(
+                fixture.CodexHome,
+                Path.Combine(fixture.Root, "missing-backup"),
+                sqliteHome));
+        CodexStorageLayout storage = new CodexStorageLayoutService().Resolve(
+            fixture.CodexHome,
+            sqliteHome,
+            originalConfig,
+            new Dictionary<string, string?>());
+        BackupService backupService = new(new SessionRolloutService(), new SqliteStateService());
+        InvalidOperationException backupError = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => backupService.CreateBackupAsync(
+                storage,
+                "openai",
+                [],
+                configPath));
+
+        Assert.Contains("Cannot sync", syncError.Message);
+        Assert.Contains("Cannot switch", switchError.Message);
+        Assert.Contains("Cannot restore", restoreError.Message);
+        Assert.Contains("Cannot create a backup", backupError.Message);
+        Assert.Equal(originalConfig, await File.ReadAllTextAsync(configPath));
+        Assert.Equal(originalRollout, await File.ReadAllTextAsync(rolloutPath));
+        Assert.False(Directory.Exists(fixture.BackupRoot()));
+    }
+}
+
+public sealed class WindowsWslIntegrationFactAttribute : FactAttribute
+{
+    public WindowsWslIntegrationFactAttribute()
+    {
+        if (string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable("CODEX_PROVIDER_SYNC_WSL_SQLITE_HOME")))
+        {
+            Skip = "Run scripts/test-wsl-unc-safety.sh from WSL to provide a real ext4 SQLite Home.";
+        }
+    }
+}
diff --git a/desktop/CodexProviderSync.Core/BackupService.cs b/desktop/CodexProviderSync.Core/BackupService.cs
index 62f407e..a6a1e25 100644
--- a/desktop/CodexProviderSync.Core/BackupService.cs
+++ b/desktop/CodexProviderSync.Core/BackupService.cs
@@ -20,21 +20,52 @@ public async Task<string> CreateBackupAsync(
         string configPath,
         string? configBackupText = null)
     {
+        return await CreateBackupAsync(
+            new CodexStorageLayoutService().CreateDefault(codexHome),
+            targetProvider,
+            sessionChanges,
+            configPath,
+            configBackupText);
+    }
+
+    public async Task<string> CreateBackupAsync(
+        CodexStorageLayout storage,
+        string targetProvider,
+        IReadOnlyList<SessionChange> sessionChanges,
+        string configPath,
+        string? configBackupText = null)
+    {
+        storage.EnsureSqliteAccessSupported("create a backup");
+        string codexHome = storage.CodexHome;
         string backupRoot = AppConstants.DefaultBackupRoot(codexHome);
         string backupDir = Path.Combine(backupRoot, DateTimeOffset.UtcNow.ToString("yyyyMMdd'T'HHmmssfff'Z'"));
         string dbDir = Path.Combine(backupDir, "db");
         Directory.CreateDirectory(dbDir);
 
         List<string> copiedDbFiles = [];
-        StateDbLocation? stateDb = _sqliteStateService.DetectStateDb(codexHome);
+        List<string> copiedSqliteDbFiles = [];
+        StateDbLocation? stateDb = storage.StateDbLocation ?? _sqliteStateService.DetectStateDb(storage);
+        string actualSqliteHome = stateDb is null ? storage.SqliteHome : Path.GetDirectoryName(stateDb.Path)!;
         if (stateDb is not null)
         {
             foreach (string suffix in new[] { string.Empty, "-shm", "-wal" })
             {
-                string relativePath = DbBackupRelativePath(codexHome, stateDb.Path, suffix);
-                if (await CopyIfPresentAsync(stateDb.Path + suffix, Path.Combine(dbDir, relativePath), overwrite: false))
+                string sourcePath = stateDb.Path + suffix;
+                string sqliteRelativePath = AppConstants.DbFileBasename + suffix;
+                if (!await CopyIfPresentAsync(
+                    sourcePath,
+                    Path.Combine(dbDir, "sqlite-home", sqliteRelativePath),
+                    overwrite: false))
+                {
+                    continue;
+                }
+
+                copiedSqliteDbFiles.Add(sqliteRelativePath);
+                string? legacyRelativePath = SafeRelativePath(codexHome, sourcePath);
+                if (legacyRelativePath is not null)
                 {
-                    copiedDbFiles.Add(relativePath);
+                    await CopyIfPresentAsync(sourcePath, Path.Combine(dbDir, legacyRelativePath), overwrite: false);
+                    copiedDbFiles.Add(legacyRelativePath);
                 }
             }
         }
@@ -81,12 +112,14 @@ await File.WriteAllTextAsync(
 
         BackupMetadataFile metadata = new()
         {
-            Version = 1,
+            Version = 2,
             Namespace = AppConstants.BackupNamespace,
             CodexHome = codexHome,
+            SqliteHome = actualSqliteHome,
             TargetProvider = targetProvider,
             CreatedAt = createdAt,
             DbFiles = copiedDbFiles,
+            SqliteDbFiles = copiedSqliteDbFiles,
             ChangedSessionFiles = sessionChanges.Count
         };
         await File.WriteAllTextAsync(
@@ -101,13 +134,33 @@ public async Task<RestoreResult> RestoreBackupAsync(
         string codexHome,
         RestoreBackupOptions? options = null)
     {
+        return await RestoreBackupAsync(
+            backupDir,
+            new CodexStorageLayoutService().CreateDefault(codexHome),
+            options);
+    }
+
+    public async Task<RestoreResult> RestoreBackupAsync(
+        string backupDir,
+        CodexStorageLayout storage,
+        RestoreBackupOptions? options = null)
+    {
+        storage.EnsureSqliteAccessSupported("restore");
         options ??= new RestoreBackupOptions();
+        string codexHome = storage.CodexHome;
         string normalizedBackupDir = Path.GetFullPath(backupDir);
+        string metadataPath = Path.Combine(normalizedBackupDir, "metadata.json");
         BackupMetadataFile metadata = JsonSerializer.Deserialize<BackupMetadataFile>(
-            await File.ReadAllTextAsync(Path.Combine(normalizedBackupDir, "metadata.json")),
+            await File.ReadAllTextAsync(metadataPath),
             JsonOptions()) ?? throw new InvalidOperationException($"Backup metadata is invalid: {backupDir}");
 
-        if (!string.Equals(metadata.CodexHome, codexHome, StringComparison.Ordinal))
+        if (!string.Equals(metadata.Namespace, AppConstants.BackupNamespace, StringComparison.Ordinal)
+            || metadata.Version is not (1 or 2))
+        {
+            throw new InvalidOperationException($"Unsupported backup metadata in {metadataPath}.");
+        }
+
+        if (!PathsEqual(metadata.CodexHome, codexHome))
         {
             throw new InvalidOperationException($"Backup was created for {metadata.CodexHome}, not {codexHome}.");
         }
@@ -123,45 +176,105 @@ await _sessionRolloutService.AssertSessionFilesWritableAsync(
                 sessionManifest.Files.Select(static entry => entry.Path));
         }
 
+        List<(string SourcePath, string TargetPath)> databaseEntries = [];
+        List<string> sidecarsToRemove = [];
+        if (options.RestoreDatabase)
+        {
+            StateDbLocation? stateDb = storage.StateDbLocation ?? _sqliteStateService.DetectStateDb(storage);
+            if (stateDb is null && storage.HasConfiguredSqliteHome)
+            {
+                throw new InvalidOperationException(
+                    $"state_5.sqlite not found in SQLite home {storage.SqliteHome}.");
+            }
+
+            string targetSqliteHome = ResolveRestoreSqliteHome(storage, metadata, stateDb);
+            bool sqliteHomeRelocation = metadata.Version >= 2
+                && !string.IsNullOrWhiteSpace(metadata.SqliteHome)
+                && !PathsEqual(metadata.SqliteHome, targetSqliteHome);
+            if (sqliteHomeRelocation && !options.AllowSqliteHomeRelocation)
+            {
+                throw new InvalidOperationException(
+                    $"Backup SQLite home is {metadata.SqliteHome}, but the current target is {targetSqliteHome}. "
+                    + "Confirm SQLite Home relocation before restoring to a different location.");
+            }
+            if (sqliteHomeRelocation && options.RestoreConfig)
+            {
+                throw new InvalidOperationException(
+                    "Cannot restore config.toml while relocating SQLite home. "
+                    + "Disable config restore to preserve the current target configuration.");
+            }
+
+            if (stateDb is not null)
+            {
+                CodexStorageLayout detectedStorage = storage with { StateDbLocation = stateDb };
+                await _sqliteStateService.AssertSqliteWritableAsync(detectedStorage);
+            }
+
+            IReadOnlyList<string> databaseFiles = metadata.Version >= 2
+                ? metadata.SqliteDbFiles ?? []
+                : metadata.DbFiles ?? [];
+            if (!databaseFiles.Any(static fileName => Path.GetFileName(fileName) == AppConstants.DbFileBasename))
+            {
+                throw new InvalidOperationException(
+                    "Backup does not contain state_5.sqlite. Disable database restore to restore the remaining data.");
+            }
+            string databaseBackupRoot = metadata.Version >= 2
+                ? Path.Combine(normalizedBackupDir, "db", "sqlite-home")
+                : Path.Combine(normalizedBackupDir, "db");
+            string restoreRoot = metadata.Version >= 2 ? targetSqliteHome : codexHome;
+            foreach (string fileName in databaseFiles)
+            {
+                string targetPath = metadata.Version >= 2
+                    ? RestoreSqliteTargetPath(restoreRoot, fileName)
+                    : RestoreDbTargetPath(restoreRoot, fileName);
+                string sourcePath = Path.Combine(databaseBackupRoot, fileName);
+                if (!File.Exists(sourcePath))
+                {
+                    throw new InvalidOperationException($"Backup declares a missing SQLite file: {sourcePath}");
+                }
+                databaseEntries.Add((sourcePath, targetPath));
+            }
+
+            HashSet<string> backedUpFiles = new(databaseFiles, StringComparer.Ordinal);
+            foreach (string baseFile in databaseFiles.Where(
+                static fileName => Path.GetFileName(fileName) == AppConstants.DbFileBasename))
+            {
+                string basePath = metadata.Version >= 2
+                    ? RestoreSqliteTargetPath(restoreRoot, baseFile)
+                    : RestoreDbTargetPath(restoreRoot, baseFile);
+                foreach (string suffix in new[] { "-shm", "-wal" })
+                {
+                    if (!backedUpFiles.Contains(baseFile + suffix))
+                    {
+                        sidecarsToRemove.Add(basePath + suffix);
+                    }
+                }
+            }
+        }
+
         if (options.RestoreConfig)
         {
             await CopyIfPresentAsync(
                 Path.Combine(normalizedBackupDir, "config.toml"),
                 Path.Combine(codexHome, "config.toml"),
                 overwrite: true);
-            await CopyIfPresentAsync(
-                Path.Combine(normalizedBackupDir, AppConstants.GlobalStateFileBasename),
-                Path.Combine(codexHome, AppConstants.GlobalStateFileBasename),
-                overwrite: true);
-            await CopyIfPresentAsync(
-                Path.Combine(normalizedBackupDir, AppConstants.GlobalStateBackupFileBasename),
-                Path.Combine(codexHome, AppConstants.GlobalStateBackupFileBasename),
-                overwrite: true);
+            await RestoreGlobalStateFilesAsync(normalizedBackupDir, codexHome);
         }
 
         if (options.RestoreDatabase)
         {
-            await _sqliteStateService.AssertSqliteWritableAsync(codexHome);
-            string dbDir = Path.Combine(normalizedBackupDir, "db");
-            HashSet<string> backedUpFiles = new(metadata.DbFiles, StringComparer.Ordinal);
-
-            foreach (string baseFile in metadata.DbFiles.Where(static fileName => Path.GetFileName(fileName) == AppConstants.DbFileBasename))
+            foreach (string sidecarPath in sidecarsToRemove)
             {
-                string basePath = RestoreDbTargetPath(codexHome, baseFile);
-                foreach (string suffix in new[] { "-shm", "-wal" })
+                if (File.Exists(sidecarPath))
                 {
-                    string sidecarFile = baseFile + suffix;
-                    string sidecarPath = basePath + suffix;
-                    if (!backedUpFiles.Contains(sidecarFile) && File.Exists(sidecarPath))
-                    {
-                        File.Delete(sidecarPath);
-                    }
+                    File.Delete(sidecarPath);
                 }
             }
 
-            foreach (string fileName in metadata.DbFiles)
+            foreach ((string sourcePath, string targetPath) in databaseEntries)
             {
-                await CopyIfPresentAsync(Path.Combine(dbDir, fileName), RestoreDbTargetPath(codexHome, fileName), overwrite: true);
+                Directory.CreateDirectory(Path.GetDirectoryName(targetPath)!);
+                File.Copy(sourcePath, targetPath, overwrite: true);
             }
         }
 
@@ -215,9 +328,11 @@ await File.ReadAllTextAsync(metadataPath),
             Version = metadata.Version,
             Namespace = metadata.Namespace,
             CodexHome = metadata.CodexHome,
+            SqliteHome = metadata.SqliteHome,
             TargetProvider = metadata.TargetProvider,
             CreatedAt = metadata.CreatedAt,
             DbFiles = metadata.DbFiles,
+            SqliteDbFiles = metadata.SqliteDbFiles,
             ChangedSessionFiles = sessionChanges.Count
         };
 
@@ -238,6 +353,24 @@ await CopyIfPresentAsync(
             overwrite: true);
     }
 
+    public async Task<BackupStorageInfo> GetBackupStorageInfoAsync(string backupDir)
+    {
+        string metadataPath = Path.Combine(Path.GetFullPath(backupDir), "metadata.json");
+        BackupMetadataFile metadata = JsonSerializer.Deserialize<BackupMetadataFile>(
+            await File.ReadAllTextAsync(metadataPath),
+            JsonOptions()) ?? throw new InvalidOperationException($"Backup metadata is invalid: {backupDir}");
+        if (!string.Equals(metadata.Namespace, AppConstants.BackupNamespace, StringComparison.Ordinal)
+            || metadata.Version is not (1 or 2))
+        {
+            throw new InvalidOperationException($"Unsupported backup metadata in {metadataPath}.");
+        }
+        return new BackupStorageInfo
+        {
+            Version = metadata.Version,
+            SqliteHome = metadata.SqliteHome
+        };
+    }
+
     public Task<BackupSummary> GetBackupSummaryAsync(string codexHome)
     {
         string backupRoot = AppConstants.DefaultBackupRoot(codexHome);
@@ -317,13 +450,14 @@ private static async Task<bool> CopyIfPresentAsync(string sourcePath, string des
         return true;
     }
 
-    private static string DbBackupRelativePath(string codexHome, string dbPath, string suffix)
+    private static string? SafeRelativePath(string root, string target)
     {
-        string relativePath = Path.GetRelativePath(codexHome, dbPath + suffix);
-        return !relativePath.StartsWith("..", StringComparison.Ordinal)
+        string relativePath = Path.GetRelativePath(root, target);
+        return !string.IsNullOrEmpty(relativePath)
+            && !relativePath.StartsWith("..", StringComparison.Ordinal)
             && !Path.IsPathRooted(relativePath)
             ? relativePath
-            : AppConstants.DbFileBasename + suffix;
+            : null;
     }
 
     private static string RestoreDbTargetPath(string codexHome, string relativePath)
@@ -337,6 +471,48 @@ private static string RestoreDbTargetPath(string codexHome, string relativePath)
         return Path.Combine(codexHome, relativePath);
     }
 
+    private static string RestoreSqliteTargetPath(string sqliteHome, string relativePath)
+    {
+        if (Path.IsPathRooted(relativePath)
+            || relativePath.Split(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar).Contains("..", StringComparer.Ordinal))
+        {
+            throw new InvalidOperationException($"Invalid SQLite backup path: {relativePath}");
+        }
+
+        return Path.Combine(sqliteHome, relativePath);
+    }
+
+    private static string ResolveRestoreSqliteHome(
+        CodexStorageLayout storage,
+        BackupMetadataFile metadata,
+        StateDbLocation? stateDb)
+    {
+        if (stateDb is not null)
+        {
+            return Path.GetDirectoryName(stateDb.Path)!;
+        }
+        if (metadata.Version >= 2
+            && !string.IsNullOrWhiteSpace(metadata.SqliteHome)
+            && !storage.HasConfiguredSqliteHome)
+        {
+            StateDbLocation? matchingCandidate = storage.StateDbCandidates.FirstOrDefault(
+                candidate => PathsEqual(Path.GetDirectoryName(candidate.Path)!, metadata.SqliteHome));
+            if (matchingCandidate is not null)
+            {
+                return Path.GetDirectoryName(matchingCandidate.Path)!;
+            }
+        }
+        return storage.SqliteHome;
+    }
+
+    private static bool PathsEqual(string left, string right)
+    {
+        StringComparison comparison = OperatingSystem.IsWindows()
+            ? StringComparison.OrdinalIgnoreCase
+            : StringComparison.Ordinal;
+        return string.Equals(Path.GetFullPath(left), Path.GetFullPath(right), comparison);
+    }
+
     private static JsonSerializerOptions JsonOptions()
     {
         return new JsonSerializerOptions
diff --git a/desktop/CodexProviderSync.Core/CodexStorageLayoutService.cs b/desktop/CodexProviderSync.Core/CodexStorageLayoutService.cs
new file mode 100644
index 0000000..2471dc3
--- /dev/null
+++ b/desktop/CodexProviderSync.Core/CodexStorageLayoutService.cs
@@ -0,0 +1,112 @@
+namespace CodexProviderSync.Core;
+
+public sealed class CodexStorageLayoutService
+{
+    private readonly CodexHomeService _codexHomeService;
+    private readonly ConfigFileService _configFileService;
+
+    public CodexStorageLayoutService(
+        CodexHomeService? codexHomeService = null,
+        ConfigFileService? configFileService = null)
+    {
+        _codexHomeService = codexHomeService ?? new CodexHomeService();
+        _configFileService = configFileService ?? new ConfigFileService();
+    }
+
+    public CodexStorageLayout Resolve(
+        string? explicitCodexHome,
+        string? explicitSqliteHome,
+        string configText,
+        IReadOnlyDictionary<string, string?>? environment = null,
+        string explicitSource = "gui")
+    {
+        string codexHome = _codexHomeService.NormalizeCodexHome(explicitCodexHome);
+        string? configuredSqliteHome = _configFileService.ReadSqliteHomeFromConfigText(configText);
+        environment ??= Environment.GetEnvironmentVariables()
+            .Cast<System.Collections.DictionaryEntry>()
+            .ToDictionary(
+                static entry => Convert.ToString(entry.Key) ?? string.Empty,
+                static entry => Convert.ToString(entry.Value),
+                StringComparer.OrdinalIgnoreCase);
+        environment.TryGetValue("CODEX_SQLITE_HOME", out string? environmentSqliteHome);
+
+        (string? Value, string Source) selected = !string.IsNullOrWhiteSpace(explicitSqliteHome)
+            ? (explicitSqliteHome, explicitSource)
+            : !string.IsNullOrWhiteSpace(configuredSqliteHome)
+                ? (configuredSqliteHome, "config")
+                : !string.IsNullOrWhiteSpace(environmentSqliteHome)
+                    ? (environmentSqliteHome, "env")
+                    : (null, "default");
+
+        string sqliteHome = selected.Value is null
+            ? Path.Combine(codexHome, AppConstants.SqliteDirBasename)
+            : Path.GetFullPath(selected.Value.Trim());
+        SqliteAccessInfo sqliteAccess = ResolveSqliteAccess(sqliteHome, selected.Value?.Trim());
+        bool allowLegacyRootFallback = string.Equals(selected.Source, "default", StringComparison.Ordinal);
+        List<StateDbLocation> candidates =
+        [
+            new StateDbLocation(
+                Path.Combine(sqliteHome, AppConstants.DbFileBasename),
+                allowLegacyRootFallback
+                    ? Path.Combine(AppConstants.SqliteDirBasename, AppConstants.DbFileBasename)
+                    : AppConstants.DbFileBasename,
+                allowLegacyRootFallback ? "sqlite-dir" : "sqlite-home")
+        ];
+        if (allowLegacyRootFallback)
+        {
+            candidates.Add(new StateDbLocation(
+                Path.Combine(codexHome, AppConstants.DbFileBasename),
+                AppConstants.DbFileBasename,
+                "legacy-root"));
+        }
+
+        return new CodexStorageLayout
+        {
+            CodexHome = codexHome,
+            SqliteHome = sqliteHome,
+            SqliteHomeSource = selected.Source,
+            SqliteAccess = sqliteAccess,
+            AllowLegacyRootFallback = allowLegacyRootFallback,
+            StateDbCandidates = candidates
+        };
+    }
+
+    public CodexStorageLayout CreateDefault(string codexHome)
+    {
+        return Resolve(
+            codexHome,
+            explicitSqliteHome: null,
+            configText: string.Empty,
+            environment: new Dictionary<string, string?>());
+    }
+
+    private static SqliteAccessInfo ResolveSqliteAccess(string sqliteHome, string? rawSqliteHome)
+    {
+        if (OperatingSystem.IsWindows()
+            && (IsWslUncPath(rawSqliteHome) || IsWslUncPath(sqliteHome)))
+        {
+            string unsafePath = rawSqliteHome ?? sqliteHome;
+            return new SqliteAccessInfo(
+                false,
+                "windows-wsl-unc",
+                $"Windows cannot safely access SQLite through the WSL UNC path {unsafePath}. "
+                + "Run codex-provider inside WSL with a Linux SQLite Home path instead.");
+        }
+
+        return SqliteAccessInfo.Direct;
+    }
+
+    private static bool IsWslUncPath(string? value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return false;
+        }
+
+        string normalized = value.Replace('/', '\\');
+        return normalized.StartsWith(@"\\wsl.localhost\", StringComparison.OrdinalIgnoreCase)
+            || normalized.StartsWith(@"\\wsl$\", StringComparison.OrdinalIgnoreCase)
+            || normalized.StartsWith(@"\\?\UNC\wsl.localhost\", StringComparison.OrdinalIgnoreCase)
+            || normalized.StartsWith(@"\\?\UNC\wsl$\", StringComparison.OrdinalIgnoreCase);
+    }
+}
diff --git a/desktop/CodexProviderSync.Core/CodexSyncService.cs b/desktop/CodexProviderSync.Core/CodexSyncService.cs
index b6e9d47..85c5d18 100644
--- a/desktop/CodexProviderSync.Core/CodexSyncService.cs
+++ b/desktop/CodexProviderSync.Core/CodexSyncService.cs
@@ -10,6 +10,7 @@ public sealed class CodexSyncService
     private readonly BackupService _backupService;
     private readonly LockService _lockService;
     private readonly ProviderDiscoveryService _providerDiscoveryService;
+    private readonly CodexStorageLayoutService _storageLayoutService;
 
     public CodexSyncService()
         : this(
@@ -39,33 +40,44 @@ public CodexSyncService(
         _globalStateService = globalStateService;
         _lockService = lockService;
         _providerDiscoveryService = providerDiscoveryService;
+        _storageLayoutService = new CodexStorageLayoutService(codexHomeService, configFileService);
         _backupService = new BackupService(sessionRolloutService, sqliteStateService);
     }
 
-    public async Task<StatusSnapshot> GetStatusAsync(string? explicitCodexHome = null)
+    public async Task<StatusSnapshot> GetStatusAsync(
+        string? explicitCodexHome = null,
+        string? explicitSqliteHome = null)
     {
         string codexHome = _codexHomeService.NormalizeCodexHome(explicitCodexHome);
         await _codexHomeService.EnsureCodexHomeAsync(codexHome);
         string configText = await _configFileService.ReadConfigTextAsync(_codexHomeService.ConfigPath(codexHome));
+        CodexStorageLayout storage = await PrepareStorageAsync(codexHome, explicitSqliteHome, configText);
         CurrentProviderInfo currentProvider = _configFileService.ReadCurrentProviderFromConfigText(configText);
         IReadOnlyList<string> configuredProviders = _configFileService.ListConfiguredProviderIds(configText);
         SessionChangeCollection rolloutInfo = await _sessionRolloutService.CollectSessionChangesAsync(codexHome, "__status_only__", skipLockedReads: true);
-        StateDbLocation? stateDbLocation = _sqliteStateService.DetectStateDb(codexHome);
-        ProviderCounts? sqliteCounts = await _sqliteStateService.ReadSqliteProviderCountsAsync(codexHome);
+        StateDbLocation? stateDbLocation = storage.StateDbLocation;
+        ProviderCounts? sqliteCounts = storage.SqliteAccess.Supported
+            ? await _sqliteStateService.ReadSqliteProviderCountsAsync(storage)
+            : null;
         SqliteRepairStats? sqliteRepairStats = sqliteCounts is not null && !sqliteCounts.Unreadable
             ? await _sqliteStateService.ReadSqliteRepairStatsAsync(
-                codexHome,
+                storage,
                 rolloutInfo.UserEventThreadIds,
                 rolloutInfo.ThreadCwdsById)
             : null;
-        IReadOnlyList<ProjectThreadVisibility> projectThreadVisibility = sqliteCounts?.Unreadable == true
+        IReadOnlyList<ProjectThreadVisibility> projectThreadVisibility = !storage.SqliteAccess.Supported
+            || sqliteCounts?.Unreadable == true
             ? []
-            : await _globalStateService.ReadProjectThreadVisibilityAsync(codexHome);
+            : await _globalStateService.ReadProjectThreadVisibilityAsync(storage);
         BackupSummary backupSummary = await _backupService.GetBackupSummaryAsync(codexHome);
 
         return new StatusSnapshot
         {
             CodexHome = codexHome,
+            SqliteHome = storage.SqliteHome,
+            SqliteHomeSource = storage.SqliteHomeSource,
+            SqliteAccess = storage.SqliteAccess,
+            CheckedStateDbPaths = storage.StateDbCandidates.Select(static candidate => candidate.Path).ToList(),
             CurrentProvider = currentProvider,
             ConfiguredProviders = configuredProviders,
             RolloutCounts = rolloutInfo.ProviderCounts,
@@ -98,7 +110,8 @@ public async Task<SyncResult> RunSyncAsync(
         string? configBackupText = null,
         int keepCount = AppConstants.DefaultBackupRetentionCount,
         int? sqliteBusyTimeoutMs = null,
-        string? model = null)
+        string? model = null,
+        string? explicitSqliteHome = null)
     {
         if (keepCount < 1)
         {
@@ -109,6 +122,9 @@ public async Task<SyncResult> RunSyncAsync(
         await _codexHomeService.EnsureCodexHomeAsync(codexHome);
         string configPath = _codexHomeService.ConfigPath(codexHome);
         string configText = await _configFileService.ReadConfigTextAsync(configPath);
+        CodexStorageLayout storage = await PrepareStorageAsync(codexHome, explicitSqliteHome, configText);
+        storage.EnsureSqliteAccessSupported("sync");
+        EnsureWritableStorage(storage);
         CurrentProviderInfo current = _configFileService.ReadCurrentProviderFromConfigText(configText);
         string targetProvider = provider ?? current.Provider ?? AppConstants.DefaultProvider;
 
@@ -130,7 +146,7 @@ public async Task<SyncResult> RunSyncAsync(
             targetProvider,
             skipLockedReads: true,
             targetModel: targetModel);
-        IReadOnlyList<ThreadCwdStat> workspaceCwdStats = await _globalStateService.ReadThreadCwdStatsAsync(codexHome);
+        IReadOnlyList<ThreadCwdStat> workspaceCwdStats = await _globalStateService.ReadThreadCwdStatsAsync(storage);
         string? encryptedContentWarning = BuildEncryptedContentWarning(sessionInfo.EncryptedContentCounts, targetProvider);
         (IReadOnlyList<SessionChange> writableChanges, IReadOnlyList<SessionChange> lockedChanges) =
             await _sessionRolloutService.SplitLockedSessionChangesAsync(sessionInfo.Changes);
@@ -141,8 +157,8 @@ public async Task<SyncResult> RunSyncAsync(
             .Order(StringComparer.Ordinal)
             .ToList();
 
-        await _sqliteStateService.AssertSqliteWritableAsync(codexHome, sqliteBusyTimeoutMs);
-        string backupDir = await _backupService.CreateBackupAsync(codexHome, targetProvider, writableChanges, configPath, configBackupText);
+        await _sqliteStateService.AssertSqliteWritableAsync(storage, sqliteBusyTimeoutMs);
+        string backupDir = await _backupService.CreateBackupAsync(storage, targetProvider, writableChanges, configPath, configBackupText);
 
         bool sessionRestoreNeeded = false;
         List<SessionChange> appliedSessionChanges = [];
@@ -158,7 +174,7 @@ public async Task<SyncResult> RunSyncAsync(
         {
             SessionApplyResult? applyResult = null;
             (int updatedRows, int providerRowsUpdated, int modelRowsUpdated, int userEventRowsUpdated, int cwdRowsUpdated, bool databasePresent) = await _sqliteStateService.UpdateSqliteProviderAsync(
-                codexHome,
+                storage,
                 targetProvider,
                 targetModel,
                 async _ =>
@@ -171,7 +187,7 @@ public async Task<SyncResult> RunSyncAsync(
                         sessionRestoreNeeded = appliedSessionChanges.Count > 0;
                         await _backupService.UpdateSessionBackupManifestAsync(backupDir, appliedSessionChanges);
                     }
-                    workspaceRootResult = await _globalStateService.SyncWorkspaceRootsAsync(codexHome, workspaceCwdStats);
+                    workspaceRootResult = await _globalStateService.SyncWorkspaceRootsAsync(storage, workspaceCwdStats);
                     globalStateRestoreNeeded = workspaceRootResult.Updated;
                 },
                 sqliteBusyTimeoutMs,
@@ -195,6 +211,8 @@ public async Task<SyncResult> RunSyncAsync(
             return new SyncResult
             {
                 CodexHome = codexHome,
+                SqliteHome = storage.SqliteHome,
+                SqliteHomeSource = storage.SqliteHomeSource,
                 TargetProvider = targetProvider,
                 PreviousProvider = current.Provider ?? AppConstants.DefaultProvider,
                 BackupDir = backupDir,
@@ -258,7 +276,8 @@ public async Task<SyncResult> RunSwitchAsync(
         string provider,
         int keepCount = AppConstants.DefaultBackupRetentionCount,
         string? model = null,
-        bool keepRootModel = false)
+        bool keepRootModel = false,
+        string? explicitSqliteHome = null)
     {
         if (string.IsNullOrWhiteSpace(provider))
         {
@@ -269,6 +288,9 @@ public async Task<SyncResult> RunSwitchAsync(
         await _codexHomeService.EnsureCodexHomeAsync(codexHome);
         string configPath = _codexHomeService.ConfigPath(codexHome);
         string originalConfigText = await _configFileService.ReadConfigTextAsync(configPath);
+        CodexStorageLayout storage = await PrepareStorageAsync(codexHome, explicitSqliteHome, originalConfigText);
+        storage.EnsureSqliteAccessSupported("switch");
+        EnsureWritableStorage(storage);
         if (!_configFileService.ConfigDeclaresProvider(originalConfigText, provider))
         {
             string configuredProviders = string.Join(", ", _configFileService.ListConfiguredProviderIds(originalConfigText));
@@ -292,10 +314,18 @@ public async Task<SyncResult> RunSwitchAsync(
             string? modelForThreads = modelSync.Applied
                 ? modelSync.Model
                 : _configFileService.ReadRootModelFromConfigText(nextConfigText);
-            SyncResult result = await RunSyncAsync(codexHome, provider, originalConfigText, keepCount, model: modelForThreads);
+            SyncResult result = await RunSyncAsync(
+                codexHome,
+                provider,
+                originalConfigText,
+                keepCount,
+                model: modelForThreads,
+                explicitSqliteHome: explicitSqliteHome);
             return new SyncResult
             {
                 CodexHome = result.CodexHome,
+                SqliteHome = result.SqliteHome,
+                SqliteHomeSource = result.SqliteHomeSource,
                 TargetProvider = result.TargetProvider,
                 PreviousProvider = result.PreviousProvider,
                 BackupDir = result.BackupDir,
@@ -364,12 +394,19 @@ private ModelSyncOutcome ResolveModelSyncOutcome(
         return ModelSyncOutcome.CreateSkipped("none", warning: null);
     }
 
-    public async Task<RestoreResult> RunRestoreAsync(string? explicitCodexHome, string backupDir)
+    public async Task<RestoreResult> RunRestoreAsync(
+        string? explicitCodexHome,
+        string backupDir,
+        string? explicitSqliteHome = null)
     {
-        return await RunRestoreAsync(explicitCodexHome, backupDir, new RestoreBackupOptions());
+        return await RunRestoreAsync(explicitCodexHome, backupDir, new RestoreBackupOptions(), explicitSqliteHome);
     }
 
-    public async Task<RestoreResult> RunRestoreAsync(string? explicitCodexHome, string backupDir, RestoreBackupOptions options)
+    public async Task<RestoreResult> RunRestoreAsync(
+        string? explicitCodexHome,
+        string backupDir,
+        RestoreBackupOptions options,
+        string? explicitSqliteHome = null)
     {
         if (string.IsNullOrWhiteSpace(backupDir))
         {
@@ -378,9 +415,12 @@ public async Task<RestoreResult> RunRestoreAsync(string? explicitCodexHome, stri
 
         string codexHome = _codexHomeService.NormalizeCodexHome(explicitCodexHome);
         await _codexHomeService.EnsureCodexHomeAsync(codexHome);
+        string configText = await _configFileService.ReadConfigTextAsync(_codexHomeService.ConfigPath(codexHome));
+        CodexStorageLayout storage = await PrepareStorageAsync(codexHome, explicitSqliteHome, configText);
+        storage.EnsureSqliteAccessSupported("restore");
 
         await using LockHandle _ = await _lockService.AcquireLockAsync(codexHome, "restore");
-        return await _backupService.RestoreBackupAsync(Path.GetFullPath(backupDir), codexHome, options);
+        return await _backupService.RestoreBackupAsync(Path.GetFullPath(backupDir), storage, options);
     }
 
     public async Task<BackupPruneResult> RunPruneBackupsAsync(
@@ -394,6 +434,11 @@ public async Task<BackupPruneResult> RunPruneBackupsAsync(
         return await _backupService.PruneBackupsAsync(codexHome, keepCount);
     }
 
+    public Task<BackupStorageInfo> GetBackupStorageInfoAsync(string backupDir)
+    {
+        return _backupService.GetBackupStorageInfoAsync(backupDir);
+    }
+
     private static string? BuildEncryptedContentWarning(ProviderCounts encryptedContentCounts, string targetProvider)
     {
         int total = encryptedContentCounts.Sessions.Values.Sum() + encryptedContentCounts.ArchivedSessions.Values.Sum();
@@ -412,4 +457,30 @@ public async Task<BackupPruneResult> RunPruneBackupsAsync(
 
         return $"Encrypted content warning: {total} rollout file(s) contain encrypted_content from provider(s) {string.Join(", ", riskyProviders)}. Visibility metadata can be synchronized to {targetProvider}, but continuing or compacting those histories may fail with invalid_encrypted_content. Return to the original provider/account or start a new session if you need reliable continuation.";
     }
+
+    private async Task<CodexStorageLayout> PrepareStorageAsync(
+        string codexHome,
+        string? explicitSqliteHome,
+        string configText)
+    {
+        CodexStorageLayout storage = _storageLayoutService.Resolve(
+            codexHome,
+            explicitSqliteHome,
+            configText,
+            explicitSource: "gui");
+        StateDbLocation? stateDb = storage.SqliteAccess.Supported
+            ? _sqliteStateService.DetectStateDb(storage)
+            : null;
+        return storage with { StateDbLocation = stateDb };
+    }
+
+    private static void EnsureWritableStorage(CodexStorageLayout storage)
+    {
+        if (storage.StateDbLocation is null && storage.HasConfiguredSqliteHome)
+        {
+            throw new InvalidOperationException(
+                $"state_5.sqlite not found in configured SQLite home {storage.SqliteHome} "
+                + $"(source: {storage.SqliteHomeSource}).");
+        }
+    }
 }
diff --git a/desktop/CodexProviderSync.Core/ConfigFileService.cs b/desktop/CodexProviderSync.Core/ConfigFileService.cs
index 524b73a..9889599 100644
--- a/desktop/CodexProviderSync.Core/ConfigFileService.cs
+++ b/desktop/CodexProviderSync.Core/ConfigFileService.cs
@@ -19,6 +19,45 @@ public Task<string> ReadConfigTextAsync(string configPath)
         return File.ReadAllTextAsync(configPath);
     }
 
+    public string? ReadSqliteHomeFromConfigText(string configText)
+    {
+        return ReadRootStringFromConfigText(configText, "sqlite_home");
+    }
+
+    public string? ReadRootStringFromConfigText(string configText, string key)
+    {
+        string escapedKey = Regex.Escape(key);
+        Regex assignment = new(
+            $"^{escapedKey}\\s*=\\s*(?:\"((?:\\\\.|[^\"\\\\])*)\"|'([^']*)')\\s*(?:#.*)?$",
+            RegexOptions.CultureInvariant);
+
+        foreach (string rawLine in SplitLines(configText))
+        {
+            string trimmed = rawLine.Trim();
+            if (string.IsNullOrWhiteSpace(trimmed) || trimmed.StartsWith('#'))
+            {
+                continue;
+            }
+            if (trimmed.StartsWith('['))
+            {
+                break;
+            }
+
+            Match match = assignment.Match(trimmed);
+            if (!match.Success)
+            {
+                continue;
+            }
+            if (match.Groups[1].Success)
+            {
+                return DecodeTomlBasicString(match.Groups[1].Value);
+            }
+            return match.Groups[2].Value;
+        }
+
+        return null;
+    }
+
     public async Task WriteConfigTextAsync(string configPath, string configText)
     {
         await File.WriteAllTextAsync(configPath, configText);
@@ -243,4 +282,22 @@ private static string EscapeTomlString(string value)
         return value.Replace("\\", "\\\\", StringComparison.Ordinal)
             .Replace("\"", "\\\"", StringComparison.Ordinal);
     }
+
+    private static string DecodeTomlBasicString(string value)
+    {
+        return Regex.Replace(
+            value,
+            "\\\\(?:[btnfr\"\\\\]|u[0-9A-Fa-f]{4}|U[0-9A-Fa-f]{8})",
+            static match => match.Value switch
+            {
+                @"\b" => "\b",
+                @"\t" => "\t",
+                @"\n" => "\n",
+                @"\f" => "\f",
+                @"\r" => "\r",
+                "\\\"" => "\"",
+                @"\\" => "\\",
+                _ => char.ConvertFromUtf32(Convert.ToInt32(match.Value[2..], 16))
+            });
+    }
 }
diff --git a/desktop/CodexProviderSync.Core/GlobalStateService.cs b/desktop/CodexProviderSync.Core/GlobalStateService.cs
index d48e4b9..416bae6 100644
--- a/desktop/CodexProviderSync.Core/GlobalStateService.cs
+++ b/desktop/CodexProviderSync.Core/GlobalStateService.cs
@@ -20,7 +20,12 @@ public string BackupPath(string codexHome)
 
     public async Task<IReadOnlyList<ThreadCwdStat>> ReadThreadCwdStatsAsync(string codexHome)
     {
-        string? dbPath = _sqliteStateService.ExistingStateDbPath(codexHome);
+        return await ReadThreadCwdStatsAsync(new CodexStorageLayoutService().CreateDefault(codexHome));
+    }
+
+    public async Task<IReadOnlyList<ThreadCwdStat>> ReadThreadCwdStatsAsync(CodexStorageLayout storage)
+    {
+        string? dbPath = _sqliteStateService.ExistingStateDbPath(storage);
         if (dbPath is null)
         {
             return [];
@@ -90,6 +95,16 @@ public async Task<WorkspaceRootSyncResult> SyncWorkspaceRootsAsync(
         string codexHome,
         IReadOnlyList<ThreadCwdStat>? cwdStats = null)
     {
+        return await SyncWorkspaceRootsAsync(
+            new CodexStorageLayoutService().CreateDefault(codexHome),
+            cwdStats);
+    }
+
+    public async Task<WorkspaceRootSyncResult> SyncWorkspaceRootsAsync(
+        CodexStorageLayout storage,
+        IReadOnlyList<ThreadCwdStat>? cwdStats = null)
+    {
+        string codexHome = storage.CodexHome;
         string statePath = StatePath(codexHome);
         if (!File.Exists(statePath))
         {
@@ -104,7 +119,7 @@ public async Task<WorkspaceRootSyncResult> SyncWorkspaceRootsAsync(
 
         JsonObject state = JsonNode.Parse(await File.ReadAllTextAsync(statePath))?.AsObject()
             ?? throw new InvalidOperationException($"Global state file is invalid: {statePath}");
-        IReadOnlyList<ThreadCwdStat> effectiveCwdStats = cwdStats ?? await ReadThreadCwdStatsAsync(codexHome);
+        IReadOnlyList<ThreadCwdStat> effectiveCwdStats = cwdStats ?? await ReadThreadCwdStatsAsync(storage);
 
         List<string> existingSavedRoots = ToPathList(state["electron-saved-workspace-roots"]);
         List<string> existingProjectOrder = ToPathList(state["project-order"]);
@@ -179,6 +194,16 @@ public async Task<IReadOnlyList<ProjectThreadVisibility>> ReadProjectThreadVisib
         string codexHome,
         int pageSize = 50)
     {
+        return await ReadProjectThreadVisibilityAsync(
+            new CodexStorageLayoutService().CreateDefault(codexHome),
+            pageSize);
+    }
+
+    public async Task<IReadOnlyList<ProjectThreadVisibility>> ReadProjectThreadVisibilityAsync(
+        CodexStorageLayout storage,
+        int pageSize = 50)
+    {
+        string codexHome = storage.CodexHome;
         string statePath = StatePath(codexHome);
         if (!File.Exists(statePath))
         {
@@ -193,7 +218,7 @@ public async Task<IReadOnlyList<ProjectThreadVisibility>> ReadProjectThreadVisib
             return [];
         }
 
-        string? dbPath = _sqliteStateService.ExistingStateDbPath(codexHome);
+        string? dbPath = _sqliteStateService.ExistingStateDbPath(storage);
         if (dbPath is null)
         {
             return roots
diff --git a/desktop/CodexProviderSync.Core/Models.cs b/desktop/CodexProviderSync.Core/Models.cs
index 4c9715c..b37dce8 100644
--- a/desktop/CodexProviderSync.Core/Models.cs
+++ b/desktop/CodexProviderSync.Core/Models.cs
@@ -16,6 +16,10 @@ public sealed class ProviderCounts
 public sealed class StatusSnapshot
 {
     public required string CodexHome { get; init; }
+    public string SqliteHome { get; init; } = string.Empty;
+    public string SqliteHomeSource { get; init; } = "default";
+    public SqliteAccessInfo SqliteAccess { get; init; } = SqliteAccessInfo.Direct;
+    public IReadOnlyList<string> CheckedStateDbPaths { get; init; } = [];
     public required CurrentProviderInfo CurrentProvider { get; init; }
     public required IReadOnlyList<string> ConfiguredProviders { get; init; }
     public required ProviderCounts RolloutCounts { get; init; }
@@ -33,6 +37,32 @@ public sealed class StatusSnapshot
 
 public sealed record StateDbLocation(string Path, string RelativePath, string Source);
 
+public sealed record SqliteAccessInfo(bool Supported, string? Reason, string? Message)
+{
+    public static SqliteAccessInfo Direct { get; } = new(true, null, null);
+}
+
+public sealed record CodexStorageLayout
+{
+    public required string CodexHome { get; init; }
+    public required string SqliteHome { get; init; }
+    public string SqliteHomeSource { get; init; } = "default";
+    public required bool AllowLegacyRootFallback { get; init; }
+    public required IReadOnlyList<StateDbLocation> StateDbCandidates { get; init; }
+    public StateDbLocation? StateDbLocation { get; init; }
+    public SqliteAccessInfo SqliteAccess { get; init; } = SqliteAccessInfo.Direct;
+
+    public bool HasConfiguredSqliteHome => !string.Equals(SqliteHomeSource, "default", StringComparison.Ordinal);
+
+    public void EnsureSqliteAccessSupported(string operation)
+    {
+        if (!SqliteAccess.Supported)
+        {
+            throw new InvalidOperationException($"Cannot {operation}: {SqliteAccess.Message}");
+        }
+    }
+}
+
 public sealed class SqliteRepairStats
 {
     public required int UserEventRowsNeedingRepair { get; init; }
@@ -102,6 +132,8 @@ public sealed class SessionChangeCollection
 public sealed class SyncResult
 {
     public required string CodexHome { get; init; }
+    public string SqliteHome { get; init; } = string.Empty;
+    public string SqliteHomeSource { get; init; } = "default";
     public required string TargetProvider { get; init; }
     public required string PreviousProvider { get; init; }
     public required string BackupDir { get; init; }
@@ -169,6 +201,12 @@ public sealed class RestoreResult
     public int ChangedSessionFiles { get; init; }
 }
 
+public sealed class BackupStorageInfo
+{
+    public required int Version { get; init; }
+    public string? SqliteHome { get; init; }
+}
+
 public enum ProviderSource
 {
     Config,
@@ -199,6 +237,8 @@ public sealed class AppSettings
 {
     public List<string> RecentCodexHomes { get; init; } = [];
     public string? LastCodexHome { get; init; }
+    public Dictionary<string, string> SqliteHomeOverrides { get; init; } = new(
+        OperatingSystem.IsWindows() ? StringComparer.OrdinalIgnoreCase : StringComparer.Ordinal);
     public List<string> SavedProviders { get; init; } = [];
     public List<string> ManualProviders { get; init; } = [];
     public string? LastSelectedProvider { get; init; }
@@ -214,6 +254,7 @@ public sealed class RestoreBackupOptions
     public bool RestoreConfig { get; init; } = true;
     public bool RestoreDatabase { get; init; } = true;
     public bool RestoreSessions { get; init; } = true;
+    public bool AllowSqliteHomeRelocation { get; init; }
 }
 
 internal sealed class BackupMetadataFile
@@ -221,9 +262,11 @@ internal sealed class BackupMetadataFile
     public int Version { get; init; }
     public required string Namespace { get; init; }
     public required string CodexHome { get; init; }
+    public string? SqliteHome { get; init; }
     public required string TargetProvider { get; init; }
     public required DateTimeOffset CreatedAt { get; init; }
     public required List<string> DbFiles { get; init; }
+    public List<string> SqliteDbFiles { get; init; } = [];
     public int ChangedSessionFiles { get; init; }
 }
 
diff --git a/desktop/CodexProviderSync.Core/SettingsService.cs b/desktop/CodexProviderSync.Core/SettingsService.cs
index ce71082..95f33a7 100644
--- a/desktop/CodexProviderSync.Core/SettingsService.cs
+++ b/desktop/CodexProviderSync.Core/SettingsService.cs
@@ -61,6 +61,7 @@ public AppSettings RecordCodexHome(AppSettings settings, string codexHome)
         {
             RecentCodexHomes = recents,
             LastCodexHome = Path.GetFullPath(codexHome),
+            SqliteHomeOverrides = NormalizeSqliteHomeOverrides(settings.SqliteHomeOverrides),
             SavedProviders = Deduplicate(settings.SavedProviders).ToList(),
             ManualProviders = Deduplicate(settings.ManualProviders).ToList(),
             LastSelectedProvider = settings.LastSelectedProvider,
@@ -78,6 +79,7 @@ public AppSettings MergeDetectedProviders(AppSettings settings, IEnumerable<stri
         {
             RecentCodexHomes = Deduplicate(settings.RecentCodexHomes).ToList(),
             LastCodexHome = settings.LastCodexHome,
+            SqliteHomeOverrides = NormalizeSqliteHomeOverrides(settings.SqliteHomeOverrides),
             SavedProviders = Deduplicate([.. settings.SavedProviders, .. providerIds]).ToList(),
             ManualProviders = Deduplicate(settings.ManualProviders).ToList(),
             LastSelectedProvider = settings.LastSelectedProvider,
@@ -95,6 +97,7 @@ public AppSettings AddManualProvider(AppSettings settings, string providerId)
         {
             RecentCodexHomes = Deduplicate(settings.RecentCodexHomes).ToList(),
             LastCodexHome = settings.LastCodexHome,
+            SqliteHomeOverrides = NormalizeSqliteHomeOverrides(settings.SqliteHomeOverrides),
             SavedProviders = Deduplicate([.. settings.SavedProviders, providerId]).ToList(),
             ManualProviders = Deduplicate([.. settings.ManualProviders, providerId]).ToList(),
             LastSelectedProvider = providerId,
@@ -112,6 +115,7 @@ public AppSettings RemoveManualProvider(AppSettings settings, string providerId)
         {
             RecentCodexHomes = Deduplicate(settings.RecentCodexHomes).ToList(),
             LastCodexHome = settings.LastCodexHome,
+            SqliteHomeOverrides = NormalizeSqliteHomeOverrides(settings.SqliteHomeOverrides),
             SavedProviders = settings.SavedProviders.Where(provider => !string.Equals(provider, providerId, StringComparison.Ordinal)).Order(StringComparer.Ordinal).ToList(),
             ManualProviders = settings.ManualProviders.Where(provider => !string.Equals(provider, providerId, StringComparison.Ordinal)).Order(StringComparer.Ordinal).ToList(),
             LastSelectedProvider = string.Equals(settings.LastSelectedProvider, providerId, StringComparison.Ordinal) ? null : settings.LastSelectedProvider,
@@ -129,6 +133,7 @@ public AppSettings UpdateUiLanguage(AppSettings settings, string uiLanguage)
         {
             RecentCodexHomes = Deduplicate(settings.RecentCodexHomes).ToList(),
             LastCodexHome = settings.LastCodexHome,
+            SqliteHomeOverrides = NormalizeSqliteHomeOverrides(settings.SqliteHomeOverrides),
             SavedProviders = Deduplicate(settings.SavedProviders).ToList(),
             ManualProviders = Deduplicate(settings.ManualProviders).ToList(),
             LastSelectedProvider = settings.LastSelectedProvider,
@@ -146,6 +151,7 @@ public AppSettings RecordAutomaticUpdateCheck(AppSettings settings, DateOnly dat
         {
             RecentCodexHomes = Deduplicate(settings.RecentCodexHomes).ToList(),
             LastCodexHome = settings.LastCodexHome,
+            SqliteHomeOverrides = NormalizeSqliteHomeOverrides(settings.SqliteHomeOverrides),
             SavedProviders = Deduplicate(settings.SavedProviders).ToList(),
             ManualProviders = Deduplicate(settings.ManualProviders).ToList(),
             LastSelectedProvider = settings.LastSelectedProvider,
@@ -168,6 +174,7 @@ public AppSettings UpdateState(
         {
             RecentCodexHomes = Deduplicate(settings.RecentCodexHomes).ToList(),
             LastCodexHome = settings.LastCodexHome,
+            SqliteHomeOverrides = NormalizeSqliteHomeOverrides(settings.SqliteHomeOverrides),
             SavedProviders = Deduplicate(settings.SavedProviders).ToList(),
             ManualProviders = Deduplicate(settings.ManualProviders).ToList(),
             LastSelectedProvider = string.IsNullOrWhiteSpace(selectedProvider) ? settings.LastSelectedProvider : selectedProvider.Trim(),
@@ -179,12 +186,54 @@ public AppSettings UpdateState(
         };
     }
 
+    public string? GetSqliteHomeOverride(AppSettings settings, string codexHome)
+    {
+        Dictionary<string, string> overrides = NormalizeSqliteHomeOverrides(settings.SqliteHomeOverrides);
+        return overrides.TryGetValue(Path.GetFullPath(codexHome), out string? sqliteHome)
+            ? sqliteHome
+            : null;
+    }
+
+    public AppSettings RecordSqliteHomeOverride(
+        AppSettings settings,
+        string codexHome,
+        string? sqliteHome)
+    {
+        Dictionary<string, string> overrides = NormalizeSqliteHomeOverrides(settings.SqliteHomeOverrides);
+        string normalizedCodexHome = Path.GetFullPath(codexHome);
+        if (string.IsNullOrWhiteSpace(sqliteHome))
+        {
+            overrides.Remove(normalizedCodexHome);
+        }
+        else
+        {
+            overrides[normalizedCodexHome] = Path.GetFullPath(sqliteHome.Trim());
+        }
+
+        AppSettings normalized = Normalize(settings);
+        return new AppSettings
+        {
+            RecentCodexHomes = normalized.RecentCodexHomes,
+            LastCodexHome = normalized.LastCodexHome,
+            SqliteHomeOverrides = overrides,
+            SavedProviders = normalized.SavedProviders,
+            ManualProviders = normalized.ManualProviders,
+            LastSelectedProvider = normalized.LastSelectedProvider,
+            LastBackupDirectory = normalized.LastBackupDirectory,
+            BackupRetentionCount = normalized.BackupRetentionCount,
+            UiLanguage = normalized.UiLanguage,
+            LastAutomaticUpdateCheckDate = normalized.LastAutomaticUpdateCheckDate,
+            WindowBounds = normalized.WindowBounds
+        };
+    }
+
     private static AppSettings Normalize(AppSettings settings)
     {
         return new AppSettings
         {
             RecentCodexHomes = Deduplicate(settings.RecentCodexHomes.Select(Path.GetFullPath)).Take(10).ToList(),
             LastCodexHome = string.IsNullOrWhiteSpace(settings.LastCodexHome) ? null : Path.GetFullPath(settings.LastCodexHome),
+            SqliteHomeOverrides = NormalizeSqliteHomeOverrides(settings.SqliteHomeOverrides),
             SavedProviders = Deduplicate(settings.SavedProviders).ToList(),
             ManualProviders = Deduplicate(settings.ManualProviders).ToList(),
             LastSelectedProvider = string.IsNullOrWhiteSpace(settings.LastSelectedProvider) ? null : settings.LastSelectedProvider.Trim(),
@@ -205,6 +254,21 @@ private static IEnumerable<string> Deduplicate(IEnumerable<string> values)
             .Order(StringComparer.Ordinal);
     }
 
+    private static Dictionary<string, string> NormalizeSqliteHomeOverrides(
+        IReadOnlyDictionary<string, string>? overrides)
+    {
+        Dictionary<string, string> normalized = new(
+            OperatingSystem.IsWindows() ? StringComparer.OrdinalIgnoreCase : StringComparer.Ordinal);
+        foreach ((string codexHome, string sqliteHome) in overrides ?? new Dictionary<string, string>())
+        {
+            if (!string.IsNullOrWhiteSpace(codexHome) && !string.IsNullOrWhiteSpace(sqliteHome))
+            {
+                normalized[Path.GetFullPath(codexHome)] = Path.GetFullPath(sqliteHome);
+            }
+        }
+        return normalized;
+    }
+
     private static JsonSerializerOptions JsonSerializerOptions()
     {
         return new JsonSerializerOptions
diff --git a/desktop/CodexProviderSync.Core/SqliteStateService.cs b/desktop/CodexProviderSync.Core/SqliteStateService.cs
index 210e303..a653c27 100644
--- a/desktop/CodexProviderSync.Core/SqliteStateService.cs
+++ b/desktop/CodexProviderSync.Core/SqliteStateService.cs
@@ -31,23 +31,18 @@ public string LegacyStateDbPath(string codexHome)
 
     public IReadOnlyList<StateDbLocation> StateDbCandidates(string codexHome)
     {
-        return
-        [
-            new StateDbLocation(
-                StateDbPath(codexHome),
-                Path.Combine(AppConstants.SqliteDirBasename, AppConstants.DbFileBasename),
-                "sqlite-dir"),
-            new StateDbLocation(
-                LegacyStateDbPath(codexHome),
-                AppConstants.DbFileBasename,
-                "legacy-root")
-        ];
+        return new CodexStorageLayoutService().CreateDefault(codexHome).StateDbCandidates;
     }
 
     public StateDbLocation? DetectStateDb(string codexHome)
+    {
+        return DetectStateDb(new CodexStorageLayoutService().CreateDefault(codexHome));
+    }
+
+    public StateDbLocation? DetectStateDb(CodexStorageLayout storage)
     {
         List<(StateDbLocation Location, int Priority)> existingCandidates = [];
-        IReadOnlyList<StateDbLocation> candidates = StateDbCandidates(codexHome);
+        IReadOnlyList<StateDbLocation> candidates = storage.StateDbCandidates;
         for (int index = 0; index < candidates.Count; index += 1)
         {
             StateDbLocation candidate = candidates[index];
@@ -62,7 +57,7 @@ public IReadOnlyList<StateDbLocation> StateDbCandidates(string codexHome)
             return null;
         }
 
-        long rolloutCount = CountRolloutFiles(codexHome);
+        long rolloutCount = CountRolloutFiles(storage.CodexHome);
         List<StateDbCandidateStats> readableCandidates = [];
         foreach ((StateDbLocation candidate, int priority) in existingCandidates)
         {
@@ -98,9 +93,19 @@ public IReadOnlyList<StateDbLocation> StateDbCandidates(string codexHome)
         return DetectStateDb(codexHome)?.Path;
     }
 
+    public string? ExistingStateDbPath(CodexStorageLayout storage)
+    {
+        return storage.StateDbLocation?.Path ?? DetectStateDb(storage)?.Path;
+    }
+
     public async Task<ProviderCounts?> ReadSqliteProviderCountsAsync(string codexHome)
     {
-        string? dbPath = ExistingStateDbPath(codexHome);
+        return await ReadSqliteProviderCountsAsync(new CodexStorageLayoutService().CreateDefault(codexHome));
+    }
+
+    public async Task<ProviderCounts?> ReadSqliteProviderCountsAsync(CodexStorageLayout storage)
+    {
+        string? dbPath = ExistingStateDbPath(storage);
         if (dbPath is null)
         {
             return null;
@@ -165,7 +170,18 @@ FROM threads
         IReadOnlyCollection<string>? userEventThreadIds = null,
         IReadOnlyDictionary<string, string>? threadCwdsById = null)
     {
-        string? dbPath = ExistingStateDbPath(codexHome);
+        return await ReadSqliteRepairStatsAsync(
+            new CodexStorageLayoutService().CreateDefault(codexHome),
+            userEventThreadIds,
+            threadCwdsById);
+    }
+
+    public async Task<SqliteRepairStats?> ReadSqliteRepairStatsAsync(
+        CodexStorageLayout storage,
+        IReadOnlyCollection<string>? userEventThreadIds = null,
+        IReadOnlyDictionary<string, string>? threadCwdsById = null)
+    {
+        string? dbPath = ExistingStateDbPath(storage);
         if (dbPath is null)
         {
             return null;
@@ -233,7 +249,14 @@ FROM threads
 
     public async Task<bool> AssertSqliteWritableAsync(string codexHome, int? busyTimeoutMs = null)
     {
-        string? dbPath = ExistingStateDbPath(codexHome);
+        return await AssertSqliteWritableAsync(
+            new CodexStorageLayoutService().CreateDefault(codexHome),
+            busyTimeoutMs);
+    }
+
+    public async Task<bool> AssertSqliteWritableAsync(CodexStorageLayout storage, int? busyTimeoutMs = null)
+    {
+        string? dbPath = ExistingStateDbPath(storage);
         if (dbPath is null)
         {
             return false;
@@ -265,7 +288,26 @@ public async Task<bool> AssertSqliteWritableAsync(string codexHome, int? busyTim
         IReadOnlyCollection<string>? userEventThreadIds = null,
         IReadOnlyDictionary<string, string>? threadCwdsById = null)
     {
-        string? dbPath = ExistingStateDbPath(codexHome);
+        return await UpdateSqliteProviderAsync(
+            new CodexStorageLayoutService().CreateDefault(codexHome),
+            targetProvider,
+            targetModel,
+            afterUpdate,
+            busyTimeoutMs,
+            userEventThreadIds,
+            threadCwdsById);
+    }
+
+    public async Task<(int UpdatedRows, int ProviderRowsUpdated, int ModelRowsUpdated, int UserEventRowsUpdated, int CwdRowsUpdated, bool DatabasePresent)> UpdateSqliteProviderAsync(
+        CodexStorageLayout storage,
+        string targetProvider,
+        string? targetModel = null,
+        Func<(int UpdatedRows, int ProviderRowsUpdated, int ModelRowsUpdated, int UserEventRowsUpdated, int CwdRowsUpdated, bool DatabasePresent), Task>? afterUpdate = null,
+        int? busyTimeoutMs = null,
+        IReadOnlyCollection<string>? userEventThreadIds = null,
+        IReadOnlyDictionary<string, string>? threadCwdsById = null)
+    {
+        string? dbPath = ExistingStateDbPath(storage);
         if (dbPath is null)
         {
             if (afterUpdate is not null)
diff --git a/desktop/CodexProviderSync.Core/TextFormatter.cs b/desktop/CodexProviderSync.Core/TextFormatter.cs
index 580ea9b..71c9596 100644
--- a/desktop/CodexProviderSync.Core/TextFormatter.cs
+++ b/desktop/CodexProviderSync.Core/TextFormatter.cs
@@ -104,6 +104,7 @@ private static string FormatStatusEnglish(StatusSnapshot status)
         List<string> lines =
         [
             $"Codex home: {status.CodexHome}",
+            $"SQLite home: {status.SqliteHome} (source: {status.SqliteHomeSource})",
             $"Current provider: {status.CurrentProvider.Provider}{(status.CurrentProvider.Implicit ? " (implicit default)" : string.Empty)}",
             $"Configured providers: {string.Join(", ", status.ConfiguredProviders)}",
             $"Backups: {status.BackupSummary.Count} ({FormatBytes(status.BackupSummary.TotalBytes)})",
@@ -131,7 +132,7 @@ private static string FormatStatusEnglish(StatusSnapshot status)
         {
             rolloutNotes.Add($"  {status.EncryptedContentWarning}");
         }
-        lines.InsertRange(11, rolloutNotes);
+        lines.InsertRange(12, rolloutNotes);
 
         AppendSqliteStatus(lines, status, chinese: false);
         AppendProjectVisibility(lines, status, chinese: false);
@@ -143,6 +144,7 @@ private static string FormatStatusChinese(StatusSnapshot status)
         List<string> lines =
         [
             $"Codex Home: {status.CodexHome}",
+            $"SQLite Home: {status.SqliteHome}（来源: {status.SqliteHomeSource}）",
             $"当前 Provider: {status.CurrentProvider.Provider}{(status.CurrentProvider.Implicit ? "（隐式默认）" : string.Empty)}",
             $"配置中的 Provider: {string.Join(", ", status.ConfiguredProviders)}",
             $"备份: {status.BackupSummary.Count}（{FormatBytes(status.BackupSummary.TotalBytes)}）",
@@ -172,7 +174,7 @@ private static string FormatStatusChinese(StatusSnapshot status)
                 status.EncryptedContentCounts,
                 status.CurrentProvider.Provider)}");
         }
-        lines.InsertRange(11, rolloutNotes);
+        lines.InsertRange(12, rolloutNotes);
 
         AppendSqliteStatus(lines, status, chinese: true);
         AppendProjectVisibility(lines, status, chinese: true);
@@ -181,6 +183,14 @@ private static string FormatStatusChinese(StatusSnapshot status)
 
     private static void AppendSqliteStatus(List<string> lines, StatusSnapshot status, bool chinese)
     {
+        if (!status.SqliteAccess.Supported)
+        {
+            lines.Add(chinese && status.SqliteAccess.Reason == "windows-wsl-unc"
+                ? $"  Windows 进程无法通过 WSL UNC 路径安全访问 SQLite：{status.SqliteHome}。请在 WSL 内运行 codex-provider，并使用 Linux SQLite Home 路径。"
+                : $"  {status.SqliteAccess.Message}");
+            return;
+        }
+
         if (status.StateDbLocation is not null)
         {
             string legacyNote = status.StateDbLocation.Source == "legacy-root"
@@ -192,9 +202,10 @@ private static void AppendSqliteStatus(List<string> lines, StatusSnapshot status
         }
         else
         {
+            string checkedPaths = string.Join(", ", status.CheckedStateDbPaths);
             lines.Add(chinese
-                ? "  未找到数据库（已检查 sqlite/state_5.sqlite 和 state_5.sqlite）"
-                : "  database: not found (checked sqlite/state_5.sqlite, state_5.sqlite)");
+                ? $"  未找到数据库（已检查: {checkedPaths}）"
+                : $"  database: not found (checked: {checkedPaths})");
         }
 
         if (status.SqliteCounts?.Unreadable == true)
@@ -252,6 +263,7 @@ private static string FormatSyncResultEnglish(SyncResult result, string label)
         [
             $"{label} provider: {result.TargetProvider}",
             $"Codex home: {result.CodexHome}",
+            $"SQLite home: {result.SqliteHome} (source: {result.SqliteHomeSource})",
             $"Backup: {result.BackupDir}",
             $"Updated rollout files: {result.ChangedSessionFiles}",
             $"Updated SQLite rows: {result.SqliteRowsUpdated}{(result.SqlitePresent ? string.Empty : " (state_5.sqlite not found)")}"
@@ -267,6 +279,7 @@ private static string FormatSyncResultChinese(SyncResult result, string label)
         [
             $"{label} Provider: {result.TargetProvider}",
             $"Codex Home: {result.CodexHome}",
+            $"SQLite Home: {result.SqliteHome}（来源: {result.SqliteHomeSource}）",
             $"备份目录: {result.BackupDir}",
             $"已更新 rollout 文件: {result.ChangedSessionFiles}",
             $"已更新 SQLite 行: {result.SqliteRowsUpdated}{(result.SqlitePresent ? string.Empty : "（未找到 state_5.sqlite）")}"
diff --git a/desktop/CodexProviderSync.Mac/MacUiText.cs b/desktop/CodexProviderSync.Mac/MacUiText.cs
index b5b860e..e395eb1 100644
--- a/desktop/CodexProviderSync.Mac/MacUiText.cs
+++ b/desktop/CodexProviderSync.Mac/MacUiText.cs
@@ -21,6 +21,8 @@ public static string Get(string language, string key)
         return key switch
         {
             "language" => zh ? "语言" : "Language",
+            "sqliteHome" => "SQLite Home",
+            "sqliteHomePlaceholder" => zh ? "留空时按配置自动解析" : "Resolved automatically when empty",
             "recent" => zh ? "最近使用" : "Recent",
             "browse" => zh ? "浏览" : "Browse",
             "refresh" => zh ? "刷新" : "Refresh",
@@ -70,6 +72,7 @@ public static string Get(string language, string key)
             "backupCleanupFinished" => zh ? "备份清理完成" : "Backup cleanup finished",
             "refreshed" => zh ? "已刷新" : "Refreshed",
             "chooseCodexFolder" => zh ? "选择 .codex 目录" : "Choose .codex folder",
+            "chooseSqliteFolder" => zh ? "选择包含 state_5.sqlite 的目录" : "Choose the folder containing state_5.sqlite",
             "chooseBackupFolder" => zh ? "选择备份目录" : "Choose backup folder",
             "continue" => zh ? "继续" : "Continue",
             "cancel" => zh ? "取消" : "Cancel",
@@ -77,6 +80,13 @@ public static string Get(string language, string key)
             "error" => zh ? "错误" : "Error",
             "confirmWriteTitle" => zh ? "确认写操作" : "Confirm Write Action",
             "restoreTitle" => zh ? "恢复备份" : "Restore Backup",
+            "relocationTitle" => zh ? "确认 SQLite Home 迁移" : "Confirm SQLite Home Relocation",
+            "relocationConfigConflict" => zh
+                ? "恢复到不同 SQLite Home 时不能同时恢复 config.toml。请取消勾选恢复配置后重试，以保留当前目标配置。"
+                : "Restoring to a different SQLite Home cannot also restore config.toml. Disable config restore and try again to preserve the current target configuration.",
+            "relocationMessage" => zh
+                ? "备份中的 SQLite Home 与当前目标不同。\n\n备份来源: {0}\n恢复目标: {1}\n\n确认将数据库恢复到当前目标吗？"
+                : "The backup SQLite Home differs from the current target.\n\nBackup source: {0}\nRestore target: {1}\n\nRestore the database to the current target?",
             "cleanTitle" => zh ? "清理旧备份" : "Clean Old Backups",
             "current" => zh ? "当前" : "current",
             "manual" => zh ? "手动" : "manual",
diff --git a/desktop/CodexProviderSync.Mac/MainWindow.cs b/desktop/CodexProviderSync.Mac/MainWindow.cs
index 9c28024..3321ece 100644
--- a/desktop/CodexProviderSync.Mac/MainWindow.cs
+++ b/desktop/CodexProviderSync.Mac/MainWindow.cs
@@ -15,6 +15,9 @@ public sealed class MainWindow : Window
     private readonly SettingsService _settingsService = new();
 
     private readonly TextBox _codexHomeText = new();
+    private readonly TextBlock _sqliteHomeLabel = new();
+    private readonly TextBox _sqliteHomeText = new();
+    private readonly Button _browseSqliteHomeButton = new();
     private readonly ComboBox _recentHomes = new();
     private readonly TextBlock _languageLabel = new();
     private readonly ComboBox _languageCombo = new();
@@ -51,6 +54,7 @@ public sealed class MainWindow : Window
     private StatusSnapshot? _currentStatus;
     private bool _loadingSettings;
     private string _language = MacUiText.English;
+    private string? _sqliteOverrideCodexHome;
 
     public MainWindow()
     {
@@ -99,10 +103,13 @@ private Control BuildCodexHomePanel()
         Grid panel = new()
         {
             ColumnDefinitions = new ColumnDefinitions("Auto,*,170,Auto,Auto,Auto,132"),
+            RowDefinitions = new RowDefinitions("Auto,Auto"),
+            RowSpacing = 8,
             ColumnSpacing = 10
         };
 
         ConfigureLabel(_codexHomeLabel, "Codex Home");
+        ConfigureLabel(_sqliteHomeLabel, "SQLite Home");
         ConfigureLabel(_languageLabel, "Language");
         _codexHomeText.PlaceholderText = AppConstants.DefaultCodexHome();
         _codexHomeText.MinHeight = 34;
@@ -116,6 +123,10 @@ private Control BuildCodexHomePanel()
         _browseButton.MinHeight = 34;
         _refreshButton.Content = "Refresh";
         _refreshButton.MinHeight = 34;
+        _sqliteHomeText.PlaceholderText = "Resolved automatically when empty";
+        _sqliteHomeText.MinHeight = 34;
+        _browseSqliteHomeButton.Content = "Browse";
+        _browseSqliteHomeButton.MinHeight = 34;
 
         panel.Children.Add(_codexHomeLabel);
         panel.Children.Add(_codexHomeText);
@@ -124,12 +135,21 @@ private Control BuildCodexHomePanel()
         panel.Children.Add(_refreshButton);
         panel.Children.Add(_languageLabel);
         panel.Children.Add(_languageCombo);
+        panel.Children.Add(_sqliteHomeLabel);
+        panel.Children.Add(_sqliteHomeText);
+        panel.Children.Add(_browseSqliteHomeButton);
         Grid.SetColumn(_codexHomeText, 1);
         Grid.SetColumn(_recentHomes, 2);
         Grid.SetColumn(_browseButton, 3);
         Grid.SetColumn(_refreshButton, 4);
         Grid.SetColumn(_languageLabel, 5);
         Grid.SetColumn(_languageCombo, 6);
+        Grid.SetRow(_sqliteHomeLabel, 1);
+        Grid.SetRow(_sqliteHomeText, 1);
+        Grid.SetColumn(_sqliteHomeText, 1);
+        Grid.SetColumnSpan(_sqliteHomeText, 2);
+        Grid.SetRow(_browseSqliteHomeButton, 1);
+        Grid.SetColumn(_browseSqliteHomeButton, 3);
         return Card(panel);
     }
 
@@ -286,6 +306,7 @@ private Control BuildLogPanel()
     private void WireEvents()
     {
         _browseButton.Click += async (_, _) => await BrowseCodexHomeAsync();
+        _browseSqliteHomeButton.Click += async (_, _) => await BrowseSqliteHomeAsync();
         _refreshButton.Click += async (_, _) => await RefreshStatusAsync();
         _languageCombo.SelectionChanged += async (_, _) => await ChangeLanguageAsync();
         _recentHomes.SelectionChanged += (_, _) =>
@@ -293,6 +314,7 @@ private void WireEvents()
             if (_recentHomes.SelectedItem is string home)
             {
                 _codexHomeText.Text = home;
+                LoadSqliteHomeOverride(home);
             }
         };
         _addProviderButton.Click += async (_, _) => await AddManualProviderAsync();
@@ -311,6 +333,7 @@ private void WireEvents()
         _openBackupButton.Click += async (_, _) => await OpenBackupFolderAsync();
         _pruneBackupsButton.Click += async (_, _) => await PruneBackupsAsync();
         _codexHomeText.LostFocus += async (_, _) => await PersistHomeSelectionAsync();
+        _sqliteHomeText.LostFocus += async (_, _) => await PersistSqliteHomeOverrideAsync(CaptureStorageSelection());
         _manualProviderText.KeyDown += async (_, args) =>
         {
             if (args.Key == Key.Enter)
@@ -331,6 +354,7 @@ private async Task LoadStateAsync()
         ApplyWindowBounds(_settings.WindowBounds);
         ReloadRecentHomes();
         _codexHomeText.Text = _settings.LastCodexHome ?? AppConstants.DefaultCodexHome();
+        LoadSqliteHomeOverride(CurrentCodexHome());
         _backupRetentionInput.Value = Math.Max(1, _settings.BackupRetentionCount);
         AppendLog($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] {T("loadedSettings")}: {_settingsService.SettingsPath}");
         _loadingSettings = false;
@@ -339,8 +363,9 @@ private async Task LoadStateAsync()
 
     private async Task RefreshStatusAsync()
     {
-        string codexHome = CurrentCodexHome();
-        await RunBusyAsync(T("refreshing"), () => RefreshStatusCoreAsync(codexHome));
+        (string codexHome, string? sqliteHome) = CaptureStorageSelection();
+        await PersistSqliteHomeOverrideAsync((codexHome, sqliteHome));
+        await RunBusyAsync(T("refreshing"), () => RefreshStatusCoreAsync(codexHome, sqliteHome));
     }
 
     private async Task ChangeLanguageAsync()
@@ -390,7 +415,7 @@ private async Task BrowseCodexHomeAsync()
 
     private async Task PersistHomeSelectionAsync()
     {
-        string codexHome = CurrentCodexHome();
+        (string codexHome, _) = CaptureStorageSelection();
         if (string.IsNullOrWhiteSpace(codexHome))
         {
             return;
@@ -402,6 +427,50 @@ private async Task PersistHomeSelectionAsync()
         ReloadRecentHomes();
     }
 
+    private async Task BrowseSqliteHomeAsync()
+    {
+        (string codexHome, string? sqliteHome) = CaptureStorageSelection();
+        string startPath = sqliteHome ?? codexHome;
+        IStorageFolder? start = Directory.Exists(startPath)
+            ? await StorageProvider.TryGetFolderFromPathAsync(startPath)
+            : null;
+        IReadOnlyList<IStorageFolder> folders = await StorageProvider.OpenFolderPickerAsync(
+            new FolderPickerOpenOptions
+            {
+                Title = T("chooseSqliteFolder"),
+                AllowMultiple = false,
+                SuggestedStartLocation = start
+            });
+        if (folders.Count == 0 || folders[0].Path.LocalPath is not { Length: > 0 } selected)
+        {
+            return;
+        }
+
+        (codexHome, _) = CaptureStorageSelection();
+        _sqliteHomeText.Text = selected;
+        await PersistSqliteHomeOverrideAsync((codexHome, selected));
+        await RefreshStatusAsync();
+    }
+
+    private async Task PersistSqliteHomeOverrideAsync((string CodexHome, string? SqliteHome) selection)
+    {
+        if (_loadingSettings)
+        {
+            return;
+        }
+        _settings = _settingsService.RecordSqliteHomeOverride(
+            _settings,
+            selection.CodexHome,
+            selection.SqliteHome);
+        await _settingsService.SaveAsync(_settings);
+    }
+
+    private void LoadSqliteHomeOverride(string codexHome)
+    {
+        _sqliteOverrideCodexHome = Path.GetFullPath(codexHome);
+        _sqliteHomeText.Text = _settingsService.GetSqliteHomeOverride(_settings, codexHome) ?? string.Empty;
+    }
+
     private async Task PersistBackupRetentionAsync()
     {
         if (_loadingSettings)
@@ -454,6 +523,7 @@ private async Task RemoveManualProviderAsync()
 
     private async Task ExecuteSyncOrSwitchAsync()
     {
+        (string codexHome, string? sqliteHome) = CaptureStorageSelection();
         string? provider = SelectedProvider();
         if (string.IsNullOrWhiteSpace(provider))
         {
@@ -474,25 +544,34 @@ private async Task ExecuteSyncOrSwitchAsync()
 
         await RunBusyAsync(T("executing"), async () =>
         {
-            string codexHome = CurrentCodexHome();
+            await PersistSqliteHomeOverrideAsync((codexHome, sqliteHome));
             int backupRetentionCount = CurrentBackupRetentionCount();
             SyncResult result = IsSwitchMode()
-                ? await Task.Run(async () => await _syncService.RunSwitchAsync(codexHome, provider, backupRetentionCount))
-                : await Task.Run(async () => await _syncService.RunSyncAsync(codexHome, provider: provider, keepCount: backupRetentionCount));
+                ? await Task.Run(async () => await _syncService.RunSwitchAsync(
+                    codexHome,
+                    provider,
+                    backupRetentionCount,
+                    explicitSqliteHome: sqliteHome))
+                : await Task.Run(async () => await _syncService.RunSyncAsync(
+                    codexHome,
+                    provider: provider,
+                    keepCount: backupRetentionCount,
+                    explicitSqliteHome: sqliteHome));
 
             _settings = _settingsService.UpdateState(_settings, provider, result.BackupDir, CaptureWindowBounds(), backupRetentionCount);
             await _settingsService.SaveAsync(_settings);
             AppendLog($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] {T("executionFinished")}");
             AppendLog(MacDisplayFormatter.FormatSyncResult(result, IsSwitchMode() ? T("switchedAndSynced") : T("synced"), _language));
             AppendLog(string.Empty);
-            await RefreshStatusCoreAsync(codexHome);
+            await RefreshStatusCoreAsync(codexHome, sqliteHome);
             SelectProvider(provider);
         });
     }
 
     private async Task RestoreBackupAsync()
     {
-        string backupRoot = _currentStatus?.BackupRoot ?? AppConstants.DefaultBackupRoot(CurrentCodexHome());
+        (string codexHome, string? sqliteHome) = CaptureStorageSelection();
+        string backupRoot = _currentStatus?.BackupRoot ?? AppConstants.DefaultBackupRoot(codexHome);
         string initialBackupDir = Directory.Exists(_settings.LastBackupDirectory)
             ? _settings.LastBackupDirectory!
             : backupRoot;
@@ -536,9 +615,44 @@ private async Task RestoreBackupAsync()
             return;
         }
 
+        bool allowSqliteHomeRelocation = false;
+        try
+        {
+            if (restoreDatabase)
+            {
+                BackupStorageInfo backupStorage = await _syncService.GetBackupStorageInfoAsync(backupDir);
+                StatusSnapshot targetStatus = await _syncService.GetStatusAsync(codexHome, sqliteHome);
+                string targetSqliteHome = targetStatus.StateDbLocation is null
+                    ? targetStatus.SqliteHome
+                    : Path.GetDirectoryName(targetStatus.StateDbLocation.Path)!;
+                if (backupStorage.Version >= 2
+                    && !string.IsNullOrWhiteSpace(backupStorage.SqliteHome)
+                    && !PathsEqual(backupStorage.SqliteHome, targetSqliteHome))
+                {
+                    if (restoreConfig)
+                    {
+                        await ShowInfoAsync(T("relocationConfigConflict"));
+                        return;
+                    }
+                    if (!await ConfirmAsync(
+                        T("relocationTitle"),
+                        string.Format(T("relocationMessage"), backupStorage.SqliteHome, targetSqliteHome)))
+                    {
+                        return;
+                    }
+                    allowSqliteHomeRelocation = true;
+                }
+            }
+        }
+        catch (Exception error)
+        {
+            AppendLog($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] {T("error")}: {error}");
+            await ShowErrorAsync(error);
+            return;
+        }
+
         await RunBusyAsync(T("restoring"), async () =>
         {
-            string codexHome = CurrentCodexHome();
             RestoreResult result = await Task.Run(async () => await _syncService.RunRestoreAsync(
                 codexHome,
                 backupDir,
@@ -546,14 +660,16 @@ await RunBusyAsync(T("restoring"), async () =>
                 {
                     RestoreConfig = restoreConfig,
                     RestoreDatabase = restoreDatabase,
-                    RestoreSessions = restoreSessions
-                }));
+                    RestoreSessions = restoreSessions,
+                    AllowSqliteHomeRelocation = allowSqliteHomeRelocation
+                },
+                sqliteHome));
             _settings = _settingsService.UpdateState(_settings, SelectedProvider(), backupDir, CaptureWindowBounds(), CurrentBackupRetentionCount());
             await _settingsService.SaveAsync(_settings);
             AppendLog($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] {T("restoreFinished")}");
             AppendLog(MacDisplayFormatter.FormatRestoreResult(result, _language));
             AppendLog(string.Empty);
-            await RefreshStatusCoreAsync(codexHome);
+            await RefreshStatusCoreAsync(codexHome, sqliteHome);
         });
     }
 
@@ -578,6 +694,7 @@ private async Task OpenBackupFolderAsync()
 
     private async Task PruneBackupsAsync()
     {
+        (string codexHome, string? sqliteHome) = CaptureStorageSelection();
         if (!await ConfirmAsync(
             T("cleanTitle"),
             string.Format(T("cleanMessage"), CurrentBackupRetentionCount())))
@@ -587,18 +704,19 @@ private async Task PruneBackupsAsync()
 
         await RunBusyAsync(T("cleaning"), async () =>
         {
-            string codexHome = CurrentCodexHome();
             BackupPruneResult result = await Task.Run(async () => await _syncService.RunPruneBackupsAsync(codexHome, CurrentBackupRetentionCount()));
             AppendLog($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] {T("backupCleanupFinished")}");
             AppendLog(MacDisplayFormatter.FormatBackupPruneResult(result, _language));
             AppendLog(string.Empty);
-            await RefreshStatusCoreAsync(codexHome);
+            await RefreshStatusCoreAsync(codexHome, sqliteHome);
         });
     }
 
-    private async Task RefreshStatusCoreAsync(string codexHome)
+    private async Task RefreshStatusCoreAsync(string codexHome, string? sqliteHome)
     {
-        _currentStatus = await Task.Run(async () => await _syncService.GetStatusAsync(codexHome));
+        _currentStatus = await Task.Run(async () => await _syncService.GetStatusAsync(
+            codexHome,
+            sqliteHome));
         _settings = _settingsService.RecordCodexHome(_settings, _currentStatus.CodexHome);
         _settings = _settingsService.MergeDetectedProviders(_settings, _syncService.ExtractDetectedProviderIds(_currentStatus));
         _settings = _settingsService.UpdateState(_settings, SelectedProvider(), _settings.LastBackupDirectory, CaptureWindowBounds(), CurrentBackupRetentionCount());
@@ -747,6 +865,22 @@ private string CurrentCodexHome()
         return string.IsNullOrWhiteSpace(text) ? AppConstants.DefaultCodexHome() : text;
     }
 
+    private string? CurrentSqliteHomeOverride()
+    {
+        string text = (_sqliteHomeText.Text ?? string.Empty).Trim();
+        return string.IsNullOrWhiteSpace(text) ? null : text;
+    }
+
+    private (string CodexHome, string? SqliteHome) CaptureStorageSelection()
+    {
+        string codexHome = CurrentCodexHome();
+        if (_sqliteOverrideCodexHome is null || !PathsEqual(_sqliteOverrideCodexHome, codexHome))
+        {
+            LoadSqliteHomeOverride(codexHome);
+        }
+        return (codexHome, CurrentSqliteHomeOverride());
+    }
+
     private int CurrentBackupRetentionCount()
     {
         decimal value = _backupRetentionInput.Value ?? AppConstants.DefaultBackupRetentionCount;
@@ -762,7 +896,12 @@ private void PersistUiState()
     {
         try
         {
-            _settings = _settingsService.RecordCodexHome(_settings, CurrentCodexHome());
+            (string codexHome, string? sqliteHome) = CaptureStorageSelection();
+            _settings = _settingsService.RecordCodexHome(_settings, codexHome);
+            _settings = _settingsService.RecordSqliteHomeOverride(
+                _settings,
+                codexHome,
+                sqliteHome);
             _settings = _settingsService.UpdateUiLanguage(_settings, _language);
             _settings = _settingsService.UpdateState(_settings, SelectedProvider(), _settings.LastBackupDirectory, CaptureWindowBounds(), CurrentBackupRetentionCount());
             _settingsService.Save(_settings);
@@ -826,6 +965,7 @@ private void SetBusy(bool busy, string stateText)
         _busyText.Foreground = busy ? Brush.Parse("#b45309") : Brush.Parse("#166534");
 
         _browseButton.IsEnabled = !busy;
+        _browseSqliteHomeButton.IsEnabled = !busy;
         _refreshButton.IsEnabled = !busy;
         _addProviderButton.IsEnabled = !busy;
         _removeProviderButton.IsEnabled = !busy;
@@ -841,6 +981,7 @@ private void SetBusy(bool busy, string stateText)
         _providerList.IsEnabled = !busy;
         _manualProviderText.IsEnabled = !busy;
         _codexHomeText.IsEnabled = !busy;
+        _sqliteHomeText.IsEnabled = !busy;
         _recentHomes.IsEnabled = !busy;
         _languageCombo.IsEnabled = !busy;
     }
@@ -874,8 +1015,11 @@ private async Task ShowErrorAsync(Exception error)
     private void ApplyLanguage()
     {
         _languageLabel.Text = T("language");
+        _sqliteHomeLabel.Text = T("sqliteHome");
+        _sqliteHomeText.PlaceholderText = T("sqliteHomePlaceholder");
         _recentHomes.PlaceholderText = T("recent");
         _browseButton.Content = T("browse");
+        _browseSqliteHomeButton.Content = T("browse");
         _refreshButton.Content = T("refresh");
         _statusTitle.Text = T("status");
         _providersTitle.Text = T("providers");
@@ -905,6 +1049,14 @@ private string T(string key)
         return MacUiText.Get(_language, key);
     }
 
+    private static bool PathsEqual(string left, string right)
+    {
+        return string.Equals(
+            Path.GetFullPath(left),
+            Path.GetFullPath(right),
+            OperatingSystem.IsWindows() ? StringComparison.OrdinalIgnoreCase : StringComparison.Ordinal);
+    }
+
     private static Border Card(Control content)
     {
         return new Border
diff --git a/docs/README_EN.md b/docs/README_EN.md
index ae655a4..d862a1d 100644
--- a/docs/README_EN.md
+++ b/docs/README_EN.md
@@ -30,7 +30,7 @@ The tool does not sign in, manage accounts, or switch authentication. Switch Pro
 ## What It Updates
 
 - Rollout metadata under `~/.codex/sessions` and `~/.codex/archived_sessions`.
-- Codex SQLite thread records. It prefers `~/.codex/sqlite/state_5.sqlite` and supports the legacy `~/.codex/state_5.sqlite` location.
+- Codex SQLite thread records, including layouts where SQLite is stored outside Codex Home.
 - Project-visibility path information and related model metadata when required.
 - Managed backups before each synchronization, with restore and pruning support.
 - Large rollout files in place when safe, with automatic fallback to a full safe rewrite.
@@ -49,6 +49,8 @@ For normal Windows use, download and extract `CodexProviderSync.exe` from [Relea
 
 The GUI keeps backups and displays the synchronization result. It checks for a stable release in the background on the first launch of each local day, with a 10-second lookup deadline. Manual update checks remain available. Execution logs are stored under `%AppData%\codex-provider-sync\logs`.
 
+The Windows GUI supports a separate SQLite Home on the Windows filesystem for each Codex Home. WSL UNC paths such as `\\wsl.localhost\...` and `\\wsl$\...` are diagnostic-only; the GUI reports the safety boundary and disables synchronization and restore. Run the CLI inside WSL for a Windows Codex Home plus WSL SQLite Home layout.
+
 The Windows executable is currently unsigned, so browser downloads may trigger a SmartScreen warning. Download it only from this project's Releases and verify the matching SHA-256 when needed.
 
 See [README_GUI_ZH.md](README_GUI_ZH.md) for the full Windows guide. A self-built Avalonia macOS app is also available; see [README_MAC_GUI_ZH.md](README_MAC_GUI_ZH.md).
@@ -75,7 +77,18 @@ Common commands:
 | `codex-provider watch` | Watch config, SQLite, and WAL changes and synchronize automatically |
 | `codex-provider watch --once` | Exit after the first change is synchronized successfully |
 
-`switch` accepts `--model <NAME>` to set the root model explicitly, or `--keep-root-model` to change only the Provider. All main commands accept `--codex-home <PATH>`.
+`switch` accepts `--model <NAME>` to set the root model explicitly, or `--keep-root-model` to change only the Provider. All main commands accept `--codex-home <PATH>` and `--sqlite-home <PATH>`.
+
+SQLite Home precedence is: CLI override, root-level `sqlite_home` in `config.toml`, `CODEX_SQLITE_HOME`, then `<Codex Home>/sqlite`. The legacy `<Codex Home>/state_5.sqlite` fallback is enabled only for the default layout. An explicit SQLite Home never falls back to a stale database under Codex Home.
+
+For a Windows Codex Home with app-server and SQLite running in WSL, invoke the CLI from WSL:
+
+```bash
+codex-provider status --codex-home /mnt/c/Users/you/.codex --sqlite-home /home/you/.codex/sqlite
+codex-provider sync --codex-home /mnt/c/Users/you/.codex --sqlite-home /home/you/.codex/sqlite
+```
+
+`status` reports the effective SQLite Home and its source. If an explicit location has no `state_5.sqlite`, read-only status reports the diagnostic while write operations fail. If a database is deleted from the default layout, `restore` can rebuild it at its original default location from backup metadata. New metadata v2 backups record the separate SQLite Home. Restoring a v2 backup to a different SQLite Home is rejected unless relocation is explicitly confirmed; the CLI requires `--sqlite-home`, `--allow-sqlite-home-relocation`, and `--no-config` so the restored config cannot point Codex back to the source SQLite Home.
 
 Node.js 24+ uses the built-in `node:sqlite` module. Older supported Node.js releases use the optional `better-sqlite3` dependency.
 
@@ -90,6 +103,7 @@ Before each `sync` or `switch`, the tool creates a backup under:
 - It does not modify messages, session titles, authentication, `auth.json`, or `updated_at`.
 - It does not copy configuration or session files between devices; it only repairs metadata in the current Codex Home.
 - If SQLite is in use, close Codex, Codex App, and app-server before retrying.
+- A Windows process that resolves SQLite Home through a WSL UNC path reports a dedicated safety diagnostic and stops immediately. Continue inside that WSL distribution with the Linux `/home/...` path.
 - If a live session locks a rollout file, the tool skips that file and continues. Run sync again after the session ends for a complete update.
 - Sessions containing `encrypted_content` may become visible across Providers/accounts but still fail to continue or compact with `invalid_encrypted_content`.
 - Codex Desktop currently shows only the latest 50 sessions on its first page. If `/resume` can see a session but the project view cannot, inspect the `first page` / `ranks` diagnostics. This tool does not alter timestamps to bypass that upstream limit.
@@ -108,10 +122,13 @@ git clone https://github.com/Dailin521/codex-provider-sync.git
 cd codex-provider-sync
 npm test
 dotnet test desktop/CodexProviderSync.Core.Tests/CodexProviderSync.Core.Tests.csproj
+./scripts/test-wsl-unc-safety.sh
 pwsh ./scripts/publish-gui.ps1
 ./scripts/publish-gui-macos.sh
 ```
 
+Run `test-wsl-unc-safety.sh` from WSL. It invokes Windows `dotnet.exe` to verify the safety guard against a real SQLite database on WSL ext4.
+
 ## License
 
 MIT
diff --git a/docs/README_GUI_ZH.md b/docs/README_GUI_ZH.md
index 334a74e..353bdd2 100644
--- a/docs/README_GUI_ZH.md
+++ b/docs/README_GUI_ZH.md
@@ -20,6 +20,7 @@ macOS 桌面版说明见 [README_MAC_GUI_ZH.md](README_MAC_GUI_ZH.md)。
 - 支持手动清理旧备份
 - 支持从 backup 目录恢复
 - 恢复时可分别选择 config、SQLite、rollout metadata
+- 支持为每个 Codex Home 单独指定 Windows 文件系统中的 SQLite Home；WSL SQLite Home 会显示安全诊断，并引导用户在 WSL 内运行 CLI
 - 当前状态、执行结果和常用提示使用中文显示
 - 常规执行日志按天写入本地并自动保留最近 30 天
 - 支持直接打开日志目录
@@ -47,15 +48,22 @@ GUI“刷新”会显示项目可见性诊断，例如 `first page 0/50`、`rank
 
 1. 打开 `CodexProviderSync.exe`
 2. 确认顶部 `Codex Home` 路径
-3. 点击“刷新”
-4. 在中间列表里选择目标 Provider
-5. 如果你希望同时改写 `config.toml` 根级 provider，勾选右侧复选框
-6. 根据需要调整“自动保留最近 N 份备份”
-7. 点击“立即同步”
-8. 如需回滚，点击“恢复备份”
-9. 如需立刻清理旧备份，点击“清理旧备份”
-10. 如需复制或查看历史执行信息，点击“打开日志目录”
-11. 软件每天首次启动会自动检查一次更新，也可以点击“检查更新”立即重试
+3. 如果 SQLite 位于 Windows 文件系统中的其它目录，在 `SQLite Home` 填写或选择包含 `state_5.sqlite` 的目录；留空时按配置自动解析
+4. 点击“刷新”，核对状态中的有效 SQLite Home、来源和数据库路径
+5. 在中间列表里选择目标 Provider
+6. 如果你希望同时改写 `config.toml` 根级 provider，勾选右侧复选框
+7. 根据需要调整“自动保留最近 N 份备份”
+8. 点击“立即同步”
+9. 如需回滚，点击“恢复备份”
+10. 如需立刻清理旧备份，点击“清理旧备份”
+11. 如需复制或查看历史执行信息，点击“打开日志目录”
+12. 软件每天首次启动会自动检查一次更新，也可以点击“检查更新”立即重试
+
+GUI 中的 SQLite Home override 按 Codex Home 保存在 GUI settings 中，不会写入 `config.toml`。解析优先级为：GUI override → `config.toml` 根级 `sqlite_home` → `CODEX_SQLITE_HOME` → `<Codex Home>\sqlite`。只有最后一种默认布局会检查旧路径 `<Codex Home>\state_5.sqlite`。
+
+Windows GUI 将 `\\wsl.localhost\<发行版>\...` 和 `\\wsl$\<发行版>\...` 一类 WSL UNC 路径识别为仅诊断路径。Windows 与 WSL 之间的文件访问层缺少 SQLite 所需的可靠锁语义；“刷新”会立即显示安全诊断，“立即同步”和“恢复备份”也会被禁用。请进入对应 WSL 发行版，并使用 `/home/...` 形式的 Linux SQLite Home 运行 CLI。
+
+对于受支持的 Windows 本地路径，显式位置缺少 `state_5.sqlite` 时，“刷新”会显示缺库诊断，写操作会停止，并保持此显式路径作为唯一目标。默认布局中的数据库被删除时，可以从有效备份恢复到原默认位置。从 metadata v2 备份恢复到不同 SQLite Home 时，必须取消勾选“恢复配置文件”；GUI 随后会显示来源与目标并要求二次确认。
 
 ## 更新与日志
 
@@ -75,6 +83,7 @@ Windows GUI 每天首次启动会在后台检查一次最新的稳定版 GitHub
 ## 注意事项
 
 - 如果 `state_5.sqlite` 被占用，请先关闭 Codex / Codex App / app-server 再重试
+- 如果状态显示 WSL UNC 路径安全诊断，请进入对应 WSL 发行版，并使用 Linux SQLite Home 路径运行 CLI
 - 如果某个 rollout 文件仍被活跃会话占用，程序会跳过它并在日志区列出来
 - 每日执行日志使用 UTF-8，可在程序运行期间读取；超过 30 天的同类日志会自动清理
 - 自动清理和手动清理都只会处理由本工具创建的备份目录
diff --git a/docs/README_MAC_GUI_ZH.md b/docs/README_MAC_GUI_ZH.md
index d6dacc2..ce5243c 100644
--- a/docs/README_MAC_GUI_ZH.md
+++ b/docs/README_MAC_GUI_ZH.md
@@ -31,6 +31,7 @@ DOTNET=/path/to/dotnet ./scripts/publish-gui-macos.sh
 ## 功能
 
 - 选择或输入 Codex Home，默认 `~/.codex`
+- 为每个 Codex Home 单独指定 SQLite Home；留空时按配置自动解析
 - `Refresh` 查看当前 provider、rollout provider counts、SQLite provider counts、备份统计、project visibility 和 `encrypted_content` 风险提示
 - Provider 列表展示 `config`、`rollout`、`SQLite`、`manual` 来源
 - 手动添加或删除 provider
@@ -45,6 +46,7 @@ DOTNET=/path/to/dotnet ./scripts/publish-gui-macos.sh
 
 - App 启动和 `Refresh` 不会修改 Codex Home 下的 session、SQLite 或 `config.toml` 元数据
 - 写操作前会弹出确认
+- metadata v2 备份恢复到不同 SQLite Home 时，会显示来源与目标并再次确认
 - `sync` 和 `switch` 由 Core 先创建 backup，再修改 metadata
 - `encrypted_content` 只提示风险，不承诺修复
 - 不处理 `auth.json`
@@ -63,6 +65,8 @@ DOTNET=/path/to/dotnet ./scripts/publish-gui-macos.sh
 
 如果看到 `state_5.sqlite is currently in use`，关闭上述进程后重试。
 
+SQLite Home 的解析优先级为：GUI override → `config.toml` 根级 `sqlite_home` → `CODEX_SQLITE_HOME` → `<Codex Home>/sqlite`。GUI override 按 Codex Home 保存在 App settings 中，不会写入 `config.toml`。显式位置缺库时只允许刷新诊断，写操作不会回退到其它数据库；默认布局中的数据库被删除时，可以从有效备份恢复到原默认位置。恢复到不同 SQLite Home 时必须取消勾选配置恢复，并再次确认来源和目标。
+
 如果日志显示跳过 locked rollout files，通常表示当前会话仍占用 rollout 文件。同步大多已完成；等会话结束后再运行一次 sync 可补齐这些文件。
 
 ## 发布说明
diff --git a/scripts/test-wsl-unc-safety.sh b/scripts/test-wsl-unc-safety.sh
new file mode 100755
index 0000000..29f3536
--- /dev/null
+++ b/scripts/test-wsl-unc-safety.sh
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+dotnet_exe="${DOTNET_EXE:-/mnt/c/Program Files/dotnet/dotnet.exe}"
+wsl_test_root="$(mktemp -d /tmp/codex-provider-sync-wsl-unc.XXXXXX)"
+sqlite_home="$wsl_test_root/sqlite"
+
+cleanup() {
+  rm -rf "$wsl_test_root"
+}
+trap cleanup EXIT
+
+cd "$repo_dir"
+mkdir -p "$sqlite_home"
+node --input-type=module - "$sqlite_home/state_5.sqlite" <<'NODE'
+import { openDatabase } from "./src/sqlite.js";
+
+const database = await openDatabase(process.argv[2]);
+try {
+  database.exec(`
+    CREATE TABLE threads (
+      id TEXT PRIMARY KEY,
+      model_provider TEXT,
+      cwd TEXT NOT NULL DEFAULT '',
+      archived INTEGER NOT NULL DEFAULT 0,
+      first_user_message TEXT NOT NULL DEFAULT '',
+      model TEXT
+    );
+    INSERT INTO threads (id, model_provider, cwd, archived, first_user_message)
+    VALUES ('thread-wsl-safety', 'apigather', '/tmp', 0, 'hello');
+  `);
+} finally {
+  database.close();
+}
+NODE
+
+sqlite_home_windows="$(wslpath -w "$sqlite_home")"
+project_windows="$(wslpath -w "$repo_dir/desktop/CodexProviderSync.Core.Tests/CodexProviderSync.Core.Tests.csproj")"
+database_hash_before="$(sha256sum "$sqlite_home/state_5.sqlite")"
+
+"$dotnet_exe" test "$project_windows" --no-restore \
+  --environment "CODEX_PROVIDER_SYNC_WSL_SQLITE_HOME=$sqlite_home_windows" \
+  --filter "Category=WindowsWslIntegration"
+
+database_hash_after="$(sha256sum "$sqlite_home/state_5.sqlite")"
+if [[ "$database_hash_after" != "$database_hash_before" ]]; then
+  echo "WSL SQLite database changed during the Windows safety test." >&2
+  exit 1
+fi
diff --git a/src/backup.js b/src/backup.js
index cf38bda..e01e316 100644
--- a/src/backup.js
+++ b/src/backup.js
@@ -11,6 +11,11 @@ import {
 } from "./constants.js";
 import { assertSessionFilesWritable, restoreSessionChanges } from "./session-files.js";
 import { assertSqliteWritable, detectStateDb } from "./sqlite-state.js";
+import {
+  assertSqliteAccessSupported,
+  resolveStorageLayout,
+  withStateDbLocation
+} from "./storage-layout.js";
 
 function timestampSlug(date = new Date()) {
   return date.toISOString().replaceAll(":", "").replaceAll("-", "").replace(".", "");
@@ -27,18 +32,48 @@ async function copyIfPresent(sourcePath, destinationPath) {
   return true;
 }
 
-function dbBackupRelativePath(codexHome, dbPath, suffix) {
-  const relativePath = path.relative(codexHome, `${dbPath}${suffix}`);
+function restoreDbTargetPath(codexHome, relativePath) {
+  if (path.isAbsolute(relativePath) || relativePath.split(/[\\/]/).includes("..")) {
+    throw new Error(`Invalid database backup path: ${relativePath}`);
+  }
+  return path.join(codexHome, relativePath);
+}
+
+function safeRelativePath(root, target) {
+  const relativePath = path.relative(root, target);
   return relativePath && !relativePath.startsWith("..") && !path.isAbsolute(relativePath)
     ? relativePath
-    : `${DB_FILE_BASENAME}${suffix}`;
+    : null;
 }
 
-function restoreDbTargetPath(codexHome, relativePath) {
+function restoreSqliteTargetPath(sqliteHome, relativePath) {
   if (path.isAbsolute(relativePath) || relativePath.split(/[\\/]/).includes("..")) {
-    throw new Error(`Invalid database backup path: ${relativePath}`);
+    throw new Error(`Invalid SQLite backup path: ${relativePath}`);
   }
-  return path.join(codexHome, relativePath);
+  return path.join(sqliteHome, relativePath);
+}
+
+function storagePathsEqual(left, right) {
+  const normalizedLeft = path.resolve(left);
+  const normalizedRight = path.resolve(right);
+  return process.platform === "win32"
+    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+    : normalizedLeft === normalizedRight;
+}
+
+function resolveRestoreSqliteHome(storage, metadata, stateDb) {
+  if (stateDb) {
+    return path.dirname(stateDb.path);
+  }
+  if (metadata.version >= 2 && metadata.sqliteHome && storage.sqliteHomeSource === "default") {
+    const matchingCandidate = storage.stateDbCandidates.find((candidate) =>
+      storagePathsEqual(path.dirname(candidate.path), metadata.sqliteHome)
+    );
+    if (matchingCandidate) {
+      return path.dirname(matchingCandidate.path);
+    }
+  }
+  return storage.sqliteHome;
 }
 
 async function removeIfPresent(targetPath) {
@@ -58,25 +93,41 @@ export async function restoreGlobalStateFilesFromBackup(backupDir, codexHome) {
 }
 
 export async function createBackup({
+  storage,
   codexHome,
   targetProvider,
   sessionChanges,
   configPath,
   configBackupText
 }) {
+  const effectiveStorage = storage ?? resolveStorageLayout({ codexHome, env: {} });
+  assertSqliteAccessSupported(effectiveStorage, "create a backup");
+  codexHome = effectiveStorage.codexHome;
   const backupRoot = defaultBackupRoot(codexHome);
   const backupDir = path.join(backupRoot, timestampSlug());
   const dbDir = path.join(backupDir, "db");
   await fs.mkdir(dbDir, { recursive: true });
 
   const copiedDbFiles = [];
-  const stateDb = await detectStateDb(codexHome);
+  const copiedSqliteDbFiles = [];
+  const stateDb = Object.hasOwn(effectiveStorage, "stateDbLocation")
+    ? effectiveStorage.stateDbLocation
+    : await detectStateDb(effectiveStorage);
+  const actualSqliteHome = stateDb ? path.dirname(stateDb.path) : effectiveStorage.sqliteHome;
   if (stateDb) {
     for (const suffix of ["", "-shm", "-wal"]) {
-      const relativePath = dbBackupRelativePath(codexHome, stateDb.path, suffix);
-      const copied = await copyIfPresent(`${stateDb.path}${suffix}`, path.join(dbDir, relativePath));
-      if (copied) {
-        copiedDbFiles.push(relativePath);
+      const sourcePath = `${stateDb.path}${suffix}`;
+      const sqliteRelativePath = `${DB_FILE_BASENAME}${suffix}`;
+      const copied = await copyIfPresent(sourcePath, path.join(dbDir, "sqlite-home", sqliteRelativePath));
+      if (!copied) {
+        continue;
+      }
+      copiedSqliteDbFiles.push(sqliteRelativePath);
+
+      const legacyRelativePath = safeRelativePath(codexHome, sourcePath);
+      if (legacyRelativePath) {
+        await copyIfPresent(sourcePath, path.join(dbDir, legacyRelativePath));
+        copiedDbFiles.push(legacyRelativePath);
       }
     }
   }
@@ -120,12 +171,14 @@ export async function createBackup({
     path.join(backupDir, "metadata.json"),
     JSON.stringify(
       {
-        version: 1,
+        version: 2,
         namespace: BACKUP_NAMESPACE,
         codexHome,
+        sqliteHome: actualSqliteHome,
         targetProvider,
         createdAt: sessionManifest.createdAt,
         dbFiles: copiedDbFiles,
+        sqliteDbFiles: copiedSqliteDbFiles,
         changedSessionFiles: sessionChanges.length
       },
       null,
@@ -199,14 +252,23 @@ export async function pruneBackups(codexHome, keepCount = DEFAULT_BACKUP_RETENTI
   };
 }
 
-export async function restoreBackup(backupDir, codexHome, options = {}) {
+export async function restoreBackup(backupDir, storageOrCodexHome, options = {}) {
   const {
     restoreConfig = true,
     restoreDatabase = true,
-    restoreSessions = true
+    restoreSessions = true,
+    allowSqliteHomeRelocation = false
   } = options;
+  const storage = typeof storageOrCodexHome === "string"
+    ? resolveStorageLayout({ codexHome: storageOrCodexHome, env: {} })
+    : storageOrCodexHome;
+  assertSqliteAccessSupported(storage, "restore");
+  const codexHome = storage.codexHome;
   const metadataPath = path.join(backupDir, "metadata.json");
   const metadata = JSON.parse(await fs.readFile(metadataPath, "utf8"));
+  if (metadata.namespace !== BACKUP_NAMESPACE || ![1, 2].includes(metadata.version)) {
+    throw new Error(`Unsupported backup metadata in ${metadataPath}.`);
+  }
   if (metadata.codexHome !== codexHome) {
     throw new Error(`Backup was created for ${metadata.codexHome}, not ${codexHome}.`);
   }
@@ -218,30 +280,87 @@ export async function restoreBackup(backupDir, codexHome, options = {}) {
     await assertSessionFilesWritable(sessionManifest.files ?? []);
   }
 
-  const configBackupPath = path.join(backupDir, "config.toml");
-  if (restoreConfig) {
-    await copyIfPresent(configBackupPath, path.join(codexHome, "config.toml"));
-    await restoreGlobalStateFilesFromBackup(backupDir, codexHome);
-  }
-
+  let stateDb = null;
+  let targetSqliteHome = null;
+  let databaseRestorePlan = null;
   if (restoreDatabase) {
-    await assertSqliteWritable(codexHome);
+    stateDb = Object.hasOwn(storage, "stateDbLocation")
+      ? storage.stateDbLocation
+      : await detectStateDb(storage);
+    if (!stateDb && storage.sqliteHomeSource !== "default") {
+      throw new Error(`state_5.sqlite not found in SQLite home ${storage.sqliteHome}.`);
+    }
+    targetSqliteHome = resolveRestoreSqliteHome(storage, metadata, stateDb);
+    const sqliteHomeRelocation = metadata.version >= 2
+      && metadata.sqliteHome
+      && !storagePathsEqual(metadata.sqliteHome, targetSqliteHome);
+    if (sqliteHomeRelocation && !allowSqliteHomeRelocation) {
+      throw new Error(
+        `Backup SQLite home is ${metadata.sqliteHome}, but the current target is ${targetSqliteHome}. `
+        + "Use --allow-sqlite-home-relocation with an explicit --sqlite-home to restore to a different location."
+      );
+    }
+    if (sqliteHomeRelocation && restoreConfig) {
+      throw new Error(
+        "Cannot restore config.toml while relocating SQLite home. "
+        + "Use --no-config to preserve the current target configuration."
+      );
+    }
+    if (stateDb) {
+      await assertSqliteWritable(withStateDbLocation(storage, stateDb));
+    }
 
     const dbDir = path.join(backupDir, "db");
-    const backedUpFiles = new Set(metadata.dbFiles ?? []);
-    const backedUpBaseFiles = (metadata.dbFiles ?? [])
-      .filter((fileName) => path.basename(fileName) === DB_FILE_BASENAME);
-    for (const baseFile of backedUpBaseFiles) {
-      const basePath = restoreDbTargetPath(codexHome, baseFile);
+    const databaseFiles = metadata.version >= 2
+      ? (metadata.sqliteDbFiles ?? [])
+      : (metadata.dbFiles ?? []);
+    if (!databaseFiles.some((fileName) => path.basename(fileName) === DB_FILE_BASENAME)) {
+      throw new Error("Backup does not contain state_5.sqlite. Use --no-db to restore the remaining data.");
+    }
+    const databaseBackupRoot = metadata.version >= 2
+      ? path.join(dbDir, "sqlite-home")
+      : dbDir;
+    const restoreRoot = metadata.version >= 2 ? targetSqliteHome : codexHome;
+    const entries = [];
+    for (const fileName of databaseFiles) {
+      const targetPath = metadata.version >= 2
+        ? restoreSqliteTargetPath(restoreRoot, fileName)
+        : restoreDbTargetPath(restoreRoot, fileName);
+      const sourcePath = path.join(databaseBackupRoot, fileName);
+      await fs.access(sourcePath).catch(() => {
+        throw new Error(`Backup declares a missing SQLite file: ${sourcePath}`);
+      });
+      entries.push({ fileName, sourcePath, targetPath });
+    }
+
+    const backedUpFiles = new Set(databaseFiles);
+    const sidecarsToRemove = [];
+    for (const baseFile of databaseFiles.filter((fileName) => path.basename(fileName) === DB_FILE_BASENAME)) {
+      const basePath = metadata.version >= 2
+        ? restoreSqliteTargetPath(restoreRoot, baseFile)
+        : restoreDbTargetPath(restoreRoot, baseFile);
       for (const suffix of ["-shm", "-wal"]) {
-        const sidecarFile = `${baseFile}${suffix}`;
-        if (!backedUpFiles.has(sidecarFile)) {
-          await removeIfPresent(`${basePath}${suffix}`);
+        if (!backedUpFiles.has(`${baseFile}${suffix}`)) {
+          sidecarsToRemove.push(`${basePath}${suffix}`);
         }
       }
     }
-    for (const fileName of metadata.dbFiles ?? []) {
-      await copyIfPresent(path.join(dbDir, fileName), restoreDbTargetPath(codexHome, fileName));
+    databaseRestorePlan = { entries, sidecarsToRemove };
+  }
+
+  const configBackupPath = path.join(backupDir, "config.toml");
+  if (restoreConfig) {
+    await copyIfPresent(configBackupPath, path.join(codexHome, "config.toml"));
+    await restoreGlobalStateFilesFromBackup(backupDir, codexHome);
+  }
+
+  if (databaseRestorePlan) {
+    for (const sidecarPath of databaseRestorePlan.sidecarsToRemove) {
+      await removeIfPresent(sidecarPath);
+    }
+    for (const { sourcePath, targetPath } of databaseRestorePlan.entries) {
+      await fs.mkdir(path.dirname(targetPath), { recursive: true });
+      await fs.copyFile(sourcePath, targetPath);
     }
   }
 
diff --git a/src/cli.js b/src/cli.js
index cae2fe9..836253a 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -15,13 +15,13 @@ function printHelp() {
   console.log(`codex-provider
 
 Usage:
-  codex-provider status [--codex-home PATH]
-  codex-provider sync [--provider ID] [--keep N] [--codex-home PATH]
-  codex-provider switch <provider-id> [--model NAME] [--keep-root-model] [--keep N] [--codex-home PATH]
-  codex-provider watch [--codex-home PATH] [--debounce-ms N] [--once] [--no-state-db]
+  codex-provider status [--codex-home PATH] [--sqlite-home PATH]
+  codex-provider sync [--provider ID] [--keep N] [--codex-home PATH] [--sqlite-home PATH]
+  codex-provider switch <provider-id> [--model NAME] [--keep-root-model] [--keep N] [--codex-home PATH] [--sqlite-home PATH]
+  codex-provider watch [--codex-home PATH] [--sqlite-home PATH] [--debounce-ms N] [--once] [--no-state-db]
   codex-provider prune-backups [--keep N] [--codex-home PATH]
-  codex-provider restore <backup-dir> [--no-config] [--no-db] [--no-sessions] [--codex-home PATH]
-  codex-provider install-windows-launcher [--dir PATH] [--codex-home PATH]
+  codex-provider restore <backup-dir> [--no-config] [--no-db] [--no-sessions] [--allow-sqlite-home-relocation] [--codex-home PATH] [--sqlite-home PATH]
+  codex-provider install-windows-launcher [--dir PATH] [--codex-home PATH] [--sqlite-home PATH]
 
 switch flags:
   --model NAME         override root-level model field with NAME (e.g. "MiniMax-M3")
@@ -29,6 +29,7 @@ switch flags:
 
 watch flags:
   --codex-home PATH    override CODEX_HOME (default: ~/.codex or $CODEX_HOME)
+  --sqlite-home PATH   override sqlite_home and CODEX_SQLITE_HOME
   --debounce-ms N      wait N milliseconds after a change before syncing (default 750)
   --once               exit after the first successful sync
   --no-state-db        only watch config.toml, ignore SQLite state events
@@ -67,6 +68,7 @@ function summarizeSync(result, label) {
   const lines = [
     `${label} provider: ${result.targetProvider}`,
     `Codex home: ${result.codexHome}`,
+    `SQLite home: ${result.sqliteHome} (source: ${result.sqliteHomeSource})`,
     `Backup: ${result.backupDir}`,
     `Backup creation time: ${formatDuration(result.backupDurationMs ?? 0)}`,
     `Updated rollout files: ${result.changedSessionFiles}`,
@@ -196,7 +198,10 @@ async function main() {
 
   if (command === "status") {
     const { getStatus, renderStatus } = await loadService();
-    const status = await getStatus({ codexHome: flags["codex-home"] });
+    const status = await getStatus({
+      codexHome: flags["codex-home"],
+      sqliteHome: flags["sqlite-home"]
+    });
     console.log(renderStatus(status));
     return;
   }
@@ -219,6 +224,7 @@ async function main() {
     }
     const result = await runSync({
       codexHome: flags["codex-home"],
+      sqliteHome: flags["sqlite-home"],
       provider: flags.provider,
       keepCount: parseKeepCount(flags.keep),
       onProgress: createSyncProgressReporter(),
@@ -233,6 +239,7 @@ async function main() {
     const provider = positionals[1] ?? flags.provider;
     const result = await runSwitch({
       codexHome: flags["codex-home"],
+      sqliteHome: flags["sqlite-home"],
       provider,
       model: flags.model,
       keepRootModel: Boolean(flags["keep-root-model"]),
@@ -270,6 +277,7 @@ async function main() {
       : undefined;
     const handle = await runWatch({
       codexHome: flags["codex-home"],
+      sqliteHome: flags["sqlite-home"],
       debounceMs,
       includeStateDb: !flags["no-state-db"],
       once: Boolean(flags.once)
@@ -310,10 +318,12 @@ async function main() {
     const backupDir = positionals[1] ?? flags.backup;
     const result = await runRestore({
       codexHome: flags["codex-home"],
+      sqliteHome: flags["sqlite-home"],
       backupDir,
       restoreConfig: !flags["no-config"],
       restoreDatabase: !flags["no-db"],
-      restoreSessions: !flags["no-sessions"]
+      restoreSessions: !flags["no-sessions"],
+      allowSqliteHomeRelocation: Boolean(flags["allow-sqlite-home-relocation"])
     });
     console.log(`Restored backup from ${path.resolve(backupDir)}`);
     console.log(`Codex home: ${result.codexHome}`);
@@ -324,7 +334,8 @@ async function main() {
   if (command === "install-windows-launcher") {
     const result = await installWindowsLauncher({
       dir: flags.dir,
-      codexHome: flags["codex-home"]
+      codexHome: flags["codex-home"],
+      sqliteHome: flags["sqlite-home"]
     });
     console.log("Installed Windows launcher files:");
     console.log(`  Hidden double-click launcher: ${result.vbsPath}`);
@@ -335,6 +346,11 @@ async function main() {
     } else {
       console.log("  CODEX_HOME: default current environment / ~/.codex");
     }
+    if (result.sqliteHome) {
+      console.log(`  Fixed SQLite home: ${result.sqliteHome}`);
+    } else {
+      console.log("  SQLite home: config / environment / Codex default");
+    }
     return;
   }
 
diff --git a/src/config-file.js b/src/config-file.js
index d3f40f9..479f111 100644
--- a/src/config-file.js
+++ b/src/config-file.js
@@ -10,6 +10,48 @@ function escapeTomlString(value) {
   return value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"");
 }
 
+function decodeTomlBasicString(value) {
+  return value.replace(/\\(?:[btnfr"\\]|u[0-9A-Fa-f]{4}|U[0-9A-Fa-f]{8})/g, (escape) => {
+    const simple = {
+      "\\b": "\b",
+      "\\t": "\t",
+      "\\n": "\n",
+      "\\f": "\f",
+      "\\r": "\r",
+      '\\"': '"',
+      "\\\\": "\\"
+    };
+    if (simple[escape] !== undefined) {
+      return simple[escape];
+    }
+    const codePoint = Number.parseInt(escape.slice(2), 16);
+    return String.fromCodePoint(codePoint);
+  });
+}
+
+export function readRootStringFromConfigText(configText, key) {
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const assignment = new RegExp(`^${escapedKey}\\s*=\\s*(?:\"((?:\\\\.|[^\"\\\\])*)\"|'([^']*)')\\s*(?:#.*)?$`);
+  for (const line of splitLines(configText)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    if (trimmed.startsWith("[")) {
+      break;
+    }
+    const match = trimmed.match(assignment);
+    if (match) {
+      return match[1] !== undefined ? decodeTomlBasicString(match[1]) : match[2];
+    }
+  }
+  return null;
+}
+
+export function readSqliteHomeFromConfigText(configText) {
+  return readRootStringFromConfigText(configText, "sqlite_home");
+}
+
 export async function readConfigText(configPath) {
   return fs.readFile(configPath, "utf8");
 }
diff --git a/src/launcher.js b/src/launcher.js
index 3fe03ff..9c25ce4 100644
--- a/src/launcher.js
+++ b/src/launcher.js
@@ -17,11 +17,12 @@ function quoteForVbs(value) {
   return String(value).replace(/"/g, "\"\"");
 }
 
-function buildBatchScript({ codexHome }) {
+function buildBatchScript({ codexHome, sqliteHome }) {
   const command = [
     "codex-provider",
     "sync",
-    ...(codexHome ? ["--codex-home", quoteForBatch(codexHome)] : [])
+    ...(codexHome ? ["--codex-home", quoteForBatch(codexHome)] : []),
+    ...(sqliteHome ? ["--sqlite-home", quoteForBatch(sqliteHome)] : [])
   ].join(" ");
 
   return [
@@ -32,11 +33,12 @@ function buildBatchScript({ codexHome }) {
   ].join("\r\n") + "\r\n";
 }
 
-function buildVbsScript({ codexHome }) {
+function buildVbsScript({ codexHome, sqliteHome }) {
   const syncCommand = [
     "codex-provider",
     "sync",
-    ...(codexHome ? [`--codex-home ""${quoteForVbs(codexHome)}""`] : [])
+    ...(codexHome ? [`--codex-home ""${quoteForVbs(codexHome)}""`] : []),
+    ...(sqliteHome ? [`--sqlite-home ""${quoteForVbs(sqliteHome)}""`] : [])
   ].join(" ");
 
   return [
@@ -92,7 +94,8 @@ function buildVbsScript({ codexHome }) {
 
 export async function installWindowsLauncher({
   dir,
-  codexHome
+  codexHome,
+  sqliteHome
 } = {}) {
   const targetDir = resolveLauncherDirectory(dir);
   await fs.mkdir(targetDir, { recursive: true });
@@ -100,13 +103,14 @@ export async function installWindowsLauncher({
   const cmdPath = path.join(targetDir, WINDOWS_CMD_LAUNCHER_FILENAME);
   const vbsPath = path.join(targetDir, WINDOWS_VBS_LAUNCHER_FILENAME);
 
-  await fs.writeFile(cmdPath, buildBatchScript({ codexHome }), "utf8");
-  await fs.writeFile(vbsPath, buildVbsScript({ codexHome }), "utf8");
+  await fs.writeFile(cmdPath, buildBatchScript({ codexHome, sqliteHome }), "utf8");
+  await fs.writeFile(vbsPath, buildVbsScript({ codexHome, sqliteHome }), "utf8");
 
   return {
     targetDir,
     cmdPath,
     vbsPath,
-    codexHome: codexHome ? path.resolve(codexHome) : null
+    codexHome: codexHome ? path.resolve(codexHome) : null,
+    sqliteHome: sqliteHome ? path.resolve(sqliteHome) : null
   };
 }
diff --git a/src/service.js b/src/service.js
index ea2b23e..7ebd47c 100644
--- a/src/service.js
+++ b/src/service.js
@@ -1,11 +1,9 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 
 import {
   DEFAULT_BACKUP_RETENTION_COUNT,
   DEFAULT_PROVIDER,
-  defaultBackupRoot,
-  defaultCodexHome
+  defaultBackupRoot
 } from "./constants.js";
 import {
   configDeclaresProvider,
@@ -46,13 +44,27 @@ import {
   readThreadCwdStats,
   syncWorkspaceRoots
 } from "./workspace-roots.js";
-
-function normalizeCodexHome(explicitCodexHome) {
-  return path.resolve(explicitCodexHome ?? process.env.CODEX_HOME ?? defaultCodexHome());
-}
-
-async function ensureCodexHome(codexHome) {
-  await fs.access(codexHome);
+import {
+  assertSqliteAccessSupported,
+  ensureCodexHome,
+  isConfiguredSqliteHome,
+  missingConfiguredStateDbError,
+  normalizeCodexHome,
+  resolveStorageLayout,
+  withStateDbLocation
+} from "./storage-layout.js";
+
+async function prepareStorage({ codexHome: explicitCodexHome, sqliteHome, configText, storage, platform }) {
+  if (storage) {
+    return storage;
+  }
+  const codexHome = normalizeCodexHome(explicitCodexHome);
+  const layout = resolveStorageLayout({ codexHome, sqliteHome, configText, platform });
+  await ensureCodexHome(layout);
+  if (!layout.sqliteAccess.supported) {
+    return withStateDbLocation(layout, null);
+  }
+  return withStateDbLocation(layout, await detectStateDb(layout));
 }
 
 function formatCounts(counts) {
@@ -98,11 +110,11 @@ function buildEncryptedContentWarning(encryptedContentCounts, targetProvider) {
   return `Encrypted content warning: ${total} rollout file(s) contain encrypted_content from provider(s) ${[...riskyProviders].sort().join(", ")}. Visibility metadata can be synchronized to ${targetProvider}, but continuing or compacting those histories may fail with invalid_encrypted_content. Return to the original provider/account or start a new session if you need reliable continuation.`;
 }
 
-export async function getStatus({ codexHome: explicitCodexHome } = {}) {
+export async function getStatus({ codexHome: explicitCodexHome, sqliteHome, platform } = {}) {
   const codexHome = normalizeCodexHome(explicitCodexHome);
-  await ensureCodexHome(codexHome);
   const configPath = path.join(codexHome, "config.toml");
   const configText = await readConfigText(configPath);
+  const storage = await prepareStorage({ codexHome, sqliteHome, configText, platform });
   const current = readCurrentProviderFromConfigText(configText);
   const configuredProviders = listConfiguredProviderIds(configText);
   const {
@@ -112,18 +124,24 @@ export async function getStatus({ codexHome: explicitCodexHome } = {}) {
     userEventThreadIds,
     threadCwdById
   } = await collectSessionChanges(codexHome, "__status_only__", { skipLockedReads: true });
-  const stateDbLocation = await detectStateDb(codexHome);
-  const sqliteCounts = await readSqliteProviderCounts(codexHome);
+  const stateDbLocation = storage.stateDbLocation;
+  const sqliteCounts = storage.sqliteAccess.supported
+    ? await readSqliteProviderCounts(storage)
+    : null;
   const sqliteRepairStats = sqliteCounts && !sqliteCounts.unreadable
-    ? await readSqliteRepairStats(codexHome, { userEventThreadIds, threadCwdById })
+    ? await readSqliteRepairStats(storage, { userEventThreadIds, threadCwdById })
     : null;
-  const projectThreadVisibility = sqliteCounts?.unreadable
+  const projectThreadVisibility = !storage.sqliteAccess.supported || sqliteCounts?.unreadable
     ? []
-    : await readProjectThreadVisibility(codexHome);
+    : await readProjectThreadVisibility(storage);
   const backupSummary = await getBackupSummary(codexHome);
 
   return {
     codexHome,
+    sqliteHome: storage.sqliteHome,
+    sqliteHomeSource: storage.sqliteHomeSource,
+    sqliteAccess: storage.sqliteAccess,
+    checkedStateDbPaths: storage.stateDbCandidates.map((candidate) => candidate.path),
     currentProvider: current.provider,
     currentProviderImplicit: current.implicit,
     configuredProviders,
@@ -143,6 +161,7 @@ export async function getStatus({ codexHome: explicitCodexHome } = {}) {
 export function renderStatus(status) {
   const lines = [
     `Codex home: ${status.codexHome}`,
+    `SQLite home: ${status.sqliteHome} (source: ${status.sqliteHomeSource})`,
     `Current provider: ${status.currentProvider}${status.currentProviderImplicit ? " (implicit default)" : ""}`,
     `Configured providers: ${status.configuredProviders.join(", ")}`,
     `Backups: ${status.backupSummary.count} (${formatBytes(status.backupSummary.totalBytes)})`,
@@ -166,11 +185,15 @@ export function renderStatus(status) {
 
   lines.push("");
   lines.push("SQLite state:");
+  if (!status.sqliteAccess?.supported) {
+    lines.push(`  ${status.sqliteAccess.message}`);
+    return lines.join("\n");
+  }
   if (status.stateDbLocation) {
     const legacyNote = status.stateDbLocation.source === "legacy-root" ? " (legacy root)" : "";
     lines.push(`  database: ${status.stateDbLocation.path}${legacyNote}`);
   } else {
-    lines.push("  database: not found (checked sqlite/state_5.sqlite, state_5.sqlite)");
+    lines.push(`  database: not found (checked ${status.checkedStateDbPaths.join(", ")})`);
   }
   if (status.sqliteCounts?.unreadable) {
     lines.push(`  ${status.sqliteCounts.error ?? "state_5.sqlite is malformed or unreadable"}`);
@@ -204,21 +227,28 @@ export function renderStatus(status) {
 
 export async function runSync({
   codexHome: explicitCodexHome,
+  sqliteHome,
+  storage: providedStorage,
   provider,
   configBackupText,
   keepCount = DEFAULT_BACKUP_RETENTION_COUNT,
   sqliteBusyTimeoutMs,
   onProgress,
-  model = null
+  model = null,
+  platform
 } = {}) {
   if (!Number.isInteger(keepCount) || keepCount < 1) {
     throw new Error(`Invalid automatic keep count: ${keepCount}. Expected an integer greater than or equal to 1.`);
   }
 
-  const codexHome = normalizeCodexHome(explicitCodexHome);
-  await ensureCodexHome(codexHome);
+  const codexHome = providedStorage?.codexHome ?? normalizeCodexHome(explicitCodexHome);
   const configPath = path.join(codexHome, "config.toml");
   const configText = await readConfigText(configPath);
+  const storage = await prepareStorage({ codexHome, sqliteHome, configText, storage: providedStorage, platform });
+  assertSqliteAccessSupported(storage, "sync");
+  if (!storage.stateDbLocation && isConfiguredSqliteHome(storage)) {
+    throw missingConfiguredStateDbError(storage);
+  }
   const current = readCurrentProviderFromConfigText(configText);
   const targetProvider = provider ?? current.provider ?? DEFAULT_PROVIDER;
 
@@ -235,7 +265,7 @@ export async function runSync({
       userEventThreadIds,
       threadCwdById
     } = await collectSessionChanges(codexHome, targetProvider, { skipLockedReads: true, targetModel: model });
-    const cwdStats = await readThreadCwdStats(codexHome);
+    const cwdStats = await readThreadCwdStats(storage);
     const encryptedContentWarning = buildEncryptedContentWarning(encryptedContentCounts, targetProvider);
     emitProgress(onProgress, {
       stage: "scan_rollout_files",
@@ -260,7 +290,7 @@ export async function runSync({
       ...lockedReadPaths,
       ...lockedChanges.map((change) => change.path)
     ])].sort((left, right) => left.localeCompare(right));
-    await assertSqliteWritable(codexHome, { busyTimeoutMs: sqliteBusyTimeoutMs });
+    await assertSqliteWritable(storage, { busyTimeoutMs: sqliteBusyTimeoutMs });
 
     emitProgress(onProgress, {
       stage: "create_backup",
@@ -269,6 +299,7 @@ export async function runSync({
     });
     const backupStartedAt = Date.now();
     backupDir = await createBackup({
+      storage,
       codexHome,
       targetProvider,
       sessionChanges: writableChanges,
@@ -300,7 +331,7 @@ export async function runSync({
         writableCount: writableChanges.length
       });
       const sqliteResult = await updateSqliteProvider(
-        codexHome,
+        storage,
         targetProvider,
         async () => {
           if (writableChanges.length > 0) {
@@ -310,7 +341,7 @@ export async function runSync({
             sessionRestoreNeeded = appliedSessionChanges.length > 0;
             await updateSessionBackupManifest(backupDir, appliedSessionChanges);
           }
-          workspaceRootResult = await syncWorkspaceRoots(codexHome, { cwdStats });
+          workspaceRootResult = await syncWorkspaceRoots(storage, { cwdStats });
           globalStateRestoreNeeded = workspaceRootResult.updated;
         },
         { busyTimeoutMs: sqliteBusyTimeoutMs, userEventThreadIds, threadCwdById, targetModel: model }
@@ -350,6 +381,8 @@ export async function runSync({
       });
       return {
         codexHome,
+        sqliteHome: storage.sqliteHome,
+        sqliteHomeSource: storage.sqliteHomeSource,
         targetProvider,
         previousProvider: current.provider,
         backupDir,
@@ -403,20 +436,26 @@ export async function runSync({
 
 export async function runSwitch({
   codexHome: explicitCodexHome,
+  sqliteHome,
   provider,
   model,
   keepRootModel = false,
   keepCount = DEFAULT_BACKUP_RETENTION_COUNT,
-  onProgress
+  onProgress,
+  platform
 }) {
   if (!provider) {
     throw new Error("Missing provider id. Usage: codex-provider switch <provider-id>");
   }
 
   const codexHome = normalizeCodexHome(explicitCodexHome);
-  await ensureCodexHome(codexHome);
   const configPath = path.join(codexHome, "config.toml");
   const originalConfigText = await readConfigText(configPath);
+  const storage = await prepareStorage({ codexHome, sqliteHome, configText: originalConfigText, platform });
+  assertSqliteAccessSupported(storage, "switch");
+  if (!storage.stateDbLocation && isConfiguredSqliteHome(storage)) {
+    throw missingConfiguredStateDbError(storage);
+  }
   if (!configDeclaresProvider(originalConfigText, provider)) {
     throw new Error(`Provider "${provider}" is not available in config.toml. Configure it first or use one of: ${listConfiguredProviderIds(originalConfigText).join(", ")}`);
   }
@@ -473,6 +512,7 @@ export async function runSwitch({
     }
     const syncResult = await runSync({
       codexHome,
+      storage,
       provider,
       configBackupText: originalConfigText,
       keepCount,
@@ -492,22 +532,34 @@ export async function runSwitch({
 
 export async function runRestore({
   codexHome: explicitCodexHome,
+  sqliteHome,
   backupDir,
   restoreConfig = true,
   restoreDatabase = true,
-  restoreSessions = true
+  restoreSessions = true,
+  allowSqliteHomeRelocation = false,
+  platform
 }) {
   if (!backupDir) {
     throw new Error("Missing backup path. Usage: codex-provider restore <backup-dir>");
   }
   const codexHome = normalizeCodexHome(explicitCodexHome);
-  await ensureCodexHome(codexHome);
+  if (allowSqliteHomeRelocation && !(typeof sqliteHome === "string" && sqliteHome.trim())) {
+    throw new Error("--allow-sqlite-home-relocation requires an explicit --sqlite-home path.");
+  }
+  const configText = await readConfigText(path.join(codexHome, "config.toml"));
+  const storage = await prepareStorage({ codexHome, sqliteHome, configText, platform });
+  assertSqliteAccessSupported(storage, "restore");
+  if (restoreDatabase && !storage.stateDbLocation && isConfiguredSqliteHome(storage)) {
+    throw missingConfiguredStateDbError(storage);
+  }
   const releaseLock = await acquireLock(codexHome, "restore");
   try {
-    return await restoreBackup(path.resolve(backupDir), codexHome, {
+    return await restoreBackup(path.resolve(backupDir), storage, {
       restoreConfig,
       restoreDatabase,
-      restoreSessions
+      restoreSessions,
+      allowSqliteHomeRelocation
     });
   } finally {
     await releaseLock();
@@ -523,7 +575,7 @@ export async function runPruneBackups({
   }
 
   const codexHome = normalizeCodexHome(explicitCodexHome);
-  await ensureCodexHome(codexHome);
+  await ensureCodexHome(resolveStorageLayout({ codexHome, env: {} }));
   const releaseLock = await acquireLock(codexHome, "prune-backups");
   try {
     return await pruneBackups(codexHome, keepCount);
diff --git a/src/sqlite-state.js b/src/sqlite-state.js
index 8556632..fe4e9e7 100644
--- a/src/sqlite-state.js
+++ b/src/sqlite-state.js
@@ -3,6 +3,7 @@ import path from "node:path";
 
 import { DB_FILE_BASENAME, SESSION_DIRS, SQLITE_DIR_BASENAME } from "./constants.js";
 import { openDatabase } from "./sqlite.js";
+import { resolveStorageLayout } from "./storage-layout.js";
 
 const DEFAULT_BUSY_TIMEOUT_MS = 5000;
 
@@ -14,19 +15,15 @@ export function legacyStateDbPath(codexHome) {
   return path.join(codexHome, DB_FILE_BASENAME);
 }
 
-export function stateDbCandidates(codexHome) {
-  return [
-    {
-      path: stateDbPath(codexHome),
-      relativePath: path.join(SQLITE_DIR_BASENAME, DB_FILE_BASENAME),
-      source: "sqlite-dir"
-    },
-    {
-      path: legacyStateDbPath(codexHome),
-      relativePath: DB_FILE_BASENAME,
-      source: "legacy-root"
-    }
-  ];
+function normalizeStorage(storageOrCodexHome) {
+  if (typeof storageOrCodexHome === "string") {
+    return resolveStorageLayout({ codexHome: storageOrCodexHome, env: {} });
+  }
+  return storageOrCodexHome;
+}
+
+export function stateDbCandidates(storageOrCodexHome) {
+  return normalizeStorage(storageOrCodexHome).stateDbCandidates;
 }
 
 async function countRolloutFilesInDir(rootDir) {
@@ -117,9 +114,10 @@ function compareStateDbCandidateStats(a, b) {
   return a.priority - b.priority;
 }
 
-export async function detectStateDb(codexHome) {
+export async function detectStateDb(storageOrCodexHome) {
+  const storage = normalizeStorage(storageOrCodexHome);
   const existingCandidates = [];
-  const candidates = stateDbCandidates(codexHome);
+  const candidates = stateDbCandidates(storage);
   for (const [priority, candidate] of candidates.entries()) {
     try {
       await fs.access(candidate.path);
@@ -132,7 +130,7 @@ export async function detectStateDb(codexHome) {
     return null;
   }
 
-  const rolloutCount = await countRolloutFiles(codexHome);
+  const rolloutCount = await countRolloutFiles(storage.codexHome);
   const readableCandidates = [];
   for (const { candidate, priority } of existingCandidates) {
     try {
@@ -154,8 +152,21 @@ export async function detectStateDb(codexHome) {
   return readableCandidates.sort(compareStateDbCandidateStats)[0].candidate;
 }
 
-export async function existingStateDbPath(codexHome) {
-  return (await detectStateDb(codexHome))?.path ?? null;
+async function resolveStateDbLocation(storageOrLocation) {
+  if (!storageOrLocation) {
+    return null;
+  }
+  if (Object.hasOwn(storageOrLocation, "stateDbLocation")) {
+    return storageOrLocation.stateDbLocation;
+  }
+  if (typeof storageOrLocation.path === "string" && typeof storageOrLocation.source === "string") {
+    return storageOrLocation;
+  }
+  return detectStateDb(storageOrLocation);
+}
+
+export async function existingStateDbPath(storageOrLocation) {
+  return (await resolveStateDbLocation(storageOrLocation))?.path ?? null;
 }
 
 function tableHasColumn(db, tableName, columnName) {
@@ -206,8 +217,8 @@ export function wrapSqliteMalformedError(error, action) {
   );
 }
 
-export async function readSqliteProviderCounts(codexHome) {
-  const dbPath = await existingStateDbPath(codexHome);
+export async function readSqliteProviderCounts(storageOrLocation) {
+  const dbPath = await existingStateDbPath(storageOrLocation);
   if (!dbPath) {
     return null;
   }
@@ -259,8 +270,8 @@ export async function readSqliteProviderCounts(codexHome) {
   }
 }
 
-export async function readSqliteRepairStats(codexHome, options = {}) {
-  const dbPath = await existingStateDbPath(codexHome);
+export async function readSqliteRepairStats(storageOrLocation, options = {}) {
+  const dbPath = await existingStateDbPath(storageOrLocation);
   if (!dbPath) {
     return null;
   }
@@ -307,8 +318,8 @@ export async function readSqliteRepairStats(codexHome, options = {}) {
   }
 }
 
-export async function assertSqliteWritable(codexHome, options = {}) {
-  const dbPath = await existingStateDbPath(codexHome);
+export async function assertSqliteWritable(storageOrLocation, options = {}) {
+  const dbPath = await existingStateDbPath(storageOrLocation);
   if (!dbPath) {
     return { databasePresent: false };
   }
@@ -330,7 +341,7 @@ export async function assertSqliteWritable(codexHome, options = {}) {
   }
 }
 
-export async function updateSqliteProvider(codexHome, targetProvider, afterUpdateOrOptions, maybeOptions) {
+export async function updateSqliteProvider(storageOrLocation, targetProvider, afterUpdateOrOptions, maybeOptions) {
   const afterUpdate = typeof afterUpdateOrOptions === "function" ? afterUpdateOrOptions : null;
   const options = typeof afterUpdateOrOptions === "function"
     ? (maybeOptions ?? {})
@@ -341,7 +352,7 @@ export async function updateSqliteProvider(codexHome, targetProvider, afterUpdat
   // untouched (legacy behaviour for callers that do not track model).
   const targetModel = options.targetModel ?? null;
 
-  const dbPath = await existingStateDbPath(codexHome);
+  const dbPath = await existingStateDbPath(storageOrLocation);
   if (!dbPath) {
     if (afterUpdate) {
       await afterUpdate({
diff --git a/src/storage-layout.js b/src/storage-layout.js
new file mode 100644
index 0000000..c1eba31
--- /dev/null
+++ b/src/storage-layout.js
@@ -0,0 +1,108 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { DB_FILE_BASENAME, defaultCodexHome } from "./constants.js";
+import { readSqliteHomeFromConfigText } from "./config-file.js";
+
+function resolvePath(value, cwd) {
+  return path.resolve(cwd, value);
+}
+
+function isWslUncPath(value) {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const normalized = value.replaceAll("/", "\\");
+  return /^\\\\(?:wsl\.localhost|wsl\$)\\/i.test(normalized)
+    || /^\\\\\?\\UNC\\(?:wsl\.localhost|wsl\$)\\/i.test(normalized);
+}
+
+function resolveSqliteAccess(sqliteHome, rawSqliteHome, platform) {
+  if (platform === "win32" && (isWslUncPath(rawSqliteHome) || isWslUncPath(sqliteHome))) {
+    return {
+      supported: false,
+      reason: "windows-wsl-unc",
+      message: `Windows cannot safely access SQLite through the WSL UNC path ${rawSqliteHome ?? sqliteHome}. Run codex-provider inside WSL with a Linux SQLite Home path instead.`
+    };
+  }
+  return { supported: true, reason: null, message: null };
+}
+
+export function normalizeCodexHome(explicitCodexHome, { env = process.env, cwd = process.cwd() } = {}) {
+  return resolvePath(explicitCodexHome ?? env.CODEX_HOME ?? defaultCodexHome(), cwd);
+}
+
+export function resolveStorageLayout({
+  codexHome: explicitCodexHome,
+  sqliteHome: explicitSqliteHome,
+  configText = "",
+  env = process.env,
+  cwd = process.cwd(),
+  platform = process.platform
+} = {}) {
+  const codexHome = normalizeCodexHome(explicitCodexHome, { env, cwd });
+  const configuredSqliteHome = readSqliteHomeFromConfigText(configText);
+  const selected = [
+    [explicitSqliteHome, "cli"],
+    [configuredSqliteHome, "config"],
+    [env.CODEX_SQLITE_HOME, "env"]
+  ].find(([value]) => typeof value === "string" && value.trim());
+
+  const sqliteHomeSource = selected?.[1] ?? "default";
+  const sqliteHome = selected
+    ? resolvePath(selected[0].trim(), cwd)
+    : path.join(codexHome, "sqlite");
+  const sqliteAccess = resolveSqliteAccess(sqliteHome, selected?.[0]?.trim(), platform);
+  const allowLegacyRootFallback = sqliteHomeSource === "default";
+  const stateDbCandidates = [
+    {
+      path: path.join(sqliteHome, DB_FILE_BASENAME),
+      relativePath: allowLegacyRootFallback
+        ? path.join("sqlite", DB_FILE_BASENAME)
+        : DB_FILE_BASENAME,
+      source: allowLegacyRootFallback ? "sqlite-dir" : "sqlite-home"
+    },
+    ...(allowLegacyRootFallback
+      ? [{
+          path: path.join(codexHome, DB_FILE_BASENAME),
+          relativePath: DB_FILE_BASENAME,
+          source: "legacy-root"
+        }]
+      : [])
+  ];
+
+  return {
+    codexHome,
+    sqliteHome,
+    sqliteHomeSource,
+    sqliteAccess,
+    allowLegacyRootFallback,
+    stateDbCandidates
+  };
+}
+
+export async function ensureCodexHome(storage) {
+  await fs.access(storage.codexHome).catch(() => {
+    throw new Error(`Codex home not found at ${storage.codexHome}`);
+  });
+}
+
+export function withStateDbLocation(storage, stateDbLocation) {
+  return { ...storage, stateDbLocation };
+}
+
+export function isConfiguredSqliteHome(storage) {
+  return storage.sqliteHomeSource !== "default";
+}
+
+export function assertSqliteAccessSupported(storage, operation) {
+  if (storage.sqliteAccess?.supported === false) {
+    throw new Error(`Cannot ${operation}: ${storage.sqliteAccess.message}`);
+  }
+}
+
+export function missingConfiguredStateDbError(storage) {
+  return new Error(
+    `state_5.sqlite not found in configured SQLite home ${storage.sqliteHome} (source: ${storage.sqliteHomeSource}).`
+  );
+}
diff --git a/src/watch.js b/src/watch.js
index 4326b96..5265b5a 100644
--- a/src/watch.js
+++ b/src/watch.js
@@ -14,13 +14,16 @@ import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
 
-import { defaultCodexHome } from "./constants.js";
 import { detectStateDb } from "./sqlite-state.js";
 import { readConfigText, readRootModelFromConfigText } from "./config-file.js";
-
-function normalizeCodexHome(explicitCodexHome) {
-  return path.resolve(explicitCodexHome ?? process.env.CODEX_HOME ?? defaultCodexHome());
-}
+import {
+  assertSqliteAccessSupported,
+  isConfiguredSqliteHome,
+  missingConfiguredStateDbError,
+  normalizeCodexHome,
+  resolveStorageLayout,
+  withStateDbLocation
+} from "./storage-layout.js";
 
 function defaultDebounceMs() {
   return 750;
@@ -52,6 +55,7 @@ function makeDebouncer(delayMs, run) {
 
 export async function runWatch({
   codexHome: explicitCodexHome,
+  sqliteHome: explicitSqliteHome,
   debounceMs = defaultDebounceMs(),
   includeStateDb = true,
   once = false,
@@ -60,7 +64,8 @@ export async function runWatch({
   onShutdown,
   runSyncImpl,
   signal,
-  sleepImpl
+  sleepImpl,
+  platform
 } = {}) {
   if (!Number.isInteger(debounceMs) || debounceMs < 0) {
     throw new Error(`Invalid --debounce-ms value: ${debounceMs}. Expected a non-negative integer.`);
@@ -83,7 +88,19 @@ export async function runWatch({
     }
   };
 
-  const invokeSync = async (reason) => {
+  const resolveCurrentStorage = async () => {
+    const configText = await readConfigText(configPath);
+    const layout = resolveStorageLayout({
+      codexHome,
+      sqliteHome: explicitSqliteHome,
+      configText,
+      platform
+    });
+    assertSqliteAccessSupported(layout, "watch");
+    return withStateDbLocation(layout, await detectStateDb(layout));
+  };
+
+  const invokeSync = async (reason, storage) => {
     // Read the current root-level model on every fire so the per-thread
     // model rewrite picks up the latest value the user has in config.toml.
     // We only consider the top-level (root) `model = "..."` line — anything
@@ -98,15 +115,16 @@ export async function runWatch({
       // Missing/unreadable config; carry on with a null model.
     }
     if (typeof onSync === "function") {
-      return onSync({ reason, codexHome, model: rootModel });
+      return onSync({ reason, codexHome, sqliteHome: storage.sqliteHome, storage, model: rootModel });
     }
     if (typeof runSyncImpl === "function") {
-      return runSyncImpl({ codexHome, reason, model: rootModel });
+      return runSyncImpl({ codexHome, sqliteHome: storage.sqliteHome, storage, reason, model: rootModel });
     }
     // Lazy import to avoid pulling in the full service module until needed.
     const { runSync } = await import("./service.js");
     return runSync({
       codexHome,
+      storage,
       model: rootModel,
       onProgress: (event) => {
         if (event?.stage && event.status === "start") {
@@ -118,7 +136,10 @@ export async function runWatch({
 
   let stopped = false;
   let watchers = [];
+  let stateWatchers = [];
+  let stateWatchGeneration = 0;
   let stateDbInfo = null;
+  let activeStorage = null;
   // Track the currently-running sync (if any) so that stop()/SIGINT can
   // wait for it to drain instead of yanking the watcher out from under
   // a half-written SQLite transaction.
@@ -152,7 +173,18 @@ export async function runWatch({
     log(`[${new Date().toISOString()}] Detected change (${reason}); running sync...`);
     const task = (async () => {
       try {
-        const result = await invokeSync(reason);
+        const nextStorage = await resolveCurrentStorage();
+        if (includeStateDb && reason === "config.toml") {
+          await rebindStateWatchers(nextStorage);
+        } else {
+          activeStorage = nextStorage;
+        }
+        if (!nextStorage.stateDbLocation && isConfiguredSqliteHome(nextStorage)) {
+          log(`[${new Date().toISOString()}] Sync paused: ${missingConfiguredStateDbError(nextStorage).message} Waiting for config.toml to be fixed.`);
+          consecutiveNonBusyFailures = 0;
+          return;
+        }
+        const result = await invokeSync(reason, nextStorage);
         log(`[${new Date().toISOString()}] Sync complete: provider=${result.targetProvider}, rollout_files=${result.changedSessionFiles}, sqlite_rows=${result.sqliteRowsUpdated}${result.skippedLockedRolloutFiles?.length ? `, skipped_locked=${result.skippedLockedRolloutFiles.length}` : ""}`);
         // A successful sync resets the consecutive-failure counter
         // so a transient error followed by recovery does not
@@ -198,6 +230,8 @@ export async function runWatch({
     inFlight = task;
   });
 
+  const initialStorage = await resolveCurrentStorage();
+
   const configWatcher = fs.watch(configPath, { persistent: true }, (eventType, filename) => {
     if (stopped) {
       return;
@@ -209,39 +243,12 @@ export async function runWatch({
 
   if (includeStateDb) {
     try {
-      stateDbInfo = await detectStateDb(codexHome);
+      await rebindStateWatchers(initialStorage);
     } catch (error) {
       log(`[${new Date().toISOString()}] Could not locate state database: ${error.message}`);
     }
-    if (stateDbInfo?.path) {
-      // Watch the active database *and* its WAL sidecar. SQLite by
-      // default runs in WAL journal mode: new transactions are
-      // appended to `state_5.sqlite-wal` and only checkpointed back
-      // to the main file on a checkpoint, so watching the main
-      // file alone would miss every write Codex makes between
-      // checkpoints. We watch both, plus the -shm shared-memory
-      // file so a checkpoint still fires the change event for
-      // long-running sessions.
-      const stateDbFile = stateDbInfo.path;
-      const walFile = `${stateDbFile}-wal`;
-      const shmFile = `${stateDbFile}-shm`;
-      for (const target of [stateDbFile, walFile, shmFile]) {
-        // Watch each file directly instead of its parent
-        // directory. Watching a directory on Windows enters a
-        // libuv path that asserts in src/win/fs-event.c around
-        // line 72 when any sibling under the directory is renamed
-        // during startup (a race condition Node 22 and 24 started
-        // hitting reliably on Windows runners). Watching a single
-        // file bypasses that path entirely. The downside is that
-        // SQLite's atomic-rename of the database (or its WAL)
-        // can leave us listening on a stale handle; we re-attach
-        // the watcher on any `rename` event so the next write
-        // burst still reaches us.
-        attachStateWatcher(target, target === stateDbFile ? "state_db" : "state_db-wal");
-      }
-    } else {
-      log(`[${new Date().toISOString()}] No state database found in ${codexHome}; skipping watcher`);
-    }
+  } else {
+    activeStorage = initialStorage;
   }
 
   log(`[${new Date().toISOString()}] Watching ${configPath}${includeStateDb && stateDbInfo?.path ? `, ${stateDbInfo.path}, ${stateDbInfo.path}-wal, ${stateDbInfo.path}-shm` : ""} (debounce ${debounceMs}ms${once ? ", once" : ""})`);
@@ -251,6 +258,7 @@ export async function runWatch({
       return;
     }
     stopped = true;
+    stateWatchGeneration += 1;
     for (const watcher of watchers) {
       try {
         watcher.close();
@@ -302,14 +310,41 @@ export async function runWatch({
     }
   }
 
-  function attachStateWatcher(stateDbFile, reasonLabel) {
+  async function rebindStateWatchers(storage) {
+    stateWatchGeneration += 1;
+    const generation = stateWatchGeneration;
+    for (const watcher of stateWatchers) {
+      try {
+        watcher.close();
+      } catch {
+        // best-effort
+      }
+      const index = watchers.indexOf(watcher);
+      if (index !== -1) {
+        watchers.splice(index, 1);
+      }
+    }
+    stateWatchers = [];
+    activeStorage = storage;
+    stateDbInfo = storage.stateDbLocation;
+    if (!stateDbInfo?.path) {
+      log(`[${new Date().toISOString()}] No state database found in ${storage.sqliteHome}; waiting for config.toml changes`);
+      return;
+    }
+    const stateDbFile = stateDbInfo.path;
+    for (const target of [stateDbFile, `${stateDbFile}-wal`, `${stateDbFile}-shm`]) {
+      attachStateWatcher(target, target === stateDbFile ? "state_db" : "state_db-wal", generation);
+    }
+  }
+
+  function attachStateWatcher(stateDbFile, reasonLabel, generation) {
     // Attach (or re-attach after a rename) a single-file fs.watch
     // for the active SQLite database (or its WAL/SHM sidecar).
     // Returns when the watcher is attached so we can drive startup
     // synchronously.
     let current = null;
     const tryAttach = () => {
-      if (stopped || current !== null) {
+      if (stopped || generation !== stateWatchGeneration || current !== null) {
         return;
       }
       // WAL and SHM sidecars may not exist when the watcher starts.
@@ -338,6 +373,10 @@ export async function runWatch({
             if (idx !== -1) {
               watchers.splice(idx, 1);
             }
+            const stateIndex = stateWatchers.indexOf(watcher);
+            if (stateIndex !== -1) {
+              stateWatchers.splice(stateIndex, 1);
+            }
             setTimeout(tryAttach, 50);
             return;
           }
@@ -360,6 +399,7 @@ export async function runWatch({
         return;
       }
       watchers.push(watcher);
+      stateWatchers.push(watcher);
       current = watcher;
     };
     tryAttach();
@@ -368,7 +408,12 @@ export async function runWatch({
   return {
     codexHome,
     watchedConfigPath: configPath,
-    watchedStateDbPath: stateDbInfo?.path ?? null,
+    get watchedStateDbPath() {
+      return stateDbInfo?.path ?? null;
+    },
+    get sqliteHome() {
+      return activeStorage?.sqliteHome ?? null;
+    },
     stop: () => shutdown("external"),
     signalPromise,
     done: donePromise
diff --git a/src/workspace-roots.js b/src/workspace-roots.js
index c073ecc..b2b0dad 100644
--- a/src/workspace-roots.js
+++ b/src/workspace-roots.js
@@ -20,6 +20,12 @@ export function globalStateBackupPath(codexHome) {
   return path.join(codexHome, GLOBAL_STATE_BACKUP_FILE_BASENAME);
 }
 
+function codexHomeFrom(storageOrCodexHome) {
+  return typeof storageOrCodexHome === "string"
+    ? storageOrCodexHome
+    : storageOrCodexHome.codexHome;
+}
+
 export function normalizeComparablePath(value) {
   if (typeof value !== "string") {
     return null;
@@ -163,8 +169,8 @@ function copyResolvedObjectKeys(input, cwdStats) {
   return result;
 }
 
-export async function readThreadCwdStats(codexHome) {
-  const dbPath = await existingStateDbPath(codexHome);
+export async function readThreadCwdStats(storageOrCodexHome) {
+  const dbPath = await existingStateDbPath(storageOrCodexHome);
   if (!dbPath) {
     return [];
   }
@@ -236,7 +242,8 @@ function formatRankPreview(ranks, maxCount = 12) {
   return remaining > 0 ? `${preview} (+${remaining} more)` : preview;
 }
 
-export async function readProjectThreadVisibility(codexHome, options = {}) {
+export async function readProjectThreadVisibility(storageOrCodexHome, options = {}) {
+  const codexHome = codexHomeFrom(storageOrCodexHome);
   const pageSize = Number.isInteger(options.pageSize) && options.pageSize > 0
     ? options.pageSize
     : 50;
@@ -256,7 +263,7 @@ export async function readProjectThreadVisibility(codexHome, options = {}) {
     return [];
   }
 
-  const dbPath = await existingStateDbPath(codexHome);
+  const dbPath = await existingStateDbPath(storageOrCodexHome);
   if (!dbPath) {
     return roots.map((root) => ({
       root,
@@ -353,7 +360,8 @@ export async function readProjectThreadVisibility(codexHome, options = {}) {
   }
 }
 
-export async function syncWorkspaceRoots(codexHome, options = {}) {
+export async function syncWorkspaceRoots(storageOrCodexHome, options = {}) {
+  const codexHome = codexHomeFrom(storageOrCodexHome);
   const filePath = globalStatePath(codexHome);
   const backupPath = globalStateBackupPath(codexHome);
 
@@ -373,7 +381,7 @@ export async function syncWorkspaceRoots(codexHome, options = {}) {
   }
 
   const state = JSON.parse(originalText);
-  const cwdStats = options.cwdStats ?? await readThreadCwdStats(codexHome);
+  const cwdStats = options.cwdStats ?? await readThreadCwdStats(storageOrCodexHome);
   const existingSavedRoots = toPathArray(state["electron-saved-workspace-roots"]);
   const existingProjectOrder = toPathArray(state["project-order"]);
   const existingActiveRoots = toPathArray(state["active-workspace-roots"]);
diff --git a/test/config-file.test.js b/test/config-file.test.js
index 937ece2..663eb70 100644
--- a/test/config-file.test.js
+++ b/test/config-file.test.js
@@ -7,10 +7,29 @@ import {
   readCurrentProviderFromConfigText,
   readProviderModel,
   readRootModelFromConfigText,
+  readSqliteHomeFromConfigText,
   setRootModelInConfigText,
   setRootProviderInConfigText
 } from "../src/config-file.js";
 
+test("readSqliteHomeFromConfigText reads root basic and literal strings", () => {
+  assert.equal(
+    readSqliteHomeFromConfigText('sqlite_home = "C:\\\\Users\\\\Example\\\\.codex\\\\sqlite"\n'),
+    "C:\\Users\\Example\\.codex\\sqlite"
+  );
+  assert.equal(
+    readSqliteHomeFromConfigText("sqlite_home = '\\\\wsl.localhost\\Ubuntu\\home\\user\\.codex\\sqlite'\n"),
+    "\\\\wsl.localhost\\Ubuntu\\home\\user\\.codex\\sqlite"
+  );
+});
+
+test("readSqliteHomeFromConfigText ignores provider-section values", () => {
+  assert.equal(
+    readSqliteHomeFromConfigText('[model_providers.custom]\nsqlite_home = "/wrong"\n'),
+    null
+  );
+});
+
 test("readCurrentProviderFromConfigText falls back to implicit openai", () => {
   const input = `
 # comment
diff --git a/test/launcher.test.js b/test/launcher.test.js
index 46c2d7d..e6b31e7 100644
--- a/test/launcher.test.js
+++ b/test/launcher.test.js
@@ -29,3 +29,15 @@ test("installWindowsLauncher creates cmd and vbs launchers", async () => {
   assert.match(vbsText, /Codex Provider Sync/);
   assert.match(vbsText, /codex-provider sync --codex-home ""C:\\Users\\Example User\\.codex""/);
 });
+
+test("installWindowsLauncher preserves an explicit UNC SQLite home", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "codex-provider-launcher-"));
+  const sqliteHome = "\\\\wsl.localhost\\Ubuntu\\home\\user\\.codex\\sqlite";
+
+  const result = await installWindowsLauncher({ dir, sqliteHome });
+  const cmdText = await fs.readFile(result.cmdPath, "utf8");
+  const vbsText = await fs.readFile(result.vbsPath, "utf8");
+
+  assert.match(cmdText, /--sqlite-home "\\\\wsl\.localhost\\Ubuntu\\home\\user\\\.codex\\sqlite"/);
+  assert.match(vbsText, /--sqlite-home ""\\\\wsl\.localhost\\Ubuntu\\home\\user\\\.codex\\sqlite""/);
+});
diff --git a/test/storage-layout.test.js b/test/storage-layout.test.js
new file mode 100644
index 0000000..2cca0e4
--- /dev/null
+++ b/test/storage-layout.test.js
@@ -0,0 +1,96 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+
+import { resolveStorageLayout } from "../src/storage-layout.js";
+
+const cwd = path.resolve("/work");
+const codexHome = path.resolve("/codex-home");
+
+test("resolveStorageLayout applies override, config, environment, and default precedence", () => {
+  const explicit = resolveStorageLayout({
+    codexHome,
+    sqliteHome: "explicit-db",
+    configText: 'sqlite_home = "config-db"',
+    env: { CODEX_SQLITE_HOME: "env-db" },
+    cwd
+  });
+  assert.equal(explicit.sqliteHome, path.resolve(cwd, "explicit-db"));
+  assert.equal(explicit.sqliteHomeSource, "cli");
+
+  const configured = resolveStorageLayout({
+    codexHome,
+    configText: "sqlite_home = 'config-db'",
+    env: { CODEX_SQLITE_HOME: "env-db" },
+    cwd
+  });
+  assert.equal(configured.sqliteHome, path.resolve(cwd, "config-db"));
+  assert.equal(configured.sqliteHomeSource, "config");
+
+  const environment = resolveStorageLayout({
+    codexHome,
+    env: { CODEX_SQLITE_HOME: "env-db" },
+    cwd
+  });
+  assert.equal(environment.sqliteHome, path.resolve(cwd, "env-db"));
+  assert.equal(environment.sqliteHomeSource, "env");
+
+  const fallback = resolveStorageLayout({ codexHome, env: {}, cwd });
+  assert.equal(fallback.sqliteHome, path.join(codexHome, "sqlite"));
+  assert.equal(fallback.sqliteHomeSource, "default");
+});
+
+test("resolveStorageLayout only enables legacy root fallback for the default layout", () => {
+  const fallback = resolveStorageLayout({ codexHome, env: {}, cwd });
+  assert.deepEqual(
+    fallback.stateDbCandidates.map((candidate) => candidate.path),
+    [path.join(codexHome, "sqlite", "state_5.sqlite"), path.join(codexHome, "state_5.sqlite")]
+  );
+
+  const explicit = resolveStorageLayout({ codexHome, sqliteHome: "/external", env: {}, cwd });
+  assert.deepEqual(
+    explicit.stateDbCandidates.map((candidate) => candidate.path),
+    [path.resolve("/external", "state_5.sqlite")]
+  );
+  assert.equal(explicit.allowLegacyRootFallback, false);
+});
+
+test("resolveStorageLayout blocks Windows processes from accessing WSL UNC SQLite homes", () => {
+  for (const sqliteHome of [
+    "\\\\wsl.localhost\\Ubuntu\\home\\user\\.codex\\sqlite",
+    "\\\\WSL$\\Ubuntu\\home\\user\\.codex\\sqlite",
+    "\\\\?\\UNC\\wsl.localhost\\Ubuntu\\home\\user\\.codex\\sqlite"
+  ]) {
+    const layout = resolveStorageLayout({
+      codexHome,
+      sqliteHome,
+      env: {},
+      cwd,
+      platform: "win32"
+    });
+
+    assert.equal(layout.sqliteAccess.supported, false);
+    assert.equal(layout.sqliteAccess.reason, "windows-wsl-unc");
+    assert.match(layout.sqliteAccess.message, /Run codex-provider inside WSL/);
+  }
+});
+
+test("resolveStorageLayout allows WSL paths outside a Windows process", () => {
+  const wslUncOnLinux = resolveStorageLayout({
+    codexHome,
+    sqliteHome: "\\\\wsl.localhost\\Ubuntu\\home\\user\\.codex\\sqlite",
+    env: {},
+    cwd,
+    platform: "linux"
+  });
+  const linuxPath = resolveStorageLayout({
+    codexHome,
+    sqliteHome: "/home/user/.codex/sqlite",
+    env: {},
+    cwd,
+    platform: "linux"
+  });
+
+  assert.equal(wslUncOnLinux.sqliteAccess.supported, true);
+  assert.equal(linuxPath.sqliteAccess.supported, true);
+});
diff --git a/test/sync-service.test.js b/test/sync-service.test.js
index 1c8932c..f509d42 100644
--- a/test/sync-service.test.js
+++ b/test/sync-service.test.js
@@ -18,6 +18,8 @@ import { getUnsupportedNodeVersionMessage } from "../src/node-version.js";
 import { applySessionChanges, collectSessionChanges } from "../src/session-files.js";
 import { openDatabase } from "../src/sqlite.js";
 
+delete process.env.CODEX_SQLITE_HOME;
+
 async function makeTempCodexHome() {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "codex-provider-sync-"));
   const codexHome = path.join(root, ".codex");
@@ -331,6 +333,9 @@ test("runSync rewrites rollout files and sqlite, then restore reverts both", asy
   assert.deepEqual(syncResult.skippedLockedRolloutFiles, []);
   assert.equal(syncResult.sqliteRowsUpdated, 2);
   const backupMetadata = JSON.parse(await fs.readFile(path.join(syncResult.backupDir, "metadata.json"), "utf8"));
+  assert.equal(backupMetadata.version, 2);
+  assert.equal(backupMetadata.sqliteHome, path.join(codexHome, SQLITE_DIR_BASENAME));
+  assert.deepEqual(backupMetadata.sqliteDbFiles, [DB_FILE_BASENAME]);
   assert.deepEqual(
     backupMetadata.dbFiles.map((fileName) => fileName.replaceAll("\\", "/")),
     ["sqlite/state_5.sqlite"]
@@ -382,6 +387,9 @@ test("runSync updates legacy root sqlite database when sqlite-dir state is stale
 
   assert.equal(syncResult.sqliteRowsUpdated, 2);
   const backupMetadata = JSON.parse(await fs.readFile(path.join(syncResult.backupDir, "metadata.json"), "utf8"));
+  assert.equal(backupMetadata.version, 2);
+  assert.equal(backupMetadata.sqliteHome, codexHome);
+  assert.deepEqual(backupMetadata.sqliteDbFiles, [DB_FILE_BASENAME]);
   assert.deepEqual(backupMetadata.dbFiles, [DB_FILE_BASENAME]);
 
   const legacyDb = await openDatabase(legacyStateDbPath(codexHome));
@@ -410,6 +418,281 @@ test("runSync updates legacy root sqlite database when sqlite-dir state is stale
   }
 });
 
+test("runSync uses an explicit SQLite home and never touches a stale Codex Home database", async () => {
+  const { root, codexHome } = await makeTempCodexHome();
+  await writeConfig(codexHome, 'model_provider = "openai"');
+  const sessionPath = path.join(codexHome, "sessions", "2026", "03", "19", "rollout-external.jsonl");
+  await writeRollout(sessionPath, "thread-external", "custom");
+
+  const sqliteHome = path.join(root, "external-sqlite");
+  const externalDbPath = path.join(sqliteHome, DB_FILE_BASENAME);
+  await writeStateDbAt(externalDbPath, [
+    { id: "thread-external", model_provider: "custom", archived: false }
+  ]);
+  await writeStateDb(codexHome, [
+    { id: "thread-stale", model_provider: "stale", archived: false }
+  ]);
+
+  const result = await runSync({ codexHome, sqliteHome });
+  assert.equal(result.sqliteHome, sqliteHome);
+  assert.equal(result.sqliteHomeSource, "cli");
+
+  const externalDb = await openDatabase(externalDbPath);
+  try {
+    assert.equal(
+      externalDb.prepare("SELECT model_provider FROM threads WHERE id = ?").get("thread-external").model_provider,
+      "openai"
+    );
+  } finally {
+    externalDb.close();
+  }
+
+  const staleDb = await openDatabase(stateDbPath(codexHome));
+  try {
+    assert.equal(
+      staleDb.prepare("SELECT model_provider FROM threads WHERE id = ?").get("thread-stale").model_provider,
+      "stale"
+    );
+  } finally {
+    staleDb.close();
+  }
+
+  const metadata = JSON.parse(await fs.readFile(path.join(result.backupDir, "metadata.json"), "utf8"));
+  assert.equal(metadata.version, 2);
+  assert.equal(metadata.sqliteHome, sqliteHome);
+  assert.deepEqual(metadata.dbFiles, []);
+  assert.deepEqual(metadata.sqliteDbFiles, [DB_FILE_BASENAME]);
+  await fs.access(path.join(result.backupDir, "db", "sqlite-home", DB_FILE_BASENAME));
+
+  await runRestore({ codexHome, sqliteHome, backupDir: result.backupDir });
+  const restoredDb = await openDatabase(externalDbPath);
+  try {
+    assert.equal(
+      restoredDb.prepare("SELECT model_provider FROM threads WHERE id = ?").get("thread-external").model_provider,
+      "custom"
+    );
+  } finally {
+    restoredDb.close();
+  }
+});
+
+test("runSync blocks Windows WSL UNC SQLite homes before creating a backup", async () => {
+  const { root, codexHome } = await makeTempCodexHome();
+  await writeConfig(codexHome, 'model_provider = "openai"');
+  const configPath = path.join(codexHome, "config.toml");
+  const originalConfig = await fs.readFile(configPath, "utf8");
+
+  try {
+    await assert.rejects(
+      () => runSync({
+        codexHome,
+        sqliteHome: "\\\\wsl.localhost\\Ubuntu\\home\\user\\.codex\\sqlite",
+        platform: "win32"
+      }),
+      /Cannot sync.*Run codex-provider inside WSL/
+    );
+    assert.equal(await fs.readFile(configPath, "utf8"), originalConfig);
+    await assert.rejects(() => fs.access(backupRoot(codexHome)));
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("configured SQLite home reports a missing database and blocks writes without fallback", async () => {
+  const { root, codexHome } = await makeTempCodexHome();
+  const sqliteHome = path.join(root, "missing-sqlite");
+  await fs.writeFile(
+    path.join(codexHome, "config.toml"),
+    `model_provider = "openai"\nsqlite_home = '${sqliteHome}'\n`,
+    "utf8"
+  );
+  await writeStateDb(codexHome, [
+    { id: "thread-stale", model_provider: "custom", archived: false }
+  ]);
+
+  const status = await getStatus({ codexHome });
+  assert.equal(status.sqliteHome, sqliteHome);
+  assert.equal(status.sqliteHomeSource, "config");
+  assert.equal(status.stateDbLocation, null);
+  assert.match(renderStatus(status), /database: not found/);
+  assert.match(renderStatus(status), new RegExp(sqliteHome.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&")));
+
+  await assert.rejects(
+    () => runSync({ codexHome }),
+    /not found in configured SQLite home/
+  );
+});
+
+test("v2 restore rejects SQLite home relocation unless explicitly allowed", async () => {
+  const { root, codexHome } = await makeTempCodexHome();
+  await writeConfig(codexHome, 'model_provider = "openai"');
+  const sessionPath = path.join(codexHome, "sessions", "2026", "03", "19", "rollout-relocation.jsonl");
+  await writeRollout(sessionPath, "thread-relocation", "custom");
+
+  const sourceSqliteHome = path.join(root, "source-sqlite");
+  const targetSqliteHome = path.join(root, "target-sqlite");
+  await writeStateDbAt(path.join(sourceSqliteHome, DB_FILE_BASENAME), [
+    { id: "thread-relocation", model_provider: "custom", archived: false }
+  ]);
+  await writeStateDbAt(path.join(targetSqliteHome, DB_FILE_BASENAME), [
+    { id: "thread-relocation", model_provider: "openai", archived: false }
+  ]);
+
+  const syncResult = await runSync({ codexHome, sqliteHome: sourceSqliteHome });
+  await assert.rejects(
+    () => runRestore({ codexHome, sqliteHome: targetSqliteHome, backupDir: syncResult.backupDir }),
+    /Use --allow-sqlite-home-relocation/
+  );
+  await assert.rejects(
+    () => runRestore({ codexHome, backupDir: syncResult.backupDir, allowSqliteHomeRelocation: true }),
+    /requires an explicit --sqlite-home/
+  );
+  await assert.rejects(
+    () => runRestore({
+      codexHome,
+      sqliteHome: targetSqliteHome,
+      backupDir: syncResult.backupDir,
+      allowSqliteHomeRelocation: true
+    }),
+    /Cannot restore config\.toml while relocating SQLite home/
+  );
+
+  await runRestore({
+    codexHome,
+    sqliteHome: targetSqliteHome,
+    backupDir: syncResult.backupDir,
+    restoreConfig: false,
+    allowSqliteHomeRelocation: true
+  });
+  const targetDb = await openDatabase(path.join(targetSqliteHome, DB_FILE_BASENAME));
+  try {
+    assert.equal(
+      targetDb.prepare("SELECT model_provider FROM threads WHERE id = ?").get("thread-relocation").model_provider,
+      "custom"
+    );
+  } finally {
+    targetDb.close();
+  }
+});
+
+test("v2 restore rebuilds a missing default SQLite database", async () => {
+  const { codexHome } = await makeTempCodexHome();
+  await writeConfig(codexHome, 'model_provider = "openai"');
+  await writeStateDb(codexHome, [
+    { id: "thread-missing-default", model_provider: "custom", archived: false }
+  ]);
+
+  const syncResult = await runSync({ codexHome });
+  await fs.rm(stateDbPath(codexHome));
+
+  await runRestore({
+    codexHome,
+    backupDir: syncResult.backupDir,
+    restoreConfig: false,
+    restoreSessions: false
+  });
+
+  const restoredDb = await openDatabase(stateDbPath(codexHome));
+  try {
+    assert.equal(
+      restoredDb.prepare("SELECT model_provider FROM threads WHERE id = ?").get("thread-missing-default").model_provider,
+      "custom"
+    );
+  } finally {
+    restoredDb.close();
+  }
+});
+
+test("v2 restore rebuilds a missing legacy root SQLite database in place", async () => {
+  const { codexHome } = await makeTempCodexHome();
+  await writeConfig(codexHome, 'model_provider = "openai"');
+  await writeLegacyStateDb(codexHome, [
+    { id: "thread-missing-legacy", model_provider: "custom", archived: false }
+  ]);
+
+  const syncResult = await runSync({ codexHome });
+  await fs.rm(legacyStateDbPath(codexHome));
+
+  await runRestore({
+    codexHome,
+    backupDir: syncResult.backupDir,
+    restoreConfig: false,
+    restoreSessions: false
+  });
+
+  await assert.rejects(() => fs.access(stateDbPath(codexHome)));
+  const restoredDb = await openDatabase(legacyStateDbPath(codexHome));
+  try {
+    assert.equal(
+      restoredDb.prepare("SELECT model_provider FROM threads WHERE id = ?").get("thread-missing-legacy").model_provider,
+      "custom"
+    );
+  } finally {
+    restoredDb.close();
+  }
+});
+
+test("restoreBackup keeps metadata v1 database paths compatible", async () => {
+  const { codexHome } = await makeTempCodexHome();
+  await writeConfig(codexHome, 'model_provider = "openai"');
+  await writeStateDb(codexHome, [
+    { id: "thread-v1", model_provider: "openai", archived: false }
+  ]);
+
+  const backupDir = path.join(backupRoot(codexHome), "v1-restore");
+  const backupDbPath = path.join(backupDir, "db", SQLITE_DIR_BASENAME, DB_FILE_BASENAME);
+  await writeStateDbAt(backupDbPath, [
+    { id: "thread-v1", model_provider: "custom", archived: false }
+  ]);
+  await fs.writeFile(
+    path.join(backupDir, "metadata.json"),
+    JSON.stringify({
+      version: 1,
+      namespace: "provider-sync",
+      codexHome,
+      targetProvider: "custom",
+      createdAt: "2026-03-24T00:00:00.000Z",
+      dbFiles: [path.join(SQLITE_DIR_BASENAME, DB_FILE_BASENAME)],
+      changedSessionFiles: 0
+    }),
+    "utf8"
+  );
+  await fs.rm(stateDbPath(codexHome));
+
+  await restoreBackup(backupDir, codexHome, {
+    restoreConfig: false,
+    restoreSessions: false
+  });
+
+  const restoredDb = await openDatabase(stateDbPath(codexHome));
+  try {
+    assert.equal(
+      restoredDb.prepare("SELECT model_provider FROM threads WHERE id = ?").get("thread-v1").model_provider,
+      "custom"
+    );
+  } finally {
+    restoredDb.close();
+  }
+});
+
+test("restore validates v2 SQLite files before restoring config", async () => {
+  const { codexHome } = await makeTempCodexHome();
+  await writeConfig(codexHome, 'model_provider = "openai"');
+  await writeStateDb(codexHome, [
+    { id: "thread-restore-validation", model_provider: "custom", archived: false }
+  ]);
+  const syncResult = await runSync({ codexHome });
+  await fs.rm(path.join(syncResult.backupDir, "db", "sqlite-home", DB_FILE_BASENAME));
+
+  const currentConfig = 'model_provider = "sentinel"\n';
+  await fs.writeFile(path.join(codexHome, "config.toml"), currentConfig, "utf8");
+  await assert.rejects(
+    () => runRestore({ codexHome, backupDir: syncResult.backupDir }),
+    /declares a missing SQLite file/
+  );
+  assert.equal(await fs.readFile(path.join(codexHome, "config.toml"), "utf8"), currentConfig);
+});
+
 test("runSync reports stage progress and backup duration", async () => {
   const { codexHome } = await makeTempCodexHome();
   await writeConfig(codexHome, 'model_provider = "openai"');
@@ -1099,7 +1382,7 @@ test("runSync restores turn_context model on failure rollback (no half-completed
   // session_meta, the per-turn model must return to "gpt-5",
   // and the appended user_message must be left alone (the
   // restore pass is append-tolerant).
-  await restoreBackup(backupDir, codexHome, { restoreSessions: true });
+  await restoreBackup(backupDir, codexHome, { restoreDatabase: false, restoreSessions: true });
 
   const restored = await fs.readFile(sessionPath, "utf8");
   const restoredLines = restored.split("\n").filter(Boolean);
@@ -1199,6 +1482,28 @@ test("status reports implicit default provider and rollout/sqlite counts", async
   assert.match(renderStatus(status), new RegExp(`database: ${stateDbPath(codexHome).replace(/[\\^$.*+?()[\]{}|]/g, "\\$&")}`));
 });
 
+test("status reports Windows WSL UNC SQLite homes without opening the database", async () => {
+  const { root, codexHome } = await makeTempCodexHome();
+  await writeConfig(codexHome, 'model_provider = "openai"');
+
+  try {
+    const status = await getStatus({
+      codexHome,
+      sqliteHome: "\\\\wsl.localhost\\Ubuntu\\home\\user\\.codex\\sqlite",
+      platform: "win32"
+    });
+    const rendered = renderStatus(status);
+
+    assert.equal(status.sqliteAccess.supported, false);
+    assert.equal(status.stateDbLocation, null);
+    assert.equal(status.sqliteCounts, null);
+    assert.match(rendered, /Windows cannot safely access SQLite through the WSL UNC path/);
+    assert.doesNotMatch(rendered, /currently in use/i);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
 test("status falls back to legacy root sqlite database", async () => {
   const { codexHome } = await makeTempCodexHome();
   await writeConfig(codexHome);
@@ -1337,6 +1642,48 @@ test("runSwitch rejects unknown custom providers", async () => {
   );
 });
 
+test("runSwitch blocks Windows WSL UNC SQLite homes before updating config", async () => {
+  const { root, codexHome } = await makeTempCodexHome();
+  await writeConfig(codexHome, 'model_provider = "openai"');
+  const configPath = path.join(codexHome, "config.toml");
+  const originalConfig = await fs.readFile(configPath, "utf8");
+
+  try {
+    await assert.rejects(
+      () => runSwitch({
+        codexHome,
+        sqliteHome: "\\\\wsl$\\Ubuntu\\home\\user\\.codex\\sqlite",
+        provider: "apigather",
+        platform: "win32"
+      }),
+      /Cannot switch.*Run codex-provider inside WSL/
+    );
+    assert.equal(await fs.readFile(configPath, "utf8"), originalConfig);
+    await assert.rejects(() => fs.access(backupRoot(codexHome)));
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("runRestore blocks Windows WSL UNC SQLite homes before reading the backup", async () => {
+  const { root, codexHome } = await makeTempCodexHome();
+  await writeConfig(codexHome, 'model_provider = "openai"');
+
+  try {
+    await assert.rejects(
+      () => runRestore({
+        codexHome,
+        sqliteHome: "\\\\wsl.localhost\\Ubuntu\\home\\user\\.codex\\sqlite",
+        backupDir: path.join(root, "missing-backup"),
+        platform: "win32"
+      }),
+      /Cannot restore.*Run codex-provider inside WSL/
+    );
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
 test("runSync leaves rollout files and sqlite untouched when sqlite is locked", async () => {
   const { codexHome } = await makeTempCodexHome();
   await writeConfig(codexHome, 'model_provider = "openai"');
diff --git a/test/watch.test.js b/test/watch.test.js
index 96e51fb..0ec9ec5 100644
--- a/test/watch.test.js
+++ b/test/watch.test.js
@@ -6,8 +6,12 @@ import path from "node:path";
 
 import { runWatch } from "../src/watch.js";
 
+delete process.env.CODEX_SQLITE_HOME;
+
+const testTempDir = process.platform === "win32" ? os.tmpdir() : "/tmp";
+
 async function makeTempCodexHome() {
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "codex-provider-sync-watch-"));
+  const root = await fs.mkdtemp(path.join(testTempDir, "codex-provider-sync-watch-"));
   const codexHome = path.join(root, ".codex");
   await fs.mkdir(path.join(codexHome, "sqlite"), { recursive: true });
   await fs.writeFile(
@@ -30,6 +34,17 @@ function deferred() {
   return { promise, resolve, reject };
 }
 
+async function waitUntil(predicate, message, timeoutMs = 3000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (predicate()) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error(message);
+}
+
 test("runWatch rejects invalid debounce-ms values", async () => {
   const { codexHome } = await makeTempCodexHome();
   await assert.rejects(
@@ -40,7 +55,7 @@ test("runWatch rejects invalid debounce-ms values", async () => {
 });
 
 test("runWatch rejects when codex home or config.toml is missing", async () => {
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "codex-provider-sync-watch-"));
+  const root = await fs.mkdtemp(path.join(testTempDir, "codex-provider-sync-watch-"));
   await assert.rejects(
     () => runWatch({ codexHome: path.join(root, "does-not-exist") }),
     /Codex home not found/
@@ -54,6 +69,26 @@ test("runWatch rejects when codex home or config.toml is missing", async () => {
   await fs.rm(root, { recursive: true, force: true });
 });
 
+test("runWatch blocks Windows WSL UNC SQLite homes before creating watchers", async () => {
+  const { root, codexHome } = await makeTempCodexHome();
+  let handle;
+  try {
+    await assert.rejects(
+      async () => {
+        handle = await runWatch({
+          codexHome,
+          sqliteHome: "\\\\wsl.localhost\\Ubuntu\\home\\user\\.codex\\sqlite",
+          platform: "win32"
+        });
+      },
+      /Cannot watch.*Run codex-provider inside WSL/
+    );
+  } finally {
+    await handle?.stop();
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
 test("runWatch invokes the injected sync handler when config.toml changes and stops on --once", async () => {
   const { codexHome } = await makeTempCodexHome();
   const configPath = path.join(codexHome, "config.toml");
@@ -244,6 +279,68 @@ test("runWatch observes the active state database chosen by detectStateDb", asyn
   await fs.rm(codexHome, { recursive: true, force: true });
 });
 
+test("runWatch rebinds SQLite watchers after config changes and drops invalid homes", async () => {
+  const { root, codexHome } = await makeTempCodexHome();
+  const configPath = path.join(codexHome, "config.toml");
+  const originalDbPath = path.join(codexHome, "sqlite", "state_5.sqlite");
+  const sqliteHomeA = path.join(root, "sqlite-a");
+  const sqliteHomeB = path.join(root, "sqlite-b");
+  const dbPathA = path.join(sqliteHomeA, "state_5.sqlite");
+  const dbPathB = path.join(sqliteHomeB, "state_5.sqlite");
+  await fs.mkdir(sqliteHomeA, { recursive: true });
+  await fs.mkdir(sqliteHomeB, { recursive: true });
+  await fs.writeFile(dbPathA, "", "utf8");
+  await fs.writeFile(dbPathB, "", "utf8");
+
+  const syncCalls = [];
+  const handle = await runWatch({
+    codexHome,
+    debounceMs: 30,
+    includeStateDb: true,
+    onSync: async ({ reason, sqliteHome }) => {
+      syncCalls.push({ reason, sqliteHome });
+      return { targetProvider: "openai", changedSessionFiles: 0, sqliteRowsUpdated: 0 };
+    }
+  });
+
+  await fs.writeFile(
+    configPath,
+    `model_provider = "openai"\nsqlite_home = '${sqliteHomeA}'\n`,
+    "utf8"
+  );
+  await waitUntil(() => handle.watchedStateDbPath === dbPathA, "watcher did not bind SQLite home A");
+  const beforeA = syncCalls.length;
+  await fs.appendFile(dbPathA, "a", "utf8");
+  await waitUntil(() => syncCalls.length > beforeA, "watcher did not observe SQLite home A");
+
+  const missingSqliteHome = path.join(root, "missing-sqlite");
+  await fs.writeFile(
+    configPath,
+    `model_provider = "openai"\nsqlite_home = '${missingSqliteHome}'\n`,
+    "utf8"
+  );
+  await waitUntil(() => handle.watchedStateDbPath === null, "watcher did not drop the invalid SQLite home");
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  const beforeOldDbWrite = syncCalls.length;
+  await fs.appendFile(dbPathA, "stale", "utf8");
+  await fs.appendFile(originalDbPath, "stale", "utf8");
+  await new Promise((resolve) => setTimeout(resolve, 250));
+  assert.equal(syncCalls.length, beforeOldDbWrite, "invalid layout must leave only the config watcher active");
+
+  await fs.writeFile(
+    configPath,
+    `model_provider = "openai"\nsqlite_home = '${sqliteHomeB}'\n`,
+    "utf8"
+  );
+  await waitUntil(() => handle.watchedStateDbPath === dbPathB, "watcher did not bind SQLite home B");
+  const beforeB = syncCalls.length;
+  await fs.appendFile(dbPathB, "b", "utf8");
+  await waitUntil(() => syncCalls.length > beforeB, "watcher did not observe SQLite home B");
+
+  await handle.stop();
+  await fs.rm(root, { recursive: true, force: true });
+});
+
 test("runWatch reacts to writes in the SQLite WAL sidecar", async () => {
   // Regression guard for owner review: when Codex runs against a
   // SQLite database in WAL journal mode (the default), new
@@ -316,7 +413,7 @@ test("runWatch uses the top-level model field, ignoring provider sections", asyn
   // inside a `[model_providers.*]` section — otherwise the
   // provider-section model would be propagated to every
   // rollout's turn_context.model.
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "codex-provider-sync-watch-"));
+  const root = await fs.mkdtemp(path.join(testTempDir, "codex-provider-sync-watch-"));
   const codexHome = path.join(root, ".codex");
   await fs.mkdir(path.join(codexHome, "sqlite"), { recursive: true });
   await fs.writeFile(