main.cpp

// acecode-desktop: WebView 壳 + 共享 daemon(所有 workspace/session 复用一个 daemon)。
//
// 启动流程:
//   1. 扫 .acecode/projects/*  → WorkspaceRegistry
//   2. 读 state.json::last_active_workspace_hash
//   3. pick_active 决定首屏 workspace
//   4. 注册 webview JS bridge: aceDesktop_listWorkspaces / activateWorkspace /
//      renameWorkspace / addWorkspace
//   5. 若 active workspace 存在 → DaemonPool::activate → 拼 URL → navigate
//      若不存在 → 仍启动 shared daemon 只用于承载前端,sidebar 渲染为空列表 + "+ 添加项目"
//   6. WebHost.run() 阻塞直到窗口关闭
//   7. quit: pool.shutdown_all() 按用户策略 stop/release + 写 last_active
//
// daemon 端通过 workspace-aware API 在同一进程内服务多个 workspace。

#include "daemon_pool.hpp"
#include "agent_browser_host.hpp"
#include "agent_browser_runtime.hpp"
#include "context_items.hpp"
#include "context_picker.hpp"
#include "desktop_about.hpp"
#include "desktop_restart.hpp"
#include "dpi_win.hpp"
#include "edge_app_launcher.hpp"
#include "external_url.hpp"
#include "folder_picker.hpp"
#include "locale.hpp"
#include "notifications.hpp"
#include "open_request.hpp"
#include "open_in_explorer.hpp"
#include "pick_active.hpp"
#include "single_instance.hpp"
#include "splash_screen.hpp"
#include "startup_progress.hpp"
#include "strings.hpp"
#include "tray_menu_bridge.hpp"
#include "tray_icon_win.hpp"
#include "url_builder.hpp"
#include "web_host.hpp"
#include "web_host_close_policy.hpp"
#include "workspace_registry.hpp"

#include "../config/config.hpp"
#include "../daemon/platform.hpp"
#include "../daemon/runtime_files.hpp"
#include "../utils/clipboard.hpp"
#include "../utils/base64.hpp"
#include "../utils/cwd_hash.hpp"
#include "../utils/encoding.hpp"
#include "../utils/logger.hpp"
#include "../utils/state_file.hpp"
#include "../utils/utf8_path.hpp"
#include "../utils/uuid.hpp"
#include "version.hpp"

#include <nlohmann/json.hpp>

#include <algorithm>
#include <atomic>
#include <cstdlib>
#include <filesystem>
#include <functional>
#include <memory>
#include <mutex>
#include <optional>
#include <random>
#include <sstream>
#include <string>
#include <thread>
#include <vector>

#include <cpr/cpr.h>
#ifdef _WIN32
#  ifndef WIN32_LEAN_AND_MEAN
#    define WIN32_LEAN_AND_MEAN
#  endif
#  ifndef NOMINMAX
#    define NOMINMAX
#  endif
#  include <windows.h>
#  include <shellapi.h>
#endif
#ifdef __APPLE__
#  include <mach-o/dyld.h>
#endif

namespace fs = std::filesystem;

namespace {

constexpr const char* kSharedDaemonSlotHash = "__shared_daemon__";
constexpr const char* kSharedDaemonContextId = "default";
constexpr const char* kDesktopCloseRequestEvent =
    "acecode:desktop-close-requested";

nlohmann::json agent_browser_state_json(
    const acecode::desktop::AgentBrowserState& state) {
    nlohmann::json result{
        {"supported", state.supported},
        {"ready", state.ready},
        {"loading", state.loading},
        {"visible", state.visible},
        {"active", state.active},
        {"closed", state.closed},
        {"can_go_back", state.can_go_back},
        {"can_go_forward", state.can_go_forward},
        {"shared_with_agent", state.shared_with_agent},
        {"element_selection_active", state.element_selection_active},
        {"element_selection_serial", state.element_selection_serial},
        {"url", state.url},
        {"title", state.title},
        {"favicon", state.favicon},
        {"content_state", state.content_state},
        {"failure_kind", state.failure_kind},
        {"error", state.error},
        {"diagnostic", state.diagnostic},
        {"page_id", state.page_id},
    };
    if (!state.selected_element_json.empty()) {
        const auto selected = nlohmann::json::parse(
            state.selected_element_json, nullptr, false);
        if (!selected.is_discarded()) result["selected_element"] = selected;
    }
    return result;
}

nlohmann::json context_item_json(const acecode::desktop::ContextItem& item) {
    nlohmann::json value{
        {"kind", item.kind == acecode::desktop::ContextItemKind::Folder
            ? "folder" : "file"},
        {"path", item.path},
        {"name", item.name},
    };
    if (item.kind == acecode::desktop::ContextItemKind::File) {
        value["mime_type"] = item.mime_type;
        value["size_bytes"] = item.size_bytes;
        if (item.reference_only) {
            value["reference_only"] = true;
        } else {
            value["data_base64"] = acecode::base64_encode(item.bytes);
        }
    }
    return value;
}

nlohmann::json context_items_json(const std::vector<std::string>& paths) {
    auto materialized = acecode::desktop::materialize_context_items(paths);
    if (!materialized) {
        return nlohmann::json{{"ok", false}, {"error", materialized.error}};
    }

    nlohmann::json items = nlohmann::json::array();
    for (const auto& item : materialized.items) {
        items.push_back(context_item_json(item));
    }
    return nlohmann::json{{"ok", true}, {"items", std::move(items)}};
}

struct ContextPickerFolderReference {
    std::string path;
    std::optional<std::string> relative_path;
};

std::optional<ContextPickerFolderReference> context_picker_folder_reference(
    const std::string& cwd,
    const std::string& selected_path,
    std::string& error) {
    if (selected_path.empty()) {
        error = "selected folder is unavailable";
        return std::nullopt;
    }
    std::error_code ec;
    const fs::path selected = fs::weakly_canonical(
        acecode::path_from_utf8(selected_path), ec);
    if (ec || !fs::is_directory(selected, ec) || ec) {
        error = "selected folder is unavailable";
        return std::nullopt;
    }

    ContextPickerFolderReference result{
        acecode::path_to_utf8_generic(selected), std::nullopt};
    if (!cwd.empty()) {
        ec.clear();
        const fs::path root = fs::weakly_canonical(acecode::path_from_utf8(cwd), ec);
        if (!ec) {
            if (selected == root) {
                result.relative_path = std::string{};
            } else {
                const fs::path relative = selected.lexically_relative(root);
                bool inside = !relative.empty() && !relative.is_absolute();
                for (const auto& part : relative) {
                    if (part == "..") {
                        inside = false;
                        break;
                    }
                }
                if (inside) {
                    result.relative_path = acecode::path_to_utf8_generic(relative);
                }
            }
        }
    }
    return result;
}

bool is_webapp_arg(const std::string& arg) {
    return arg == "--webapp";
}

bool desktop_webapp_requested(const std::vector<std::string>& argv) {
    for (std::size_t index = argv.empty() ? 0 : 1;
         index < argv.size();
         ++index) {
        if (is_webapp_arg(argv[index])) return true;
    }
    return false;
}

#ifdef _WIN32
std::vector<std::string> desktop_process_arguments() {
    int argc = 0;
    LPWSTR* argv = ::CommandLineToArgvW(::GetCommandLineW(), &argc);
    if (!argv) return {};

    std::vector<std::string> result;
    result.reserve(static_cast<std::size_t>((std::max)(argc, 0)));
    for (int index = 0; index < argc; ++index) {
        result.push_back(acecode::wide_to_utf8(argv[index]));
    }
    ::LocalFree(argv);
    return result;
}

std::string desktop_exe_dir() {
    wchar_t buf[MAX_PATH] = {0};
    DWORD n = ::GetModuleFileNameW(nullptr, buf, MAX_PATH);
    if (n == 0 || n == MAX_PATH) return "";
    std::wstring wpath(buf, n);
    return acecode::wide_to_utf8(fs::path(wpath).parent_path().wstring());
}
#elif defined(__APPLE__)
std::vector<std::string> desktop_process_arguments(int argc, char** argv) {
    std::vector<std::string> result;
    result.reserve(static_cast<std::size_t>((std::max)(argc, 0)));
    for (int index = 0; index < argc; ++index) {
        result.emplace_back(argv[index] ? argv[index] : "");
    }
    return result;
}

std::string desktop_exe_dir() {
    uint32_t size = 1024;
    std::vector<char> buf(size);
    if (_NSGetExecutablePath(buf.data(), &size) != 0) {
        buf.assign(static_cast<size_t>(size) + 1, '\0');
        if (_NSGetExecutablePath(buf.data(), &size) != 0) return "";
    }

    fs::path exe(buf.data());
    std::error_code ec;
    fs::path resolved = fs::weakly_canonical(exe, ec);
    if (ec) {
        ec.clear();
        resolved = fs::absolute(exe, ec);
        if (ec) resolved = exe;
    }
    return acecode::path_to_utf8(resolved.parent_path());
}
#else
std::vector<std::string> desktop_process_arguments(int argc, char** argv) {
    std::vector<std::string> result;
    result.reserve(static_cast<std::size_t>((std::max)(argc, 0)));
    for (int index = 0; index < argc; ++index) {
        result.emplace_back(argv[index] ? argv[index] : "");
    }
    return result;
}

std::string desktop_exe_dir() {
    std::error_code ec;
    auto p = fs::current_path(ec);
    if (ec) return "";
    return acecode::path_to_utf8(p);
}
#endif

#ifdef _WIN32
void show_error(const std::string& msg) {
    std::wstring w = acecode::utf8_to_wide(msg);
    const std::wstring title = acecode::utf8_to_wide(std::string(
        acecode::desktop::native_string(
            acecode::desktop::DesktopStringId::StartupFailedTitle)));
    ::MessageBoxW(nullptr, w.c_str(), title.c_str(), MB_ICONERROR | MB_OK);
}
#endif

fs::path path_from_utf8(const std::string& path) {
    return acecode::path_from_utf8(path);
}

std::string path_to_utf8(const fs::path& path) {
    return acecode::path_to_utf8(path);
}

std::string append_query_param(const std::string& url,
                               const std::string& key,
                               const std::string& value) {
    if (url.empty() || url == "about:blank") return url;
    const char separator = url.find('?') == std::string::npos ? '?' : '&';
    return url + separator +
           acecode::desktop::percent_encode(key) + "=" +
           acecode::desktop::percent_encode(value);
}

std::string locate_daemon_exe() {
    auto dir = desktop_exe_dir();
    if (dir.empty()) return "";
#ifdef _WIN32
    std::vector<const char*> candidates{"acecode.exe"};
#elif defined(__APPLE__)
    std::vector<const char*> candidates{"acecode-daemon", "acecode"};
#else
    std::vector<const char*> candidates{"acecode"};
#endif
    for (const char* name : candidates) {
        fs::path p = path_from_utf8(dir) / name;
        if (fs::exists(p)) return path_to_utf8(p);
    }
    return "";
}

// dev 模式: 探到仓库 web/dist/ (Vite build 产物) → 让 daemon 走
// FileSystemAssetSource,`pnpm build` 后 F5 即生效,无需重 build acecode。
//
// **必须是 web/dist/ 不是 web/** — web/ 是 Vite 源码(index.html 里写
// <script src="/src/main.jsx">),daemon 不会 transpile JSX,加载会挂。
//
// 探测顺序:
//   1. 环境变量 ACECODE_DEV_WEB_DIR(显式指定绝对路径,信用户判断)
//   2. 自动猜:从 desktop exe 向上找 "web/dist/index.html"
//      Windows: build/Release/acecode-desktop.exe → ../../web/dist
//      macOS: build/ACECode.app/Contents/MacOS/ACECode → ../../../../web/dist
// 找不到返回空字符串 → daemon 走 embedded(cmake 已把 web/dist 嵌进二进制)。
std::string detect_dev_web_dir() {
    std::string env = acecode::getenv_utf8("ACECODE_DEV_WEB_DIR");
    if (!env.empty()) {
        fs::path p = path_from_utf8(env) / "index.html";
        if (fs::exists(p)) return env;
    }
    auto dir = desktop_exe_dir();
    if (dir.empty()) return "";
    fs::path cur = path_from_utf8(dir);
    for (int i = 0; i < 8; ++i) {
        fs::path candidate = cur / "web" / "dist";
        if (fs::exists(candidate / "index.html")) return path_to_utf8(candidate);
        if (!cur.has_parent_path()) break;
        cur = cur.parent_path();
    }
    return "";
}

std::string projects_dir() {
    return path_to_utf8(path_from_utf8(acecode::get_acecode_dir()) / "projects");
}

std::string desktop_shared_run_dir() {
    return path_to_utf8(path_from_utf8(acecode::get_acecode_dir()) / "run" / "desktop-shared");
}

std::string current_cwd() {
    std::error_code ec;
    auto p = fs::current_path(ec);
    if (ec) return "";
    return path_to_utf8(p);
}

bool is_existing_directory(const std::string& path) {
    if (path.empty()) return false;
#ifdef _WIN32
    std::wstring wide = acecode::utf8_to_wide(path);
    if (wide.empty()) return false;
    DWORD attrs = ::GetFileAttributesW(wide.c_str());
    return attrs != INVALID_FILE_ATTRIBUTES && (attrs & FILE_ATTRIBUTE_DIRECTORY) != 0;
#else
    std::error_code ec;
    return fs::is_directory(path, ec) && !ec;
#endif
}

std::string daemon_exe_parent_dir(const std::string& daemon_exe) {
    if (daemon_exe.empty()) return "";
    fs::path p = path_from_utf8(daemon_exe).parent_path();
    if (p.empty()) return "";
    return path_to_utf8(p);
}

std::string choose_launch_cwd(const std::string& preferred,
                              const std::string& proc_cwd,
                              const std::string& daemon_exe) {
    if (is_existing_directory(preferred)) return preferred;
    if (is_existing_directory(proc_cwd)) return proc_cwd;
    std::string exe_dir = daemon_exe_parent_dir(daemon_exe);
    if (is_existing_directory(exe_dir)) return exe_dir;
    return "";
}

void log_legacy_workspace_run_dirs(const std::string& proj_dir) {
    std::error_code ec;
    fs::path native_proj_dir = path_from_utf8(proj_dir);
    if (!fs::is_directory(native_proj_dir, ec) || ec) return;
    int count = 0;
    for (const auto& project_entry : fs::directory_iterator(native_proj_dir, ec)) {
        if (ec) break;
        if (!project_entry.is_directory(ec) || ec) continue;
        fs::path run_dir = project_entry.path() / "run";
        if (!fs::is_directory(run_dir, ec) || ec) continue;
        for (const auto& run_entry : fs::directory_iterator(run_dir, ec)) {
            if (ec) break;
            if (!run_entry.is_directory(ec) || ec) continue;
            ++count;
            if (count <= 8) {
                LOG_WARN("[desktop] legacy workspace run dir ignored by shared daemon: " +
                         path_to_utf8(run_entry.path()));
            }
        }
    }
    if (count > 8) {
        LOG_WARN("[desktop] legacy workspace run dirs ignored by shared daemon: " +
                 std::to_string(count) + " total");
    }
}

// JSON 工具:把 daemon_state 枚举转成前端用的字符串
const char* state_string(acecode::desktop::DaemonState s) {
    switch (s) {
        case acecode::desktop::DaemonState::Stopped:  return "stopped";
        case acecode::desktop::DaemonState::Starting: return "starting";
        case acecode::desktop::DaemonState::Running:  return "running";
        case acecode::desktop::DaemonState::Failed:   return "failed";
    }
    return "stopped";
}

// onboarding fallback:正常情况下即使 registry 为空也会启动 shared daemon 来
// 承载前端。只有 daemon 启动失败时才落到 about:blank。
const char* onboarding_url() { return "about:blank"; }

bool is_desktop_debug_mode() {
#ifndef NDEBUG
    return true;
#else
    return false;
#endif
}

std::string short_random_hex() {
    static constexpr char kHex[] = "0123456789abcdef";
    std::random_device rd;
    std::mt19937 gen(rd());
    std::uniform_int_distribution<int> dist(0, 15);
    std::string out;
    out.reserve(8);
    for (int i = 0; i < 8; ++i) out.push_back(kHex[dist(gen)]);
    return out;
}

bool post_resume_to_daemon(int port, const std::string& token,
                           const std::string& session_id,
                           const std::string& workspace_hash,
                           std::string& error) {
    std::string path = workspace_hash.empty()
        ? "/api/sessions/" + session_id + "/resume"
        : "/api/workspaces/" + workspace_hash + "/sessions/" + session_id + "/resume";
    auto r = cpr::Post(
        cpr::Url{"http://127.0.0.1:" + std::to_string(port) + path},
        cpr::Header{{"X-ACECode-Token", token},
                    {"Content-Type", "application/json"}},
        cpr::Body{"{}"},
        cpr::Timeout{5000});
    if (r.status_code >= 200 && r.status_code < 300) return true;
    std::ostringstream oss;
    oss << "resume endpoint failed status=" << r.status_code;
    if (!r.text.empty()) oss << " body=" << r.text;
    if (r.error.code != cpr::ErrorCode::OK) oss << " error=" << r.error.message;
    error = oss.str();
    return false;
}

bool post_workspace_to_daemon(int port, const std::string& token,
                              const std::string& cwd,
                              std::string& error) {
    auto r = cpr::Post(
        cpr::Url{"http://127.0.0.1:" + std::to_string(port) + "/api/workspaces"},
        cpr::Header{{"X-ACECode-Token", token},
                    {"Content-Type", "application/json"}},
        cpr::Body{nlohmann::json{{"cwd", cwd}}.dump()},
        cpr::Timeout{5000});
    if (r.status_code >= 200 && r.status_code < 300) return true;
    std::ostringstream oss;
    oss << "workspace endpoint failed status=" << r.status_code;
    if (!r.text.empty()) oss << " body=" << r.text;
    if (r.error.code != cpr::ErrorCode::OK) oss << " error=" << r.error.message;
    error = oss.str();
    return false;
}

#ifdef _WIN32
// 在指定进程的可见顶层窗口里挑一个拉到前台(best-effort)。Edge --app + 干净
// profile 下,我们启动的 msedge 就是浏览器进程、拥有 app 窗口,按 pid 能找到。
struct FindWindowByPidCtx {
    DWORD pid = 0;
    HWND found = nullptr;
};

BOOL CALLBACK find_window_by_pid_cb(HWND hwnd, LPARAM lparam) {
    auto* ctx = reinterpret_cast<FindWindowByPidCtx*>(lparam);
    DWORD wpid = 0;
    ::GetWindowThreadProcessId(hwnd, &wpid);
    if (wpid == ctx->pid && ::IsWindowVisible(hwnd) &&
        ::GetWindow(hwnd, GW_OWNER) == nullptr) {
        ctx->found = hwnd;
        return FALSE; // 找到一个顶层可见窗口就停
    }
    return TRUE;
}

void focus_process_main_window(unsigned long pid) {
    if (pid == 0) return;
    FindWindowByPidCtx ctx;
    ctx.pid = static_cast<DWORD>(pid);
    ::EnumWindows(find_window_by_pid_cb, reinterpret_cast<LPARAM>(&ctx));
    if (!ctx.found) return;
    if (::IsIconic(ctx.found)) ::ShowWindow(ctx.found, SW_RESTORE);
    ::SetForegroundWindow(ctx.found);
}
#endif

// 浏览器兜底宿主:embedded WebView2 用不了时(运行时损坏/缺失/被策略封锁),用
// 外部浏览器显示 daemon 的 Web UI,并由 desktop 进程在后台托住 daemon。
//
// 关键设计(修白屏 + daemon 被提前杀):
//   - 不再用 WaitForSingleObject(msedge) 当生命周期 —— Chromium 的 single-instance
//     转交会让被等的进程瞬间退出,导致 daemon 被误杀 → Edge 窗口连不上 → 白屏。
//   - 改为:启动浏览器(Edge --app 优先,失败再退到系统默认浏览器),然后跑一个带
//     托盘图标的 Win32 消息循环托住进程;daemon 全程存活。
//   - Edge --app(有可靠进程句柄 + 干净 profile)额外挂一个 watcher:app 窗口关闭
//     → 进程退出 → 请求退出循环,保持"关窗即退出"的直觉。
//   - 默认浏览器那条(拿不到可靠句柄)只能靠托盘"退出"。
int run_browser_fallback(const std::string& url,
                         acecode::desktop::SplashScreen& splash,
                         acecode::desktop::DaemonPool& pool,
                         const std::string& reason,
                         const std::string& webview_error) {
    using namespace acecode::desktop;
    LOG_WARN("[desktop] starting browser fallback mode: " + reason);

    // daemon 没起来 → 没有可显示的 URL,浏览器也救不了,直接报清楚的错。
    if (url.empty() || url == onboarding_url()) {
        LOG_ERROR("[desktop] browser fallback has no daemon URL to show "
                  "(daemon failed to start)");
        splash.close();
#ifdef _WIN32
        show_error(format_browser_fallback_no_daemon_message(
            reason, webview_error, native_locale()));
#endif
        auto failures = pool.stop_all();
        return failures.empty() ? 1 : 100;
    }

    const std::string browser_url = append_query_param(url, "ace_webapp", "1");

#ifdef _WIN32
    // 1) 启动浏览器:Edge --app 优先(拿到进程句柄),失败退到默认浏览器。
    void* edge_process = nullptr;
    unsigned long edge_pid = 0;
    bool opened = false;
    std::string launch_detail;

    auto edge = launch_edge_app(browser_url);
    if (edge.ok) {
        edge_process = edge.process;
        edge_pid = edge.pid;
        opened = true;
    } else {
        launch_detail = "Edge app mode: " + edge.error;
        LOG_WARN("[desktop] Edge app mode unavailable, trying default browser: " + edge.error);
        auto ext = acecode::desktop::open_external_url(browser_url);
        if (ext.ok) {
            opened = true;
            LOG_INFO("[desktop] opened daemon UI in default browser");
        } else {
            launch_detail += " | default browser: " + ext.error;
        }
    }

    splash.close();

    if (!opened) {
        LOG_ERROR("[desktop] browser fallback failed to open any browser: " + launch_detail);
        show_error(format_browser_fallback_open_failed_message(
            reason, launch_detail, webview_error, native_locale()));
        if (edge_process) ::CloseHandle(static_cast<HANDLE>(edge_process));
        auto failures = pool.stop_all();
        return failures.empty() ? 1 : 100;
    }

    // 2) 托盘 + 消息循环托住 daemon 生命周期。
    const DWORD main_tid = ::GetCurrentThreadId();
    std::atomic<bool> quit_requested{false};
    auto request_quit = [&quit_requested, main_tid]() {
        quit_requested.store(true);
        ::PostThreadMessageW(main_tid, WM_NULL, 0, 0); // 唤醒阻塞中的 GetMessage
    };

    void* tray_hwnd = nullptr;
    bool tray_ok = init_tray_icon(
        /*on_show=*/[edge_pid]() {
            if (edge_pid) focus_process_main_window(edge_pid);
        },
        /*on_quit=*/[&request_quit]() { request_quit(); },
        &tray_hwnd);
    if (!tray_ok) {
        LOG_WARN("[desktop] tray icon unavailable in browser fallback; "
                 "window close still quits for Edge app mode");
    }

    // 3) Edge --app:app 窗口关闭(进程退出)→ 请求退出。stop_event 让 watcher 可被
    //    join(否则 WaitForMultipleObjects 无法取消)。
    // 只有 edge_process 和 stop_event 都有效才起 watcher —— 这样 watcher 总能被
    // stop_event 唤醒后 join,不会在退出时因 WaitForSingleObject 无法取消而卡死。
    HANDLE stop_event = ::CreateEventW(nullptr, TRUE, FALSE, nullptr);
    const bool can_autoquit_on_close = (edge_process != nullptr) && (stop_event != nullptr);
    std::thread watcher;
    if (can_autoquit_on_close) {
        watcher = std::thread([edge_process, stop_event, &request_quit]() {
            HANDLE waits[2] = {static_cast<HANDLE>(edge_process), stop_event};
            ::WaitForMultipleObjects(2, waits, FALSE, INFINITE);
            request_quit();
        });
    }

    if (!tray_ok && !can_autoquit_on_close) {
        // 托盘装不上 + 无法在窗口关闭时自动退出 → 没有任何主动退出途径。日志点明,
        // 避免静默"卡住"难诊断;daemon 会随 desktop 进程被杀而随之退出。
        LOG_ERROR("[desktop] browser fallback has neither tray nor a process handle "
                  "to quit on; close the desktop process to stop the daemon");
    }

    // 4) 消息循环
    MSG msg;
    while (!quit_requested.load()) {
        BOOL got = ::GetMessageW(&msg, nullptr, 0, 0);
        if (got == 0 || got == -1) break; // WM_QUIT / 错误
        ::TranslateMessage(&msg);
        ::DispatchMessageW(&msg);
    }

    // 5) teardown:先放 watcher,再清托盘,最后停 daemon。
    if (stop_event) ::SetEvent(stop_event);
    if (watcher.joinable()) watcher.join();
    if (stop_event) ::CloseHandle(stop_event);
    if (edge_process) ::CloseHandle(static_cast<HANDLE>(edge_process));
    shutdown_tray_icon();

    auto failures = pool.shutdown_all();
    return failures.empty() ? 0 : 100;
#else
    // 非 Windows:desktop 用 WebKitGTK,几乎不会走到这里。best-effort 开默认浏览器
    // 后收尾(无托盘宿主)。
    (void)webview_error;
    auto ext = acecode::desktop::open_external_url(browser_url);
    splash.close();
    if (!ext.ok) {
        LOG_ERROR("[desktop] browser fallback failed to open default browser: " + ext.error);
    }
    auto failures = pool.shutdown_all();
    return failures.empty() ? (ext.ok ? 0 : 1) : 100;
#endif
}

} // namespace

#ifdef _WIN32
int WINAPI wWinMain(HINSTANCE, HINSTANCE, PWSTR, int) {
    const auto process_arguments = desktop_process_arguments();
#else
int main(int argc, char** argv) {
    const auto process_arguments = desktop_process_arguments(argc, argv);
#endif
    const bool force_webapp = desktop_webapp_requested(process_arguments);
    const auto startup_open_parse =
        acecode::desktop::parse_desktop_open_request_arguments(
            process_arguments);
    // 顶层 try/catch:wWinMain 是 Windows 子系统的 EXE 入口,任何未捕获的
    // C++ 异常会触发 std::terminate → 系统弹"未经处理的异常"调试器对话框,
    // 普通用户既看不懂也无从下手。把整个 body 包成 IIFE lambda 让 catch 兜
    // 底:落 LOG_ERROR、弹中文 MessageBox 给用户可执行的修复指引,然后
    // return 1 走正常退出。
    //
    // 注意 logger 初始化也在 lambda 内,因为它本身也可能抛(磁盘满 / 路径
    // 受 GPO 锁)。catch 里依然先调 LOG_ERROR(失败时是 no-op,不影响
    // MessageBox 给用户提示)。
    auto run = [
        force_webapp,
        startup_open_request = startup_open_parse.request,
        startup_open_request_error = startup_open_parse.error
    ]() -> int {
    using namespace acecode::desktop;

    // desktop 自己的日志路径: ~/.acecode/logs/desktop-<date>.log。和 daemon
    // 日志(daemon-<date>.log)同目录便于一次 tail。mirror_stderr=false 因为
    // WIN32 子系统下 stderr 是 invalid handle。
    acecode::Logger::instance().init_with_rotation(acecode::get_logs_dir(), "desktop", false);
    acecode::Logger::instance().set_level(acecode::LogLevel::Dbg);
    LOG_INFO("[desktop] starting acecode-desktop");
    DesktopStartupTimeline startup_timeline;
    const std::string desktop_system_locale =
        acecode::desktop::detect_system_locale_tag();
    std::string startup_locale = acecode::desktop::resolve_ui_locale(
        acecode::desktop::kLocalePreferenceAuto, desktop_system_locale);
    WebHost* startup_progress_host = nullptr;
    bool startup_navigation_started = false;
    bool startup_splash_open = false;
    if (!startup_open_request_error.empty()) {
        LOG_WARN("[desktop] ignored invalid open request: " +
                 startup_open_request_error);
    }
    const fs::path desktop_restart_target = current_desktop_executable_path();
    if (desktop_restart_target.empty()) {
        LOG_WARN("[desktop] could not resolve installed executable path; automatic restart will be unavailable");
    }
    if (force_webapp) {
        LOG_INFO("[desktop] --webapp requested; embedded WebView will be skipped");
    }
#ifdef _WIN32
    LOG_INFO(std::string("[desktop] DPI awareness ") +
             (acecode::desktop::enable_desktop_dpi_awareness() ? "enabled" : "not enabled"));
#endif

    const std::int64_t desktop_instance_started_at_ms =
        acecode::daemon::now_unix_ms();

    // 单例锁:per-user。已有实例时把对方拉前 + 自己 exit(0),避免多份 desktop /
    // 多份 daemon 子进程同时存在。设计见 src/desktop/single_instance.hpp。
    SingleInstance singleton;
    if (!singleton.try_acquire()) {
        if (startup_open_request.has_value()) {
            std::string handoff_error;
            if (!publish_pending_desktop_open_request(
                    *startup_open_request, &handoff_error)) {
                LOG_WARN("[desktop] failed to publish open request to existing "
                         "instance: " + handoff_error);
            }
        }
        LOG_INFO("[desktop] another acecode-desktop instance is running, focusing it");
        focus_existing_instance(); // POSIX 端是 stub,返回 false 也只是 exit
        return 0;
    }

    const std::int64_t desktop_owner_pid =
        acecode::daemon::current_pid();
    const std::string desktop_owner_instance = acecode::generate_uuid();
    const std::string shared_run_dir = desktop_shared_run_dir();
    if (!acecode::daemon::write_desktop_owner_record(
            shared_run_dir,
            acecode::daemon::DesktopOwnerRecord{
                desktop_owner_pid,
                desktop_owner_instance,
                acecode::daemon::now_unix_ms(),
            })) {
        LOG_WARN("[desktop] failed to publish Desktop owner record");
    }

    SplashScreen splash;
    auto publish_startup_snapshot = [&]() {
        if (!startup_progress_host || !startup_navigation_started) return;
        const std::string snapshot = startup_timeline.snapshot_json();
        startup_progress_host->eval(
            "(function(snapshot){try{"
            "window.__ACECODE_DESKTOP_STARTUP__=snapshot;"
            "window.dispatchEvent(new CustomEvent(" +
            nlohmann::json(kDesktopStartupProgressEvent).dump() +
            ",{detail:snapshot}));"
            "}catch(e){}})(" + snapshot + ");");
    };
    auto mark_startup = [&](const std::string& stage,
                            const std::string& source = "native",
                            std::optional<double> frontend_ms = std::nullopt) {
        const auto event = startup_timeline.record(
            stage,
            desktop_startup_stage_message(stage, startup_locale),
            source,
            is_terminal_startup_stage(stage),
            frontend_ms);
        std::string log =
            "[startup] stage=" + event.stage +
            " sequence=" + std::to_string(event.sequence) +
            " source=" + event.source +
            " elapsed_ms=" + std::to_string(event.elapsed_ms);
        if (event.frontend_ms.has_value()) {
            std::ostringstream value;
            value << *event.frontend_ms;
            log += " frontend_ms=" + value.str();
        }
        LOG_INFO(log);
        if (startup_splash_open) {
            splash.set_status(event.message, event.elapsed_ms);
        }
        publish_startup_snapshot();
        return event;
    };
    startup_splash_open = true;
    mark_startup("desktop_starting");
    splash.show();

    // 加载 desktop 端用到的 config(窗口关闭行为、通知、后台进程等)。
    // 失败回退默认 AppConfig — 不阻断启动,与 daemon 一致;只是 close-to-tray
    // 默认值仍生效。Daemon 子进程会自己再次 load_config,所以 Desktop 这次读
    // 不会污染或覆盖 daemon 端配置。
    acecode::AppConfig desktop_cfg;
    std::mutex desktop_config_mu;
    mark_startup("config_load_begin");
    try {
        desktop_cfg = acecode::load_config();
    } catch (const std::exception& e) {
        LOG_WARN(std::string("[desktop] load_config failed, using defaults: ") + e.what());
    }
    std::string desktop_effective_locale = acecode::desktop::resolve_ui_locale(
        desktop_cfg.ui.locale, desktop_system_locale);
    startup_locale = desktop_effective_locale;
    acecode::desktop::set_native_locale(desktop_effective_locale);
    LOG_INFO("[desktop] GUI locale preference=" + desktop_cfg.ui.locale +
              " effective=" + desktop_effective_locale);
    mark_startup("config_load_end");

    std::string daemon_exe = locate_daemon_exe();
    if (daemon_exe.empty()) {
        splash.close();
#ifdef _WIN32
        show_error(format_daemon_missing_message(native_locale()));
#endif
        return 1;
    }

    // dev 模式探测 — 找到 web/ 后所有 spawn 出来的 daemon 都拿这个 static_dir
    std::string dev_web_dir = detect_dev_web_dir();
    if (!dev_web_dir.empty()) {
        LOG_INFO("[desktop] dev mode: serving web/ from " + dev_web_dir +
                 " (file changes hot-reload on F5)");
    }

    std::string proj_dir = projects_dir();
    std::error_code ec;
    fs::create_directories(proj_dir, ec); // 首次启动时不存在

    // 1. 扫已有 workspace
    mark_startup("workspace_scan_begin");
    WorkspaceRegistry registry;
    registry.scan(proj_dir);
    log_legacy_workspace_run_dirs(proj_dir);
    mark_startup("workspace_scan_end");

    // 2. 决定 active workspace
    std::string last_active = acecode::read_last_active_workspace_hash();
    std::string proc_cwd = current_cwd();
    std::optional<WorkspaceMeta> startup_open_workspace;
    if (startup_open_request.has_value()) {
        if (!is_existing_directory(startup_open_request->cwd)) {
            LOG_WARN("[desktop] requested TUI workspace is unavailable: " +
                     startup_open_request->cwd);
        } else {
            startup_open_workspace =
                registry.register_new(proj_dir, startup_open_request->cwd);
            LOG_INFO("[desktop] registered requested TUI workspace hash=" +
                     startup_open_workspace->hash + " cwd=" +
                     startup_open_workspace->cwd);
        }
    }
    std::string active_hash = startup_open_workspace.has_value()
        ? startup_open_workspace->hash
        : pick_active(last_active, proc_cwd, registry);

    if (!active_hash.empty()) {
        auto active_meta = registry.get(active_hash);
        if (active_meta && !is_existing_directory(active_meta->cwd)) {
            LOG_WARN("[desktop] active workspace cwd unavailable, falling back: hash=" +
                     active_meta->hash + " cwd=" + active_meta->cwd);
            active_hash.clear();
            for (const auto& candidate : registry.list()) {
                if (is_existing_directory(candidate.cwd)) {
                    active_hash = candidate.hash;
                    LOG_INFO("[desktop] selected fallback workspace hash=" + active_hash +
                             " cwd=" + candidate.cwd);
                    break;
                }
            }
        }
    }

    // 没有任何显式可见 workspace 时保持 onboarding。不要把 process cwd 自动
    // 注册进 Desktop,否则首次打开会重新暴露 TUI 里用过的历史目录。

    // 3. pool 准备 + 提前 activate daemon(在创建窗口前)
    //
    // 启动闪屏修复:webview 库在自建窗口路径里会硬编码 ShowWindow(SW_SHOW)
    // + 默认 640×480。这里改走 WebHost 自建父窗口路径,先在屏幕外渲染。
    //
    // 当前做法:
    //   a) 把 daemon activate 提到 WebHost 构造之前 — 窗口出现时 URL 就绪
    //   b) WebView2 parent 不 hide,只是在屏幕外可见,避免 hidden controller
    //      暂停渲染,同时用户只能看到透明 icon。
    DaemonPool pool;
    pool.set_keep_alive_on_exit(
        desktop_cfg.desktop.continue_background_process);
    auto configure_managed_request =
        [&](ActivateRequest& request) {
            request.run_dir = shared_run_dir;
            request.desktop_managed = true;
            request.desktop_owner_pid = desktop_owner_pid;
            request.desktop_owner_instance = desktop_owner_instance;
        };
    std::mutex active_mu;
    std::string active_hash_dynamic = active_hash; // 后续切 workspace 时更新

    std::string url = onboarding_url();
    const bool daemon_activation_attempted =
        !active_hash.empty() || !proc_cwd.empty();
    bool daemon_activation_recorded = false;
    if (daemon_activation_attempted) {
        mark_startup("daemon_activate_begin");
    }
    if (!active_hash.empty()) {
        auto m = registry.get(active_hash);
        if (m) {
            const bool workspace_available = is_existing_directory(m->cwd);
            std::string launch_cwd = choose_launch_cwd(m->cwd, proc_cwd, daemon_exe);
            if (launch_cwd.empty()) {
                LOG_ERROR("[desktop] no usable cwd available to start daemon");
            } else if (!workspace_available) {
                LOG_WARN("[desktop] starting shared daemon from fallback cwd=" + launch_cwd +
                         " because workspace cwd is unavailable: " + m->cwd);
            }

            ActivateRequest req;
            req.hash = kSharedDaemonSlotHash;
            req.cwd = launch_cwd;
            req.daemon_exe_path = daemon_exe;
            req.static_dir = dev_web_dir;
            req.context_id = kSharedDaemonContextId;
            configure_managed_request(req);
            req.native_folder_picker_enabled = true;
            ActivateResult r;
            if (launch_cwd.empty()) {
                r.error = "no usable working directory for daemon";
            } else {
                r = pool.activate(req);
            }
            if (r.ok) {
                daemon_activation_recorded = true;
                mark_startup("daemon_activate_end");
                std::string werr;
                if (workspace_available) {
                    mark_startup("workspace_register_begin");
                    if (!post_workspace_to_daemon(r.port, r.token, m->cwd, werr)) {
                        LOG_ERROR("[desktop] post_workspace failed during startup: " + werr);
                        mark_startup("workspace_register_failed");
                    } else {
                        mark_startup("workspace_register_end");
                    }
                }
                url = build_loopback_url(r.port, r.token);
            } else {
                daemon_activation_recorded = true;
                mark_startup("daemon_activate_failed");
#ifdef _WIN32
                show_error(format_daemon_workspace_failed_message(
                    m->name, r.error, native_locale()));
#endif
                // 不致命退出 — 仍打开 onboarding,用户可重试 / 切其它 workspace
            }
        }
    } else if (!proc_cwd.empty()) {
        // 没有显式可见 workspace 时仍要启动 shared daemon 来 serve Web UI。
        // 关键点:这里只启动 daemon,不 POST /api/workspaces,也不 register_new。
        // daemon worker 的 ensure_workspace_metadata 会写 desktop_visible=false,
        // 所以前端拿到的 workspace 列表仍为空,只显示"添加项目"入口。
        std::string launch_cwd = choose_launch_cwd(proc_cwd, proc_cwd, daemon_exe);
        ActivateRequest req;
        req.hash = kSharedDaemonSlotHash;
        req.cwd = launch_cwd;
        req.daemon_exe_path = daemon_exe;
        req.static_dir = dev_web_dir;
        req.context_id = kSharedDaemonContextId;
        configure_managed_request(req);
        req.native_folder_picker_enabled = true;
        ActivateResult r;
        if (launch_cwd.empty()) {
            r.error = "no usable working directory for daemon";
        } else {
            r = pool.activate(req);
        }
        if (r.ok) {
            daemon_activation_recorded = true;
            mark_startup("daemon_activate_end");
            url = build_loopback_url(r.port, r.token);
        } else {
            daemon_activation_recorded = true;
            mark_startup("daemon_activate_failed");
            LOG_ERROR("[desktop] failed to start onboarding daemon: " + r.error);
        }
    }
    if (daemon_activation_attempted && !daemon_activation_recorded) {
        mark_startup("daemon_activate_failed");
    }

    if (startup_open_workspace.has_value() &&
        startup_open_request.has_value() &&
        url != onboarding_url()) {
        url = append_query_param(
            url, "open", startup_open_request->session_id);
        url = append_query_param(
            url, "workspace", startup_open_workspace->hash);
        url = append_query_param(url, "read_only", "1");
    }

    if (force_webapp) {
        return run_browser_fallback(url, splash, pool, "--webapp requested", "");
    }

    // 注意:这里不再用全屏 splash 盖主窗口。WebHost 会用自建 Win32
    // 父窗口在屏幕外保持可见状态完成 WebView2 渲染,页面 ready 后再移回
    // 当前屏幕中央。这样用户启动时只看到透明 icon,不会看到白屏。
    const bool desktop_debug = is_desktop_debug_mode();
    std::unique_ptr<WebHost> host_storage;
    mark_startup("webhost_create_begin");
    try {
        host_storage = std::make_unique<WebHost>(
            /*debug=*/desktop_debug,
            WebHost::StartupWindowMode::OffscreenUntilReady);
    } catch (const WebHostInitializationError& e) {
        mark_startup("webhost_create_failed");
        return run_browser_fallback(url, splash, pool, "embedded WebView unavailable", e.what());
    } catch (const std::exception& e) {
        mark_startup("webhost_create_failed");
#ifdef _WIN32
        LOG_WARN(std::string("[desktop] WebHost construction failed with unexpected exception; "
                             "entering Edge app mode: ") + e.what());
        return run_browser_fallback(url, splash, pool, "embedded WebView unavailable", e.what());
#else
        throw;
#endif
    } catch (...) {
        mark_startup("webhost_create_failed");
#ifdef _WIN32
        LOG_WARN("[desktop] WebHost construction failed with unknown exception; "
                 "entering Edge app mode");
        return run_browser_fallback(url, splash, pool, "embedded WebView unavailable", "unknown WebHost initialization error");
#else
        throw;
#endif
    }
    WebHost& host = *host_storage;
    startup_progress_host = &host;
    mark_startup("webhost_create_end");
    AgentBrowserHost agent_browser(
        host.native_window(),
        desktop_owner_pid,
        desktop_owner_instance,
        [&host](const AgentBrowserState& state) {
            host.eval(
                "(function(){try{window.dispatchEvent(new CustomEvent("
                "'acecode:agent-browser-state',{detail:" +
                agent_browser_state_json(state).dump() +
                "}));}catch(e){}})();");
        },
        [&host](std::function<void()> task) {
            host.dispatch(std::move(task));
        });
    std::atomic<bool> restart_requested{false};
    host.set_title("ACECode");
    host.set_size(kDefaultDesktopWindowWidth, kDefaultDesktopWindowHeight);

    // 系统托盘与 native 通知各自初始化。通知不再依赖 tray message HWND,
    // 因此托盘被策略禁用或创建失败时,会话完成提醒仍然可用。
    auto bring_window_foreground = [&host]() {
#ifdef _WIN32
        activate_notification_window(host.native_window());
#elif defined(__APPLE__)
        mac_bring_window_foreground(host.native_window());
#else
        (void)host;
#endif
    };

    std::atomic<bool> page_ready_notified{false};
    std::function<void()> consume_pending_open_request;
    bool tray_ok = init_tray_icon(
        /*on_show=*/[&bring_window_foreground]() { bring_window_foreground(); },
        /*on_quit=*/[&host]() {
            // 托盘 "退出" 必须绕过 close_request_handler(关窗 = 隐藏到托盘),
            // 否则等于点 ×,根本退不出去。走 request_quit 直接 DestroyWindow。
            host.request_quit();
        },
        nullptr);

    // Window close and application quit are separate lifecycle events. macOS
    // always hides the window and keeps the Dock/menu-bar restore paths alive.
    // Windows retains the configurable close-to-tray behavior.
#ifdef __APPLE__
    host.set_close_request_handler([&host]() {
        host.set_visible(false);
        return true;
    });
#elif defined(_WIN32)
    host.set_close_request_handler([
        &host,
        &desktop_cfg,
        &desktop_config_mu,
        &page_ready_notified,
        tray_ok
    ]() {
        acecode::DesktopCloseBehavior behavior;
        {
            std::lock_guard<std::mutex> lock(desktop_config_mu);
            behavior = desktop_cfg.desktop.close_behavior;
        }
        const auto action = acecode::desktop::resolve_close_request_action(
            behavior,
            tray_ok);
        if (action == acecode::desktop::CloseRequestAction::ExitApplication) {
            return false;
        }
        if (action == acecode::desktop::CloseRequestAction::HideToTray) {
            host.set_visible(false);
            return true;
        }
        if (!page_ready_notified.load()) {
            return false;
        }
        host.eval(std::string(
            "(function(){try{window.dispatchEvent(new Event('") +
            kDesktopCloseRequestEvent +
            "'));}catch(_){}})();");
        return true;
    });
#endif

    // 共享的 "focus session" lambda — native 通知 / tray 菜单 session 项 / 直接
    // bridge 调用都走同一份 JS 派发逻辑。
    auto focus_session = [&host, &active_mu, &active_hash_dynamic, &bring_window_foreground](
                              const std::string& workspace_hash,
                              const std::string& session_id,
                              bool read_only) {
        bring_window_foreground();
        std::string current_active;
        {
            std::lock_guard<std::mutex> lk(active_mu);
            current_active = active_hash_dynamic;
        }
        // 用 nlohmann::json 做字符串字面量转义,避免手拼 JS 时被 sid 里的引号
        // / 反斜杠 / 控制字符注入。
        std::string ws_lit = nlohmann::json(workspace_hash).dump();
        std::string sid_lit = nlohmann::json(session_id).dump();
        std::string js;
        const bool same_workspace = (workspace_hash.empty() ||
                                     workspace_hash == current_active);
        const std::string read_only_lit = read_only ? "true" : "false";
        if (same_workspace) {
            js = "(function(){try{if(window.aceDesktop_focusSessionFromBridge){"
                 "window.aceDesktop_focusSessionFromBridge(" + sid_lit + "," +
                 ws_lit + "," + read_only_lit + ");}"
                 "}catch(e){}})();";
        } else {
            js = "(function(){try{if(window.aceDesktop_activateAndOpenSession){"
                 "window.aceDesktop_activateAndOpenSession(" + ws_lit + "," +
                 sid_lit + "," + read_only_lit + ");}"
                 "}catch(e){}})();";
        }
        host.eval(js);
    };

    consume_pending_open_request =
        [
            &registry,
            &proj_dir,
            &focus_session,
            desktop_instance_started_at_ms
        ]() {
            std::string request_error;
            auto request =
                take_pending_desktop_open_request(
                    &request_error,
                    {},
                    desktop_instance_started_at_ms);
            if (!request_error.empty()) {
                LOG_WARN("[desktop] pending open request: " + request_error);
            }
            if (!request.has_value()) return;
            if (!is_existing_directory(request->cwd)) {
                LOG_WARN("[desktop] pending TUI workspace is unavailable: " +
                         request->cwd);
                return;
            }

            auto workspace = registry.register_new(proj_dir, request->cwd);
            LOG_INFO("[desktop] opening TUI-owned session " +
                     request->session_id + " in workspace " + workspace.hash);
            focus_session(
                workspace.hash, request->session_id, /*read_only=*/true);
        };
    host.set_existing_instance_focus_handler(
        [&page_ready_notified, &consume_pending_open_request]() {
            if (!page_ready_notified.load()) return;
            if (consume_pending_open_request) {
                consume_pending_open_request();
            }
        });

    auto notification_authorization_json =
        [](const NotificationAuthorizationState& state) {
            return nlohmann::json{
                {"ok", state.status !=
                    NotificationAuthorizationStatus::Unavailable},
                {"status",
                    notification_authorization_status_name(state.status)},
                {"can_request", state.can_request},
                {"can_open_settings", state.can_open_settings},
            };
        };

    // Keep native callbacks from outliving the WebHost or focus-session state
    // if any later Desktop setup/run step throws. Normal shutdown dismisses
    // this guard after performing the same cleanup explicitly.
    class NotificationShutdownGuard {
    public:
        ~NotificationShutdownGuard() {
            if (armed_) shutdown_notifications();
        }
        void dismiss() { armed_ = false; }

    private:
        bool armed_ = true;
    } notification_shutdown_guard;

    // Authorization callbacks may arrive on a UserNotifications worker queue.
    // WebHost::eval marshals the DOM event back onto the WebView loop.
    set_notification_authorization_handler(
        [&host, notification_authorization_json](
            const NotificationAuthorizationState& state) {
            const std::string detail =
                notification_authorization_json(state).dump();
            host.eval(
                "(function(){try{window.dispatchEvent(new CustomEvent("
                "'acecode:notification-authorization-changed',{detail:" +
                detail + "}));}catch(e){}})();");
        });

    // Native click handler 复用 focus_session。每条通知自带完整 payload,
    // 不会被后来显示的通知覆盖。
#if defined(_WIN32) || defined(__APPLE__)
    NotificationInitOptions notification_options;
    notification_options.app_name = "ACECode Desktop";
#ifdef _WIN32
    notification_options.application_id = "ACECode.ACECode.Desktop.1";
#endif
    notification_options.activation_window = host.native_window();
    const bool notifications_ok = init_notifications(notification_options);
    if (notifications_ok) {
        set_click_handler([focus_session](const NotifyPayload& payload) {
            focus_session(
                payload.workspace_hash, payload.session_id, /*read_only=*/false);
        });
    } else {
        LOG_WARN("[desktop] native notifications unavailable");
    }
#endif

    if (tray_ok) {

        // tray 菜单 session click 也走 focus_session。
        set_tray_session_click_handler(
            [focus_session](const std::string& workspace_hash, const std::string& session_id) {
                focus_session(
                    workspace_hash, session_id, /*read_only=*/false);
            });

        // tray 菜单 "新建会话":拉前 + 调前端钩子(没注册时安全 no-op)。
        set_tray_new_chat_handler([&host, &bring_window_foreground]() {
            bring_window_foreground();
            host.eval("(function(){try{if(window.aceDesktop_createNewSession)"
                      "window.aceDesktop_createNewSession();}catch(e){}})();");
        });

        // tray 菜单 "打开 ACECode":等价单击 tray 行为。
        set_tray_open_app_handler([&bring_window_foreground]() {
            bring_window_foreground();
        });
    } else {
        LOG_WARN("[desktop] tray icon unavailable");
    }

    auto close_splash_once = [&] {
        bool expected = false;
        if (!page_ready_notified.compare_exchange_strong(expected, true)) return;
        startup_splash_open = false;
        splash.close();
        host.set_visible(true);
    };

    // 前端首屏完成后关闭 Win32 透明 logo splash,再把屏幕外的主窗口移回前台。
    host.bind("aceDesktop_pageReady", [&](const std::string& /*req*/) -> std::string {
        mark_startup("dom_ready", "frontend");
        close_splash_once();
        if (consume_pending_open_request) {
            consume_pending_open_request();
        }
        return nlohmann::json{{"ok", true}}.dump();
    });

    host.bind("aceDesktop_reportStartupMilestone",
              [&](const std::string& req) -> std::string {
        std::string error;
        const auto milestone = parse_frontend_startup_milestone(req, &error);
        if (!milestone.has_value()) {
            LOG_WARN("[startup] rejected frontend milestone: " + error);
            return nlohmann::json{{"ok", false}, {"error", error}}.dump();
        }
        const auto event = mark_startup(
            milestone->stage, "frontend", milestone->performance_ms);
        return nlohmann::json{
            {"ok", true},
            {"sequence", event.sequence},
            {"elapsed_ms", event.elapsed_ms},
        }.dump();
    });

    host.bind("aceDesktop_getBackgroundProcessPreference",
              [&](const std::string& /*req*/) -> std::string {
        std::lock_guard<std::mutex> lock(desktop_config_mu);
        return nlohmann::json{
            {"ok", true},
            {"enabled",
             desktop_cfg.desktop.continue_background_process},
        }.dump();
    });

    // Runtime locale bridge intentionally updates only native in-memory state.
    // The authenticated daemon API is the sole config.json writer, preventing
    // Desktop and daemon from racing over unrelated config fields.
    host.bind("aceDesktop_applyLocale",
              [&](const std::string& req) -> std::string {
        try {
            const auto args = nlohmann::json::parse(req);
            if (!args.is_array() || args.empty() || !args[0].is_string()) {
                return nlohmann::json{
                    {"ok", false},
                    {"error", "expect [locale:string]"},
                }.dump();
            }
            const std::string preference = args[0].get<std::string>();
            if (!acecode::is_valid_ui_locale(preference)) {
                return nlohmann::json{
                    {"ok", false},
                    {"error", "invalid locale"},
                }.dump();
            }
            const std::string effective = acecode::desktop::resolve_ui_locale(
                preference, desktop_system_locale);
            {
                std::lock_guard<std::mutex> lock(desktop_config_mu);
                desktop_cfg.ui.locale = preference;
                desktop_effective_locale = effective;
            }
            acecode::desktop::set_native_locale(effective);
            return nlohmann::json{
                {"ok", true},
                {"preference", preference},
                {"locale", effective},
            }.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{
                {"ok", false},
                {"error", e.what()},
            }.dump();
        }
    });

    host.bind("aceDesktop_setBackgroundProcessPreference",
              [&](const std::string& req) -> std::string {
        bool enabled = false;
        try {
            const auto args = nlohmann::json::parse(req);
            if (!args.is_array() || args.empty() ||
                !args[0].is_boolean()) {
                return nlohmann::json{
                    {"ok", false},
                    {"error", "expect [enabled:boolean]"},
                }.dump();
            }
            enabled = args[0].get<bool>();

            // Reload-merge so daemon-side config writes made after Desktop
            // startup are not overwritten by this native preference update.
            acecode::AppConfig latest = acecode::load_config();
            latest.desktop.continue_background_process = enabled;
            const bool previous_keep_alive = pool.keep_alive_on_exit();
            pool.set_keep_alive_on_exit(enabled);
            try {
                acecode::save_config(latest);
            } catch (...) {
                pool.set_keep_alive_on_exit(previous_keep_alive);
                throw;
            }
            {
                std::lock_guard<std::mutex> lock(desktop_config_mu);
                desktop_cfg.desktop.continue_background_process = enabled;
            }
            return nlohmann::json{
                {"ok", true},
                {"enabled", enabled},
            }.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{
                {"ok", false},
                {"error", e.what()},
            }.dump();
        }
    });

    host.bind("aceDesktop_getCloseBehaviorPreference",
              [&](const std::string& /*req*/) -> std::string {
        std::lock_guard<std::mutex> lock(desktop_config_mu);
        return nlohmann::json{
            {"ok", true},
            {"behavior", std::string(acecode::desktop_close_behavior_value(
                desktop_cfg.desktop.close_behavior))},
            {"tray_available", tray_ok},
        }.dump();
    });

    host.bind("aceDesktop_setCloseBehaviorPreference",
              [&](const std::string& req) -> std::string {
        try {
            const auto args = nlohmann::json::parse(req);
            if (!args.is_array() || args.empty() || !args[0].is_string()) {
                return nlohmann::json{
                    {"ok", false},
                    {"error", "expect [behavior:string]"},
                }.dump();
            }
            const auto behavior = acecode::parse_desktop_close_behavior(
                args[0].get<std::string>());
            if (!behavior) {
                return nlohmann::json{
                    {"ok", false},
                    {"error", "invalid close behavior"},
                }.dump();
            }

            acecode::AppConfig latest = acecode::load_config();
            latest.desktop.close_behavior = *behavior;
            latest.desktop.close_to_tray =
                *behavior != acecode::DesktopCloseBehavior::Exit;
            acecode::save_config(latest);
            {
                std::lock_guard<std::mutex> lock(desktop_config_mu);
                desktop_cfg.desktop.close_behavior = *behavior;
                desktop_cfg.desktop.close_to_tray =
                    latest.desktop.close_to_tray;
            }
            return nlohmann::json{
                {"ok", true},
                {"behavior", std::string(
                    acecode::desktop_close_behavior_value(*behavior))},
                {"tray_available", tray_ok},
            }.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{
                {"ok", false},
                {"error", e.what()},
            }.dump();
        }
    });

    host.bind("aceDesktop_hideToTray", [&](const std::string& /*req*/) -> std::string {
        if (!tray_ok) {
            return nlohmann::json{
                {"ok", false},
                {"error", "system tray is unavailable"},
            }.dump();
        }
        host.set_visible(false);
        return nlohmann::json{{"ok", true}}.dump();
    });

    // Post-upgrade restart bridge. Preflight while the current UI is still alive
    // so a missing replacement leaves the success dialog open. The actual
    // process launch happens only after host.run() returns and all owned runtime
    // resources have been torn down.
    host.bind("aceDesktop_restartApp", [&](const std::string& /*req*/) -> std::string {
        if (restart_requested.load()) {
            return nlohmann::json{{"ok", true}}.dump();
        }
        const auto preflight = validate_desktop_restart_target(desktop_restart_target);
        if (!preflight.ok) {
            LOG_ERROR("[desktop] restart preflight failed: " + preflight.error);
            return nlohmann::json{{"ok", false}, {"error", preflight.error}}.dump();
        }
        restart_requested.store(true);
        LOG_INFO("[desktop] post-upgrade restart requested");
        host.request_quit();
        return nlohmann::json{{"ok", true}}.dump();
    });

    // bridge: 前端 console.error/warn + window.onerror + unhandledrejection 转发
    // 到 desktop 日志(~/.acecode/logs/desktop-<date>.log)。
    host.bind("aceDesktop_logFromWeb", [](const std::string& req) -> std::string {
        try {
            auto arr = nlohmann::json::parse(req);
            if (!arr.is_array() || arr.size() < 2) return "null";
            std::string level = arr[0].is_string() ? arr[0].get<std::string>() : "info";
            std::string msg   = arr[1].is_string() ? arr[1].get<std::string>() : arr[1].dump();
            std::string line  = "[web] " + msg;
            if (level == "error")        LOG_ERROR(line);
            else if (level == "warn")    LOG_WARN(line);
            else                         LOG_INFO(line);
        } catch (...) {
            // 不抛回前端,避免日志通道反过来污染前端 console
        }
        return "null";
    });

#if defined(_WIN32) || defined(__APPLE__)
    host.bind("aceDesktop_agentBrowserGetState",
              [&](const std::string& req) -> std::string {
        std::string page_id;
        const auto args = nlohmann::json::parse(req, nullptr, false);
        if (args.is_array() && !args.empty() && args[0].is_string()) {
            page_id = args[0].get<std::string>();
        }
        nlohmann::json result = agent_browser_state_json(
            agent_browser.state(page_id));
        result["ok"] = true;
        return result.dump();
    });

    host.bind("aceDesktop_agentBrowserCreatePage",
              [&](const std::string& /*req*/) -> std::string {
        std::string error;
        const std::string page_id = agent_browser.create_page(&error);
        if (page_id.empty()) {
            return nlohmann::json{{"ok", false}, {"error", error}}.dump();
        }
        nlohmann::json result = agent_browser_state_json(
            agent_browser.state(page_id));
        result["ok"] = true;
        return result.dump();
    });

    auto bind_agent_browser_page_lifecycle =
        [&](const char* name,
            const std::function<bool(const std::string&, std::string*)>& action) {
        host.bind(name, [action](const std::string& req) -> std::string {
            const auto args = nlohmann::json::parse(req, nullptr, false);
            if (!args.is_array() || args.empty() || !args[0].is_string()) {
                return nlohmann::json{
                    {"ok", false}, {"error", "expect [page_id:string]"}
                }.dump();
            }
            const std::string page_id = args[0].get<std::string>();
            std::string error;
            if (!action(page_id, &error)) {
                return nlohmann::json{{"ok", false}, {"error", error}}.dump();
            }
            return nlohmann::json{{"ok", true}, {"page_id", page_id}}.dump();
        });
    };
    bind_agent_browser_page_lifecycle(
        "aceDesktop_agentBrowserSelectPage",
        [&](const std::string& page_id, std::string* error) {
            return agent_browser.select_page(page_id, error);
        });
    bind_agent_browser_page_lifecycle(
        "aceDesktop_agentBrowserClosePage",
        [&](const std::string& page_id, std::string* error) {
            return agent_browser.close_page(page_id, error);
        });

    host.bind("aceDesktop_agentBrowserSetLayout",
              [&](const std::string& req) -> std::string {
        try {
            const auto args = nlohmann::json::parse(req);
            if (!args.is_array() || args.empty() || !args[0].is_object()) {
                return nlohmann::json{
                    {"ok", false}, {"error", "expect [layout:object]"}
                }.dump();
            }
            const auto& value = args[0];
            const std::string page_id = value.value("page_id", "");
            if (page_id.empty()) {
                return nlohmann::json{
                    {"ok", false}, {"error", "layout page_id is required"}
                }.dump();
            }
            AgentBrowserBounds bounds;
            bounds.x = value.value("x", 0);
            bounds.y = value.value("y", 0);
            bounds.width = value.value("width", 0);
            bounds.height = value.value("height", 0);
            bounds.visible = value.value("visible", false);
            if (const auto occlusions = value.find("occlusion_rects");
                occlusions != value.end()) {
                if (!occlusions->is_array() ||
                    occlusions->size() > kAgentBrowserMaxOcclusionRects) {
                    return nlohmann::json{
                        {"ok", false},
                        {"error", "occlusion_rects must be a bounded array"},
                    }.dump();
                }
                bounds.occlusion_rects.reserve(occlusions->size());
                for (const auto& item : *occlusions) {
                    if (!item.is_object()) {
                        return nlohmann::json{
                            {"ok", false},
                            {"error", "occlusion rectangle must be an object"},
                        }.dump();
                    }
                    AgentBrowserOcclusionRect rect;
                    rect.x = item.value("x", -1);
                    rect.y = item.value("y", -1);
                    rect.width = item.value("width", 0);
                    rect.height = item.value("height", 0);
                    bounds.occlusion_rects.push_back(rect);
                }
            }
            if (const auto revision = value.find("layout_revision");
                revision != value.end()) {
                if (revision->is_number_unsigned()) {
                    bounds.layout_revision = revision->get<std::uint64_t>();
                } else if (revision->is_number_integer()) {
                    const auto signed_revision = revision->get<std::int64_t>();
                    if (signed_revision < 0) {
                        return nlohmann::json{
                            {"ok", false},
                            {"error", "layout_revision must be non-negative"},
                        }.dump();
                    }
                    bounds.layout_revision =
                        static_cast<std::uint64_t>(signed_revision);
                } else {
                    return nlohmann::json{
                        {"ok", false},
                        {"error", "layout_revision must be an integer"},
                    }.dump();
                }
            }
            std::string error;
            if (!agent_browser.set_bounds(page_id, bounds, &error)) {
                return nlohmann::json{{"ok", false}, {"error", error}}.dump();
            }
            return nlohmann::json{
                {"ok", true},
                {"layout_revision", bounds.layout_revision},
                {"occlusion_rect_count", bounds.occlusion_rects.size()},
            }.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{
                {"ok", false}, {"error", std::string("layout: ") + e.what()}
            }.dump();
        }
    });

    host.bind("aceDesktop_agentBrowserNavigate",
              [&](const std::string& req) -> std::string {
        try {
            const auto args = nlohmann::json::parse(req);
            if (!args.is_array() || args.empty() || !args[0].is_object()) {
                return nlohmann::json{
                    {"ok", false}, {"error", "expect [{page_id,url}]"}
                }.dump();
            }
            const std::string page_id = args[0].value("page_id", "");
            const std::string url = args[0].value("url", "");
            if (page_id.empty() || url.empty()) {
                return nlohmann::json{
                    {"ok", false}, {"error", "page_id and url are required"}
                }.dump();
            }
            std::string error;
            if (!agent_browser.navigate(page_id, url, &error)) {
                return nlohmann::json{{"ok", false}, {"error", error}}.dump();
            }
            return nlohmann::json{{"ok", true}}.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{
                {"ok", false}, {"error", std::string("navigate: ") + e.what()}
            }.dump();
        }
    });

    host.bind("aceDesktop_agentBrowserSetShared",
              [&](const std::string& req) -> std::string {
        const auto args = nlohmann::json::parse(req, nullptr, false);
        if (!args.is_array() || args.empty() || !args[0].is_object()) {
            return nlohmann::json{
                {"ok", false}, {"error", "expect [{page_id,shared}]"}
            }.dump();
        }
        const std::string page_id = args[0].value("page_id", "");
        if (page_id.empty() || !args[0].contains("shared") ||
            !args[0]["shared"].is_boolean()) {
            return nlohmann::json{
                {"ok", false},
                {"error", "page_id and shared are required"}
            }.dump();
        }
        std::string error;
        const bool shared = args[0]["shared"].get<bool>();
        if (!agent_browser.set_shared_with_agent(page_id, shared, &error)) {
            return nlohmann::json{{"ok", false}, {"error", error}}.dump();
        }
        return nlohmann::json{
            {"ok", true},
            {"page_id", page_id},
            {"shared_with_agent", shared},
        }.dump();
    });

    host.bind("aceDesktop_agentBrowserGetConsoleLogs",
              [&](const std::string& req) -> std::string {
        const auto args = nlohmann::json::parse(req, nullptr, false);
        if (!args.is_array() || args.empty() || !args[0].is_string()) {
            return nlohmann::json{
                {"ok", false}, {"error", "expect [page_id:string]"}
            }.dump();
        }
        const std::string page_id = args[0].get<std::string>();
        std::string error;
        const std::string logs = agent_browser.console_logs(page_id, &error);
        if (!error.empty()) {
            return nlohmann::json{{"ok", false}, {"error", error}}.dump();
        }
        const auto page_state = agent_browser.state(page_id);
        return nlohmann::json{
            {"ok", true},
            {"page_id", page_id},
            {"url", page_state.url},
            {"title", page_state.title},
            {"logs", logs},
        }.dump();
    });

    auto bind_agent_browser_action =
        [&](const char* name,
            const std::function<bool(const std::string&, std::string*)>& action) {
        host.bind(name, [action](const std::string& req) -> std::string {
            const auto args = nlohmann::json::parse(req, nullptr, false);
            if (!args.is_array() || args.empty() || !args[0].is_string()) {
                return nlohmann::json{
                    {"ok", false}, {"error", "expect [page_id:string]"}
                }.dump();
            }
            const std::string page_id = args[0].get<std::string>();
            std::string error;
            if (!action(page_id, &error)) {
                return nlohmann::json{{"ok", false}, {"error", error}}.dump();
            }
            return nlohmann::json{{"ok", true}, {"page_id", page_id}}.dump();
        });
    };
    bind_agent_browser_action(
        "aceDesktop_agentBrowserGoBack",
        [&](const std::string& page_id, std::string* error) {
            return agent_browser.go_back(page_id, error);
        });
    bind_agent_browser_action(
        "aceDesktop_agentBrowserGoForward",
        [&](const std::string& page_id, std::string* error) {
            return agent_browser.go_forward(page_id, error);
        });
    bind_agent_browser_action(
        "aceDesktop_agentBrowserReload",
        [&](const std::string& page_id, std::string* error) {
            return agent_browser.reload(page_id, error);
        });
    bind_agent_browser_action(
        "aceDesktop_agentBrowserFocus",
        [&](const std::string& page_id, std::string* error) {
            return agent_browser.focus(page_id, error);
        });
    bind_agent_browser_action(
        "aceDesktop_agentBrowserToggleElementSelection",
        [&](const std::string& page_id, std::string* error) {
            return agent_browser.toggle_element_selection(page_id, error);
        });
    bind_agent_browser_action(
        "aceDesktop_agentBrowserToggleDevTools",
        [&](const std::string& page_id, std::string* error) {
            return agent_browser.open_developer_tools(page_id, error);
        });
    host.bind("aceDesktop_agentBrowserHide",
              [&](const std::string& req) -> std::string {
        std::string page_id;
        const auto args = nlohmann::json::parse(req, nullptr, false);
        if (args.is_array() && !args.empty() && args[0].is_string()) {
            page_id = args[0].get<std::string>();
        }
        agent_browser.hide(page_id);
        return nlohmann::json{{"ok", true}}.dump();
    });
#endif

    host.bind("aceDesktop_openDevTools", [&](const std::string& /*req*/) -> std::string {
        return nlohmann::json{{"ok", host.open_dev_tools()}}.dump();
    });

    host.bind("aceDesktop_getWebCoreInfo", [&](const std::string& /*req*/) -> std::string {
        auto info = host.web_core_info();
        nlohmann::json body{{"ok", true}};
        auto put = [&](const char* key, const std::string& value) {
            if (!value.empty()) body[key] = value;
        };
        put("backend", info.backend);
        put("name", info.name);
        put("version", info.version);
        put("detail", info.detail);
        put("wrapper_name", info.wrapper_name);
        put("wrapper_version", info.wrapper_version);
        return body.dump();
    });

    host.bind("aceDesktop_showAboutDialog", [&](const std::string& /*req*/) -> std::string {
        const auto web_core = host.web_core_info();
        DesktopAboutInfo info;
        info.acecode_version = ACECODE_VERSION;
        info.browser_name = web_core.name.empty() ? web_core.backend : web_core.name;
        info.browser_version = web_core.version;
        info.compiler_version = current_compiler_version();
        const bool shown = show_desktop_about_dialog(
            host.native_window(), info, acecode::desktop::native_locale());
        if (!shown) {
            return nlohmann::json{
                {"ok", false},
                {"error", "native About dialog is unavailable"},
            }.dump();
        }
        return nlohmann::json{{"ok", true}}.dump();
    });

    host.bind("aceDesktop_quitApp", [&](const std::string& /*req*/) -> std::string {
        host.request_quit();
        return nlohmann::json{{"ok", true}}.dump();
    });

    host.bind("aceDesktop_openExternalUrl", [&](const std::string& req) -> std::string {
        try {
            auto arr = nlohmann::json::parse(req);
            if (!arr.is_array() || arr.empty() || !arr[0].is_string()) {
                return nlohmann::json{{"ok", false}, {"error", "expect [url]"}}.dump();
            }
            auto result = acecode::desktop::open_external_url(arr[0].get<std::string>());
            if (!result.ok) {
                return nlohmann::json{{"ok", false}, {"error", result.error}}.dump();
            }
            return nlohmann::json{{"ok", true}}.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{{"ok", false}, {"error", std::string("parse: ") + e.what()}}.dump();
        }
    });

    host.bind("aceDesktop_writeClipboardText", [&](const std::string& req) -> std::string {
        try {
            auto arr = nlohmann::json::parse(req);
            if (!arr.is_array() || arr.empty() || !arr[0].is_string()) {
                return nlohmann::json{{"ok", false}, {"error", "expect [text]"}}.dump();
            }
            auto result = acecode::write_system_clipboard_text(arr[0].get<std::string>());
            if (!result) {
                std::string error = result.detail;
                if (error.empty()) {
                    error = result.status == acecode::ClipboardTextWriteResult::Status::TooLarge
                        ? "clipboard text is too large"
                        : "clipboard unavailable";
                }
                return nlohmann::json{{"ok", false}, {"error", error}}.dump();
            }
            return nlohmann::json{{"ok", true}}.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{{"ok", false}, {"error", std::string("parse: ") + e.what()}}.dump();
        }
    });

    auto parse_pointer_event = [](const nlohmann::json& arr) {
        WebHost::PointerEvent event;
        if (!arr.is_array() || arr.empty() || !arr[0].is_object()) return event;
        const auto& p = arr[0];
        if (p.contains("button") && p["button"].is_number_integer()) {
            event.button = p["button"].get<int>();
        }
        if (p.contains("screenX") && p["screenX"].is_number()) {
            event.root_x = static_cast<int>(p["screenX"].get<double>());
            event.has_position = true;
        }
        if (p.contains("screenY") && p["screenY"].is_number()) {
            event.root_y = static_cast<int>(p["screenY"].get<double>());
            event.has_position = true;
        }
        if (p.contains("time") && p["time"].is_number()) {
            const double time = p["time"].get<double>();
            if (time > 0.0) {
                event.timestamp = static_cast<unsigned int>(time);
            }
        }
        return event;
    };

    host.bind("aceDesktop_startWindowDrag", [&](const std::string& req) -> std::string {
        WebHost::PointerEvent event;
        try {
            event = parse_pointer_event(nlohmann::json::parse(req));
        } catch (...) {
            // Missing pointer metadata is acceptable; GTK can still try with defaults.
        }
        return nlohmann::json{{"ok", host.start_window_drag(event)}}.dump();
    });
    // 前端在窗口 4 边的不可见 strip 上 mousedown 时调用,内部 SendMessage 进入
    // 原生 resize 循环。direction 见 parse_resize_direction;非法/最大化/平台
    // 不支持 → ok:false 但不抛错,前端静默吞掉。
    host.bind("aceDesktop_startWindowResize", [&](const std::string& req) -> std::string {
        std::string direction;
        WebHost::PointerEvent event;
        try {
            auto arr = nlohmann::json::parse(req);
            if (arr.is_array() && !arr.empty() && arr[0].is_string()) {
                direction = arr[0].get<std::string>();
                if (arr.size() > 1) {
                    nlohmann::json event_arr = nlohmann::json::array({arr[1]});
                    event = parse_pointer_event(event_arr);
                }
            }
        } catch (...) {
            // 非法 JSON 也走下面的 ok:false 分支
        }
        if (direction.empty()) {
            return nlohmann::json{{"ok", false}, {"error", "expect [direction]"}}.dump();
        }
        return nlohmann::json{{"ok", host.start_window_resize(direction, event)}}.dump();
    });
    host.bind("aceDesktop_minimizeWindow", [&](const std::string& /*req*/) -> std::string {
        return nlohmann::json{{"ok", host.minimize_window()}}.dump();
    });
    host.bind("aceDesktop_toggleMaximizeWindow", [&](const std::string& /*req*/) -> std::string {
        return nlohmann::json{{"ok", host.toggle_maximize_window()}}.dump();
    });
    // 前端 TopBar 在 mount 时调一次拿初始最大化态;后续靠下方 set_window_state_change_handler
    // 推送的 aceDesktop_onMaximizeStateChanged 回调实时更新图标(矩形 ↔ 双层方框)。
    host.bind("aceDesktop_isWindowMaximized", [&](const std::string& /*req*/) -> std::string {
        return nlohmann::json{{"maximized", host.is_window_maximized()}}.dump();
    });
    host.bind("aceDesktop_closeWindow", [&](const std::string& /*req*/) -> std::string {
        return nlohmann::json{{"ok", host.close_window()}}.dump();
    });
    // 前端 ThemeProvider 在主题变化(含 mount 首次)时推送 body 底色
    // (--ace-bg),native 把 host/webview_widget 窗口类背景刷 + WebView2
    // DefaultBackgroundColor 一起换 — 快速 resize 时新暴露区域的打底色
    // 跟随主题,不再闪黑/闪白。非法颜色 ok:false(哨兵,不猜),前端静默吞。
    host.bind("aceDesktop_setWindowBackgroundColor", [&](const std::string& req) -> std::string {
        std::string color;
        try {
            auto arr = nlohmann::json::parse(req);
            if (arr.is_array() && !arr.empty() && arr[0].is_string()) {
                color = arr[0].get<std::string>();
            }
        } catch (...) {
            // 非法 JSON 走下面的 ok:false 分支
        }
        if (color.empty()) {
            return nlohmann::json{{"ok", false}, {"error", "expect [\"#rrggbb\"]"}}.dump();
        }
        return nlohmann::json{{"ok", host.set_background_color(color)}}.dump();
    });
    host.bind("aceDesktop_focusWindow", [&](const std::string& /*req*/) -> std::string {
        bring_window_foreground();
        return nlohmann::json{{"ok", true}}.dump();
    });
    host.bind("aceDesktop_activateFileDropWindow", [&](const std::string& /*req*/) -> std::string {
        // A drag-enter is direct user intent. Present the host once while the
        // pointer is still over it, but deliberately avoid the notification
        // activation path: its temporary TOPMOST fallback is appropriate for
        // tray/toast attention, not for an in-progress file drag.
        host.set_visible(true);
        return nlohmann::json{{"ok", true}}.dump();
    });

    // WM_SIZE 时如果最大化状态变化(被 web_host.cpp 内部 g_last_known_maximized 去重过),
    // eval 一段 JS 调前端 window.aceDesktop_onMaximizeStateChanged(bool),让 TopBar 切换
    // 图标。前端没注册回调时静默吞,避免 webview 异常 ts 上报。
    host.set_window_state_change_handler([&host, &agent_browser](bool maximized) {
        agent_browser.refresh_layout();
        const std::string js = std::string(
            "(function(){try{if(window.aceDesktop_onMaximizeStateChanged){"
            "window.aceDesktop_onMaximizeStateChanged(") + (maximized ? "true" : "false") +
            ");}}catch(e){}})();";
        host.eval(js);
    });

    host.set_window_visibility_handler([&agent_browser](bool visible) {
        agent_browser.set_parent_visible(visible);
    });

    // Native window activation does not consistently reach WebView2 as a DOM
    // focus event. Send an explicit event after WM_ACTIVATE so a visible chat
    // composer can restore keyboard focus without requiring another click.
    host.set_window_focus_handler([&host, &agent_browser]() {
        agent_browser.set_parent_visible(true);
        host.eval("(function(){try{window.dispatchEvent(new Event("
                  "'acecode:desktop-window-focus'));}catch(e){}})();");
    });

    // 系统通知 bridge — 前端应用级 WS 监听器在权限/提问/回合完成时调用。
    // 兼容参数[object]和历史参数[JSON.stringify(object)]。失败静默 no-op,
    // 前端 desktopNotify.js 已经做过抑制规则判定,这里不再二次过滤。
    host.bind("aceDesktop_notify", [&](const std::string& req) -> std::string {
        std::string error;
        auto payload = parse_notification_bridge_args(req, &error);
        if (!payload.has_value()) {
            return nlohmann::json{{"ok", false}, {"error", error}}.dump();
        }
        const bool shown = show_notification(*payload);
        return nlohmann::json{
            {"ok", shown},
            {"error", shown ? std::string{} :
                std::string{"native notifications unavailable"}},
        }.dump();
    });

    host.bind("aceDesktop_getNotificationAuthorization",
              [notification_authorization_json](
                  const std::string& /*req*/) -> std::string {
        // Return the current snapshot immediately and ask the backend to
        // publish a fresh asynchronous state. This picks up changes made in
        // macOS System Settings while ACECode remained open.
        refresh_notification_authorization();
        return notification_authorization_json(
            notification_authorization_state()).dump();
    });
    host.bind("aceDesktop_requestNotificationAuthorization",
              [notification_authorization_json](
                  const std::string& /*req*/) -> std::string {
        const bool requested = request_notification_authorization();
        auto response = notification_authorization_json(
            notification_authorization_state());
        if (!requested) response["ok"] = false;
        return response.dump();
    });
    host.bind("aceDesktop_openNotificationSettings",
              [notification_authorization_json](
                  const std::string& /*req*/) -> std::string {
        const bool opened = open_notification_settings();
        auto response = notification_authorization_json(
            notification_authorization_state());
        response["ok"] = opened;
        return response.dump();
    });

    // 直接触发"切到某 session"。前端可在 SearchPalette 等场景调用,与 toast 点击
    // 走同一 click_handler 逻辑,UX 与代码路径一致。
    host.bind("aceDesktop_focusSession", [&host, &active_mu, &active_hash_dynamic, &bring_window_foreground](const std::string& req) -> std::string {
        try {
            auto arr = nlohmann::json::parse(req);
            if (!arr.is_array() || arr.empty() || !arr[0].is_object()) {
                return nlohmann::json{{"ok", false}, {"error", "expect [{workspace_hash,session_id}]"}}.dump();
            }
            const auto& p = arr[0];
            std::string ws  = p.value("workspace_hash", std::string{});
            std::string sid = p.value("session_id", std::string{});
            if (sid.empty()) {
                return nlohmann::json{{"ok", false}, {"error", "session_id required"}}.dump();
            }
            bring_window_foreground();
            std::string current_active;
            {
                std::lock_guard<std::mutex> lk(active_mu);
                current_active = active_hash_dynamic;
            }
            const bool same_workspace = (ws.empty() || ws == current_active);
            std::string ws_lit = nlohmann::json(ws).dump();
            std::string sid_lit = nlohmann::json(sid).dump();
            std::string js = same_workspace
                ? "(function(){try{if(window.aceDesktop_focusSessionFromBridge){"
                  "window.aceDesktop_focusSessionFromBridge(" + sid_lit + "," + ws_lit + ");}}catch(e){}})();"
                : "(function(){try{if(window.aceDesktop_activateAndOpenSession){"
                  "window.aceDesktop_activateAndOpenSession(" + ws_lit + "," + sid_lit + ");}}catch(e){}})();";
            host.eval(js);
            return nlohmann::json{{"ok", true}}.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{{"ok", false}, {"error", e.what()}}.dump();
        }
    });

    // bridge: setTrayMenu — 前端推送 pinned + recent session 列表给 native 缓存。
    // 右键托盘时 native 取这份缓存渲染 Codex 风格菜单。
    // payload: [{ workspace_name, pinned: [{session_id, workspace_hash, title, subtitle}], recent: [...] }]
    // 见 openspec/changes/enhance-desktop-tray-menu。
    host.bind("aceDesktop_setTrayMenu", [&](const std::string& req) -> std::string {
        try {
            set_tray_menu_payload(tray_menu_payload_from_bridge_request(req));
            return nlohmann::json{{"ok", true}}.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{{"ok", false}, {"error", std::string("parse: ") + e.what()}}.dump();
        }
    });

    host.bind("aceDesktop_openInExplorer", [&](const std::string& req) -> std::string {
        try {
            auto arr = nlohmann::json::parse(req);
            if (!arr.is_array() || arr.empty() || !arr[0].is_string()) {
                return nlohmann::json{{"ok", false}, {"error", "expect [path]"}}.dump();
            }
            auto result = acecode::desktop::open_path_in_file_manager(
                arr[0].get<std::string>());
            if (!result.ok) {
                return nlohmann::json{{"ok", false}, {"error", result.error}}.dump();
            }
            return nlohmann::json{{"ok", true}}.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{{"ok", false}, {"error", std::string("parse: ") + e.what()}}.dump();
        }
    });

    // navigate 前注入 JS: hook console + window 错误事件 → 全部转发回 native。
    // 故意不 hook console.log / console.info,避免噪音(可在前端代码里需要时
    // 显式调 aceDesktop_logFromWeb('info', ...))。
    // 系统文件拖放。Windows/macOS 的 native 拦截把路径回传给终端和 composer
    // 两个接收函数；各自用最近 hover 时间戳判定落点，不会互相抢占。Linux 由
    // 前端 text/uri-list 进入同一个 filesystem-item materialize bridge。
    host.set_file_drop_handler([&host](std::vector<std::string> paths) {
        if (paths.empty()) return;
        nlohmann::json arr = nlohmann::json::array();
        for (const auto& p : paths) arr.push_back(p);
        const std::string js =
            "(function(){var p=" + arr.dump() + ";"
            "try{if(window.__aceConsoleAcceptFileDrop){window.__aceConsoleAcceptFileDrop(p);}}catch(e){}"
            "try{if(window.__aceComposerAcceptFileDrop){window.__aceComposerAcceptFileDrop(p);}}catch(e){}"
            "})();";
        host.eval(js);
    });

    constexpr const char* kFramelessWindowFlag = "true";
#if defined(_WIN32)
    constexpr const char* kHostOs = "windows";
    constexpr const char* kNativeFileDrop = "true";
#elif defined(__APPLE__)
    constexpr const char* kHostOs = "macos";
    constexpr const char* kNativeFileDrop = "true";
#else
    constexpr const char* kHostOs = "linux";
    constexpr const char* kNativeFileDrop = "false";
#endif
    const std::string appearance_bootstrap = nlohmann::json{
        {"theme", desktop_cfg.web_ui.theme},
        {"color_theme", desktop_cfg.web_ui.color_theme},
        {"font_size", desktop_cfg.web_ui.font_size},
    }.dump();
    const std::string startup_bootstrap = startup_timeline.snapshot_json();
    host.init_script(acecode::desktop::locale_bootstrap_script(
                         desktop_cfg.ui.locale, desktop_effective_locale) +
                                     "window.__ACECODE_APPEARANCE__=" +
                                     appearance_bootstrap + ";\n" +
                                     "window.__ACECODE_DESKTOP_STARTUP__=" +
                                     startup_bootstrap + ";\n" +
                                     "window.__ACECODE_DESKTOP_SHELL__=true;\n" +
                                     "window.__ACECODE_DESKTOP_DEBUG__=" +
                                     (desktop_debug ? "true" : "false") + ";\n" +
                                     "window.__ACECODE_FRAMELESS_WINDOW__=" +
                                     kFramelessWindowFlag + ";\n" +
                                     "window.__ACECODE_OS__=\"" + kHostOs + "\";\n" +
                                     "window.__ACECODE_AGENT_BROWSER_SUPPORTED__=" +
                                     (agent_browser.supported() ? "true" : "false") + ";\n" +
                                     "window.__ACECODE_NATIVE_FILE_DROP__=" +
                                     kNativeFileDrop + ";\n" + R"JS(
    (function () {
      var notifyReady = function () {
        try {
          if (window.__aceDesktopReadySent) return;
          window.__aceDesktopReadySent = true;
          var send = function () {
            try {
              if (window.aceDesktop_pageReady) {
                Promise.resolve(window.aceDesktop_pageReady()).catch(function () {});
              }
            } catch (e) {}
          };
          requestAnimationFrame(function () {
            requestAnimationFrame(function () { setTimeout(send, 40); });
          });
        } catch (e) {}
      };
      if (document.readyState === 'complete' || document.readyState === 'interactive') {
        notifyReady();
      } else {
        window.addEventListener('DOMContentLoaded', notifyReady, { once: true });
        window.addEventListener('load', notifyReady, { once: true });
      }
      window.addEventListener('keydown', function (event) {
        try {
          if (!event || event.key !== 'F11') return;
          event.preventDefault();
          event.stopPropagation();
          if (window.aceDesktop_openDevTools) {
            Promise.resolve(window.aceDesktop_openDevTools()).catch(function () {});
          }
        } catch (e) {}
      }, true);
      if (!window.aceDesktop_logFromWeb) return;
      var send = function (level, args) {
        try {
          var parts = [];
          for (var i = 0; i < args.length; i++) {
            var a = args[i];
            try { parts.push(typeof a === 'string' ? a : JSON.stringify(a)); }
            catch (e) { parts.push(String(a)); }
          }
          window.aceDesktop_logFromWeb(level, parts.join(' '));
        } catch (e) { /* swallow */ }
      };
      var origErr  = console.error.bind(console);
      var origWarn = console.warn.bind(console);
      console.error = function () { send('error', arguments); origErr.apply(console, arguments); };
      console.warn  = function () { send('warn',  arguments); origWarn.apply(console, arguments); };
      window.addEventListener('error', function (e) {
        send('error', ['window.onerror', e.message, e.filename + ':' + e.lineno + ':' + e.colno,
                       e.error && e.error.stack ? e.error.stack : '']);
      });
      window.addEventListener('unhandledrejection', function (e) {
        var r = e.reason;
        send('error', ['unhandledrejection', r && r.message ? r.message : String(r),
                       r && r.stack ? r.stack : '']);
      });
    })();
    )JS");

    // bridge: listWorkspaces
    host.bind("aceDesktop_listWorkspaces", [&](const std::string& /*req*/) -> std::string {
        // The shared daemon can register a workspace while Desktop is already
        // running. Its WorkspaceRegistry is a separate in-process cache, so
        // refresh from the persisted marker before serving native operations.
        registry.scan(proj_dir);
        nlohmann::json arr = nlohmann::json::array();
        auto entries = registry.list();
        std::string cur;
        { std::lock_guard<std::mutex> lk(active_mu); cur = active_hash_dynamic; }
        for (auto& m : entries) {
            auto snap = pool.lookup(kSharedDaemonSlotHash, kSharedDaemonContextId);
            nlohmann::json o;
            o["hash"] = m.hash;
            o["cwd"] = m.cwd;
            o["name"] = m.name;
            o["available"] = is_existing_directory(m.cwd);
            o["daemon_state"] = state_string(snap.state);
            o["active"] = (m.hash == cur);
            if (snap.state == DaemonState::Running) {
                o["port"] = snap.port;
                o["token"] = snap.token;
            }
            if (!snap.error.empty()) o["error"] = snap.error;
            arr.push_back(o);
        }
        return arr.dump();
    });

    // bridge: get/set home workspace selector preference.
    host.bind("aceDesktop_getHomeWorkspaceHash", [&](const std::string& /*req*/) -> std::string {
        return nlohmann::json{
            {"workspace_hash", acecode::read_last_home_workspace_hash()}
        }.dump();
    });
    host.bind("aceDesktop_setHomeWorkspaceHash", [&](const std::string& req) -> std::string {
        try {
            auto arr = nlohmann::json::parse(req);
            if (!arr.is_array() || arr.empty() || !arr[0].is_string()) {
                return nlohmann::json{{"error", "missing hash arg"}}.dump();
            }
            acecode::write_last_home_workspace_hash(arr[0].get<std::string>());
            return nlohmann::json{{"ok", true}}.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{{"error", std::string("parse: ") + e.what()}}.dump();
        }
    });

    // bridge: activateWorkspace
    auto activate_fn = [&](const std::string& hash) -> nlohmann::json {
        registry.scan(proj_dir);
        auto m = registry.get(hash);
        if (!m) {
            return {{"error", "unknown workspace hash"}};
        }
        if (!is_existing_directory(m->cwd)) {
            return {{"error", "workspace path is not available: " + m->cwd}};
        }
        // 切 workspace 前先清托盘菜单缓存,避免新 workspace 第一次 setTrayMenu 之前
        // 用户右键看到旧 workspace 的 session 残留(decision 5 in design.md)。
        clear_tray_menu_payload();
        ActivateRequest req;
        req.hash = kSharedDaemonSlotHash;
        req.cwd = choose_launch_cwd(m->cwd, proc_cwd, daemon_exe);
        req.daemon_exe_path = daemon_exe;
        req.static_dir = dev_web_dir;
        // Shared desktop daemon: one process hosts all registered workspaces.
        // Keep runtime files isolated from standalone daemon runs, but do not
        // create per-workspace or per-resume run dirs.
        req.context_id = kSharedDaemonContextId;
        configure_managed_request(req);
        req.native_folder_picker_enabled = true;
        auto r = pool.activate(req);
        if (!r.ok) {
            return {{"error", r.error}};
        }
        std::string workspace_error;
        if (!post_workspace_to_daemon(r.port, r.token, m->cwd, workspace_error)) {
            return {{"error", workspace_error}};
        }
        { std::lock_guard<std::mutex> lk(active_mu); active_hash_dynamic = m->hash; }
        return {{"port", r.port}, {"token", r.token}, {"workspace_hash", m->hash}, {"cwd", m->cwd}};
    };
    host.bind("aceDesktop_activateWorkspace", [&](const std::string& req) -> std::string {
        // webview 给的 args 是 JSON array,如 ["abc123"]
        try {
            auto arr = nlohmann::json::parse(req);
            if (!arr.is_array() || arr.empty() || !arr[0].is_string()) {
                return nlohmann::json{{"error", "missing hash arg"}}.dump();
            }
            return activate_fn(arr[0].get<std::string>()).dump();
        } catch (const std::exception& e) {
            return nlohmann::json{{"error", std::string("parse: ") + e.what()}}.dump();
        }
    });

    // bridge: resumeSession(hash, session_id)
    host.bind("aceDesktop_resumeSession", [&](const std::string& req) -> std::string {
        try {
            auto arr = nlohmann::json::parse(req);
            if (!arr.is_array() || arr.size() < 2 ||
                !arr[0].is_string() || !arr[1].is_string()) {
                return nlohmann::json{{"error", "expect [hash, session_id]"}}.dump();
            }
            std::string hash = arr[0].get<std::string>();
            std::string session_id = arr[1].get<std::string>();
            registry.scan(proj_dir);
            auto m = registry.get(hash);
            if (!m) return nlohmann::json{{"error", "unknown workspace hash"}}.dump();
            if (!is_existing_directory(m->cwd)) {
                return nlohmann::json{{"error", "workspace path is not available: " + m->cwd}}.dump();
            }

            ActivateRequest areq;
            areq.hash = kSharedDaemonSlotHash;
            areq.context_id = kSharedDaemonContextId;
            areq.cwd = choose_launch_cwd(m->cwd, proc_cwd, daemon_exe);
            areq.daemon_exe_path = daemon_exe;
            areq.static_dir = dev_web_dir;
            configure_managed_request(areq);
            areq.native_folder_picker_enabled = true;
            auto ar = pool.activate(areq);
            if (!ar.ok) return nlohmann::json{{"error", ar.error}}.dump();

            std::string workspace_error;
            if (!post_workspace_to_daemon(ar.port, ar.token, m->cwd, workspace_error)) {
                return nlohmann::json{{"error", workspace_error}}.dump();
            }

            std::string resume_error;
            if (!post_resume_to_daemon(ar.port, ar.token, session_id, m->hash, resume_error)) {
                return nlohmann::json{{"error", resume_error}}.dump();
            }
            return nlohmann::json{
                {"context_id", areq.context_id},
                {"port", ar.port},
                {"token", ar.token},
                {"workspace_hash", m->hash},
                {"cwd", m->cwd},
                {"session_id", session_id},
            }.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{{"error", std::string("parse: ") + e.what()}}.dump();
        }
    });

    // bridge: renameWorkspace
    host.bind("aceDesktop_renameWorkspace", [&](const std::string& req) -> std::string {
        try {
            auto arr = nlohmann::json::parse(req);
            if (!arr.is_array() || arr.size() < 2 ||
                !arr[0].is_string() || !arr[1].is_string()) {
                return nlohmann::json{{"error", "expect [hash, name]"}}.dump();
            }
            std::string h = arr[0].get<std::string>();
            std::string n = arr[1].get<std::string>();
            registry.scan(proj_dir);
            bool ok = registry.set_name(proj_dir, h, n);
            if (!ok) return nlohmann::json{{"error", "rename failed"}}.dump();
            return nlohmann::json{{"ok", true}}.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{{"error", std::string("parse: ") + e.what()}}.dump();
        }
    });

    // bridge: removeWorkspace (hide from Desktop list; does not delete data)
    host.bind("aceDesktop_removeWorkspace", [&](const std::string& req) -> std::string {
        try {
            auto arr = nlohmann::json::parse(req);
            if (!arr.is_array() || arr.empty() || !arr[0].is_string()) {
                return nlohmann::json{{"error", "expect [hash]"}}.dump();
            }
            std::string h = arr[0].get<std::string>();
            bool was_active = false;
            {
                std::lock_guard<std::mutex> lk(active_mu);
                was_active = (active_hash_dynamic == h);
            }

            registry.scan(proj_dir);
            bool ok = registry.hide(proj_dir, h);
            if (!ok) return nlohmann::json{{"error", "remove failed"}}.dump();

            std::string next_active;
            if (was_active) {
                auto remaining = registry.list();
                if (!remaining.empty()) next_active = remaining.front().hash;
                std::lock_guard<std::mutex> lk(active_mu);
                active_hash_dynamic = next_active;
            }

            return nlohmann::json{{"ok", true}, {"active_workspace_hash", next_active}}.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{{"error", std::string("parse: ") + e.what()}}.dump();
        }
    });

    // Native filesystem-item bridge shared by composer drag/drop and clipboard
    // paste. Paths must come from the shell/native transfer layer; the bridge
    // canonicalizes them and returns the same item schema as the context picker.
    host.bind("aceDesktop_materializeContextItems", [&](const std::string& req) -> std::string {
        try {
            auto args = nlohmann::json::parse(req);
            if (!args.is_array() || args.empty() || !args[0].is_array()) {
                return nlohmann::json{
                    {"ok", false}, {"error", "expect [paths]"}
                }.dump();
            }
            std::vector<std::string> paths;
            for (const auto& value : args[0]) {
                if (!value.is_string()) {
                    return nlohmann::json{
                        {"ok", false}, {"error", "filesystem path must be a string"}
                    }.dump();
                }
                paths.push_back(value.get<std::string>());
            }
            return context_items_json(paths).dump();
        } catch (const std::exception& e) {
            return nlohmann::json{
                {"ok", false}, {"error", std::string("filesystem items: ") + e.what()}
            }.dump();
        }
    });

    host.bind("aceDesktop_readClipboardContextItems", [&](const std::string&) -> std::string {
        auto clipboard = acecode::read_system_clipboard_paths();
        if (clipboard.status == acecode::ClipboardPathsReadResult::Status::TooMany) {
            return nlohmann::json{
                {"ok", false},
                {"error", clipboard.detail.empty()
                    ? "clipboard contains too many filesystem items"
                    : clipboard.detail},
            }.dump();
        }
        if (!clipboard) {
            return nlohmann::json{
                {"ok", true},
                {"items", nlohmann::json::array()},
                {"filesystem_items", false},
            }.dump();
        }
        auto response = context_items_json(clipboard.paths);
        response["filesystem_items"] = true;
        return response.dump();
    });

    // Preview file picker: return one absolute path without materializing the
    // selected file as a composer attachment.
#ifdef _WIN32
    host.bind("aceDesktop_pickPreviewFile", [&](const std::string& req) -> std::string {
        try {
            std::string default_folder;
            auto args = nlohmann::json::parse(req);
            if (args.is_array() && !args.empty() && args[0].is_object()) {
                default_folder = args[0].value("cwd", std::string{});
            }

            auto picked = acecode::desktop::pick_single_file(
                host.native_window(), default_folder);
            if (!picked.error.empty()) {
                return nlohmann::json{{"ok", false}, {"error", picked.error}}.dump();
            }
            if (!picked.file_path) {
                return nlohmann::json{{"ok", true}, {"cancelled", true}}.dump();
            }
            return nlohmann::json{
                {"ok", true},
                {"cancelled", false},
                {"path", *picked.file_path},
            }.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{
                {"ok", false},
                {"error", std::string("preview file picker: ") + e.what()},
            }.dump();
        }
    });

    // Composer context picker: one Windows common file dialog handles normal
    // file multi-selection plus a custom "select current folder" action.
    host.bind("aceDesktop_pickContextItems", [&](const std::string& req) -> std::string {
        try {
            std::string default_folder;
            auto args = nlohmann::json::parse(req);
            if (args.is_array() && !args.empty() && args[0].is_object()) {
                default_folder = args[0].value("cwd", std::string{});
            }

            auto picked = acecode::desktop::pick_context_items(
                host.native_window(), default_folder);
            if (!picked.error.empty()) {
                return nlohmann::json{{"ok", false}, {"error", picked.error}}.dump();
            }

            nlohmann::json result{{"ok", true}, {"cancelled", false}};
            result["items"] = nlohmann::json::array();
            if (picked.folder_path) {
                auto materialized = acecode::desktop::materialize_context_items(
                    {*picked.folder_path});
                if (!materialized || materialized.items.size() != 1 ||
                    materialized.items[0].kind != acecode::desktop::ContextItemKind::Folder) {
                    return nlohmann::json{
                        {"ok", false},
                        {"error", materialized.error.empty()
                            ? "selected folder is unavailable" : materialized.error},
                    }.dump();
                }
                std::string folder_error;
                auto folder = context_picker_folder_reference(
                    default_folder, materialized.items[0].path, folder_error);
                if (!folder) {
                    return nlohmann::json{
                        {"ok", false}, {"error", folder_error}
                    }.dump();
                }
                nlohmann::json item{
                    {"kind", "folder"},
                    {"path", folder->path},
                };
                if (folder->relative_path) {
                    item["relative_path"] = *folder->relative_path;
                }
                result["items"].push_back(std::move(item));
                return result.dump();
            }

            auto materialized = acecode::desktop::materialize_context_items(
                picked.file_paths);
            if (!materialized) {
                return nlohmann::json{
                    {"ok", false}, {"error", materialized.error}
                }.dump();
            }
            for (const auto& item : materialized.items) {
                if (item.kind != acecode::desktop::ContextItemKind::File) {
                    return nlohmann::json{
                        {"ok", false}, {"error", "selected item is not a regular file"}
                    }.dump();
                }
                result["items"].push_back(context_item_json(item));
            }
            if (picked.file_paths.empty()) result["cancelled"] = true;
            return result.dump();
        } catch (const std::exception& e) {
            return nlohmann::json{
                {"ok", false}, {"error", std::string("context picker: ") + e.what()}
            }.dump();
        }
    });
#endif

    // bridge: addWorkspace (folder picker)
    host.bind("aceDesktop_addWorkspace", [&](const std::string& /*req*/) -> std::string {
        auto outcome = pick_folder_outcome(host.native_window());
        // 环境缺失选择器工具(Linux 无 zenity/kdialog)必须透传给前端 toast,
        // 否则"添加项目"按钮表现为点了毫无反应;用户取消才返回 null 静默。
        if (!outcome.error.empty()) {
            return nlohmann::json{{"error", outcome.error}}.dump();
        }
        if (!outcome.path) return "null";
        // normalize:把反斜杠改成正斜杠,作为 cwd 持久化(与 hash 算法的输入对齐)
        std::string cwd = *outcome.path;
        for (auto& c : cwd) if (c == '\\') c = '/';
        auto m = registry.register_new(proj_dir, cwd);
        nlohmann::json o;
        o["hash"] = m.hash;
        o["cwd"] = m.cwd;
        o["name"] = m.name;
        return o.dump();
    });

    // 4. navigate(URL 在第 3 步已就绪)
    mark_startup("native_shell_ready");
    mark_startup("webview_navigate_begin");
    host.init_script(
        "window.__ACECODE_DESKTOP_STARTUP__=" +
        startup_timeline.snapshot_json() + ";\n");
    startup_navigation_started = true;
    host.navigate(url);
    if (url == onboarding_url()) {
        close_splash_once();
    }

    // 5. 阻塞主循环
    host.run();

    // 6. quit:写 last_active + stop_all
    {
        std::lock_guard<std::mutex> lk(active_mu);
        if (!active_hash_dynamic.empty()) {
            acecode::write_last_active_workspace_hash(active_hash_dynamic);
        }
    }
    // 退出前撤销系统通知 + 移除托盘图标。顺序与 init 相反。
    shutdown_notifications();
    notification_shutdown_guard.dismiss();
    shutdown_tray_icon();

    auto failures = pool.shutdown_all();
    if (restart_requested.load()) {
        // The replacement must not see the dying process's singleton guard and
        // focus it instead of starting. At this point the WebView loop, tray,
        // notifications, and managed daemons have all completed teardown.
        singleton.release();
        std::string restart_error;
        if (!launch_desktop_replacement(desktop_restart_target, &restart_error)) {
            LOG_ERROR("[desktop] failed to launch replacement after upgrade: " + restart_error);
            return 101;
        }
        LOG_INFO("[desktop] launched replacement after upgrade");
    }
    return failures.empty() ? 0 : 100; // 部分失败返回非零便于诊断
    }; // end of run lambda

    try {
        return run();
    } catch (const std::exception& e) {
        LOG_ERROR(std::string("[desktop] unhandled exception during startup: ") + e.what());
#ifdef _WIN32
        const std::string locale = acecode::desktop::native_locale();
        const std::wstring wbody = acecode::utf8_to_wide(
            acecode::desktop::format_startup_exception_message(e.what(), locale));
        const std::wstring wtitle = acecode::utf8_to_wide(std::string(
            acecode::desktop::desktop_string(
                acecode::desktop::DesktopStringId::StartupFailedTitle, locale)));
        ::MessageBoxW(nullptr,
                      wbody.empty() ? L"Unhandled exception during startup." : wbody.c_str(),
                      wtitle.c_str(),
                      MB_OK | MB_ICONERROR | MB_SETFOREGROUND);
#else
        std::fprintf(stderr, "[desktop] unhandled exception: %s\n", e.what());
#endif
        return 1;
    } catch (...) {
        LOG_ERROR("[desktop] unhandled non-std::exception during startup");
#ifdef _WIN32
        const std::string locale = acecode::desktop::native_locale();
        const std::wstring wbody = acecode::utf8_to_wide(
            acecode::desktop::format_startup_exception_message({}, locale));
        const std::wstring wtitle = acecode::utf8_to_wide(std::string(
            acecode::desktop::desktop_string(
                acecode::desktop::DesktopStringId::StartupFailedTitle, locale)));
        ::MessageBoxW(nullptr,
                      wbody.c_str(),
                      wtitle.c_str(),
                      MB_OK | MB_ICONERROR | MB_SETFOREGROUND);
#else
        std::fprintf(stderr, "[desktop] unhandled non-std::exception during startup\n");
#endif
        return 1;
    }
}