server_helpers.cpp

// server_helpers.cpp — Shared helper method definitions for WebServer::Impl.
// This file contains auth/CORS, workspace, session serialization, attention,
// session draft/title/todo, and session-options helpers that are used by
// multiple route TUs.

#include "server_impl.hpp"
#include "remote_control_session_event.hpp"
#include "session_status_routing.hpp"
#include "../config/saved_models_revision.hpp"
#include "../prompt/context_usage_breakdown.hpp"
#include "../session/session_user_message_search.hpp"
#include "../utils/encoding.hpp"

namespace acecode::web {

using nlohmann::json;

// =====================================================================
// Free functions (formerly anonymous-namespace, now shared across route TUs)
// =====================================================================

std::uint64_t parse_seq(const std::string& s) {
    if (s.empty()) return 0;
    try { return std::stoull(s); } catch (...) { return 0; }
}

std::string trim_trailing_slash(std::string value) {
    while (!value.empty() && value.back() == '/') value.pop_back();
    return value;
}

std::optional<std::string> preview_blob_mime(const std::string& path) {
    auto dot = path.find_last_of('.');
    if (dot == std::string::npos || dot + 1 >= path.size()) return std::nullopt;
    std::string ext = path.substr(dot + 1);
    std::transform(ext.begin(), ext.end(), ext.begin(), [](unsigned char c) {
        return static_cast<char>(std::tolower(c));
    });
    if (ext == "png")  return "image/png";
    if (ext == "jpg" || ext == "jpeg") return "image/jpeg";
    if (ext == "gif")  return "image/gif";
    if (ext == "webp") return "image/webp";
    if (ext == "bmp")  return "image/bmp";
    if (ext == "ico")  return "image/x-icon";
    if (ext == "svg")  return "image/svg+xml";
    if (ext == "pdf")  return "application/pdf";
    if (ext == "docx") return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
    if (ext == "xlsx") return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
    if (ext == "xlsm") return "application/vnd.ms-excel.sheet.macroEnabled.12";
    if (ext == "pptx") return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
    return std::nullopt;
}

std::int64_t now_unix_ms() {
    using namespace std::chrono;
    return duration_cast<milliseconds>(
        system_clock::now().time_since_epoch()).count();
}

bool cwd_is_directory(const std::string& cwd) {
    if (cwd.empty()) return false;
    std::error_code ec;
#ifdef _WIN32
    return std::filesystem::is_directory(std::filesystem::u8path(cwd), ec) && !ec;
#else
    return std::filesystem::is_directory(cwd, ec) && !ec;
#endif
}

json chat_message_to_json(const ChatMessage& m) {
    return chat_message_to_payload_json(m);
}

json ui_preferences_to_json(const WebUiPreferencesConfig& cfg) {
    return json{
        {"show_acecode_avatar", false},
        {"theme", cfg.theme},
        {"color_theme", cfg.color_theme},
        {"font_size", cfg.font_size},
    };
}

json upgrade_config_to_json(const UpgradeConfig& cfg) {
    return json{{"base_url", normalize_upgrade_base_url(cfg.base_url)}};
}

json update_check_to_json(const acecode::upgrade::UpdateCheckResult& result) {
    json out = {
        {"status", acecode::upgrade::update_check_status_name(result.status)},
        {"update_available", result.update_available()},
        {"current_version", result.current_version},
        {"latest_version", result.latest_version},
        {"target", result.target},
        {"manifest_url", result.manifest_url},
    };
    out["releases"] = json::array();
    for (const auto& release : result.releases) {
        out["releases"].push_back({
            {"version", release.version},
            {"published_at", release.published_at},
            {"notes", release.notes},
        });
    }
    if (!result.package_file.empty()) out["package_file"] = result.package_file;
    if (!result.package_url.empty()) out["package_url"] = result.package_url;
    if (result.package_size) out["package_size"] = *result.package_size;
    if (result.http_status != 0) out["http_status"] = result.http_status;
    if (!result.error.empty()) out["error"] = result.error;
    return out;
}

json custom_instructions_to_json(const CustomInstructionsConfig& cfg) {
    return json{{"text", cfg.text_snapshot()}};
}

bool has_non_whitespace(const std::string& value) {
    return std::any_of(value.begin(), value.end(), [](unsigned char c) {
        return !std::isspace(c);
    });
}

std::string json_string_field(const json& object, const char* key) {
    if (!object.is_object() || !object.contains(key) || !object[key].is_string()) {
        return {};
    }
    return object[key].get<std::string>();
}

int json_positive_int_field(const json& object, const char* key) {
    if (!object.is_object() || !object.contains(key)) return 0;
    const auto& value = object[key];
    if (value.is_number_integer()) {
        const int number = value.get<int>();
        return number > 0 ? number : 0;
    }
    if (value.is_number_unsigned()) {
        const auto number = value.get<unsigned int>();
        return number > 0 ? static_cast<int>(number) : 0;
    }
    return 0;
}

std::optional<std::int64_t> json_nonnegative_int_field(const json& object,
                                                       const char* key) {
    if (!object.is_object() || !object.contains(key)) return std::nullopt;
    const auto& value = object[key];
    if (value.is_number_unsigned()) {
        const auto number = value.get<std::uint64_t>();
        if (number <= static_cast<std::uint64_t>(
                std::numeric_limits<std::int64_t>::max())) {
            return static_cast<std::int64_t>(number);
        }
    } else if (value.is_number_integer()) {
        const auto number = value.get<std::int64_t>();
        if (number >= 0) return number;
    }
    return std::nullopt;
}

std::string truncate_selection_context_text(std::string text) {
    if (text.size() <= kMaxSelectionContextChars) return text;
    text = truncate_utf8_prefix(text, kMaxSelectionContextChars, "");
    text += "\n[Selection truncated]";
    return text;
}

std::string truncate_selection_anchor_text(std::string text) {
    std::string normalized;
    normalized.reserve(text.size());
    for (std::size_t i = 0; i < text.size(); ++i) {
        if (text[i] == '\r') {
            normalized.push_back('\n');
            if (i + 1 < text.size() && text[i + 1] == '\n') ++i;
        } else {
            normalized.push_back(text[i]);
        }
    }
    if (normalized.size() > kMaxSelectionContextChars) {
        normalized =
            truncate_utf8_prefix(normalized, kMaxSelectionContextChars, "");
    }
    return normalized;
}

std::string truncate_selection_annotation_text(std::string text) {
    if (text.size() <= kMaxSelectionAnnotationChars) return text;
    text = truncate_utf8_prefix(text, kMaxSelectionAnnotationChars, "");
    text += "\n[Annotation truncated]";
    return text;
}

json sanitized_selection_annotations(const json& ctx) {
    constexpr std::size_t kMaxAnnotationIdBytes = 256;
    constexpr std::size_t kMaxAnnotationTimestampBytes = 64;
    json annotations = json::array();
    if (!ctx.is_object() || !ctx.contains("annotations") ||
        !ctx["annotations"].is_array()) {
        return annotations;
    }

    std::unordered_set<std::string> seen_ids;
    std::size_t fallback_id = 0;
    for (const auto& raw : ctx["annotations"]) {
        if (annotations.size() >= kMaxSelectionAnnotations) break;
        if (!raw.is_object()) continue;
        std::string text =
            truncate_selection_annotation_text(json_string_field(raw, "text"));
        if (!has_non_whitespace(text)) continue;

        std::string id = truncate_utf8_prefix(
            json_string_field(raw, "id"), kMaxAnnotationIdBytes, "");
        if (!has_non_whitespace(id)) {
            id = "annotation-" + std::to_string(++fallback_id);
        }
        if (!seen_ids.insert(id).second) continue;

        json annotation{{"id", id}, {"text", std::move(text)}};
        const std::string created_at = truncate_utf8_prefix(
            json_string_field(raw, "created_at"),
            kMaxAnnotationTimestampBytes,
            "");
        if (has_non_whitespace(created_at)) {
            annotation["created_at"] = created_at;
        }
        annotations.push_back(std::move(annotation));
    }
    return annotations;
}

std::string selection_line_suffix(const json& source) {
    const int start = json_positive_int_field(source, "start_line");
    const int end = json_positive_int_field(source, "end_line");
    if (start <= 0) return {};
    if (end <= 0 || end == start) return ":" + std::to_string(start);
    return ":" + std::to_string(start) + "-" + std::to_string(end);
}

std::optional<json> sanitized_selection_context_meta(const json& ctx) {
    constexpr std::size_t kMaxContentRevisionBytes = 128;
    if (!ctx.is_object() || json_string_field(ctx, "type") != "selection") {
        return std::nullopt;
    }
    const std::string text = json_string_field(ctx, "text");
    if (!has_non_whitespace(text)) return std::nullopt;

    json source = json::object();
    if (ctx.contains("source") && ctx["source"].is_object()) {
        const auto& raw_source = ctx["source"];
        const std::string path = json_string_field(raw_source, "path");
        const std::string kind = json_string_field(raw_source, "kind");
        if (!path.empty()) source["path"] = path;
        if (!kind.empty()) source["kind"] = kind;
        const int start = json_positive_int_field(raw_source, "start_line");
        const int end = json_positive_int_field(raw_source, "end_line");
        const int line_count = json_positive_int_field(raw_source, "line_count");
        if (start > 0) source["start_line"] = start;
        if (end > 0) source["end_line"] = end;
        if (line_count > 0) source["line_count"] = line_count;
        const std::string view = json_string_field(raw_source, "view");
        if (view == "source" || view == "rendered") source["view"] = view;
        const auto start_offset =
            json_nonnegative_int_field(raw_source, "start_offset");
        const auto end_offset =
            json_nonnegative_int_field(raw_source, "end_offset");
        if (start_offset.has_value() && end_offset.has_value() &&
            *end_offset > *start_offset) {
            source["start_offset"] = *start_offset;
            source["end_offset"] = *end_offset;
        }
        const std::string content_revision = truncate_utf8_prefix(
            json_string_field(raw_source, "content_revision"),
            kMaxContentRevisionBytes,
            "");
        if (has_non_whitespace(content_revision)) {
            source["content_revision"] = content_revision;
        }
    }

    json meta = json::object();
    meta["type"] = "selection";
    const std::string id = json_string_field(ctx, "id");
    const std::string label = json_string_field(ctx, "label");
    const std::string note = json_string_field(ctx, "note");
    if (!id.empty()) meta["id"] = id;
    if (!label.empty()) meta["label"] = label;
    if (!note.empty()) meta["note"] = note;
    if (!source.empty()) meta["source"] = std::move(source);
    std::string selected_text = json_string_field(ctx, "selected_text");
    if (!has_non_whitespace(selected_text)) selected_text = text;
    selected_text = truncate_selection_anchor_text(std::move(selected_text));
    if (has_non_whitespace(selected_text)) {
        meta["selected_text"] = std::move(selected_text);
    }
    json annotations = sanitized_selection_annotations(ctx);
    if (!annotations.empty()) meta["annotations"] = std::move(annotations);
    return meta;
}

SelectionPromptContext build_selection_prompt_context(const json& contexts) {
    SelectionPromptContext out;
    if (!contexts.is_array()) return out;

    std::ostringstream body;
    int count = 0;
    for (const auto& ctx : contexts) {
        auto meta = sanitized_selection_context_meta(ctx);
        if (!meta.has_value()) continue;
        std::string text = truncate_selection_context_text(json_string_field(ctx, "text"));
        if (!has_non_whitespace(text)) continue;

        ++count;
        out.meta.push_back(*meta);
        const json source = meta->contains("source") && (*meta)["source"].is_object()
            ? (*meta)["source"]
            : json::object();
        std::string source_label = json_string_field(source, "path");
        if (!source_label.empty()) {
            source_label += selection_line_suffix(source);
        } else {
            source_label = json_string_field(*meta, "label");
        }
        body << "[selection " << count << "]\n";
        if (!source_label.empty()) {
            body << "Source: " << source_label << "\n";
        }
        body << "Text:\n" << text << "\n\n";
        if (meta->contains("annotations") && (*meta)["annotations"].is_array() &&
            !(*meta)["annotations"].empty()) {
            body << "Annotations:\n";
            int annotation_number = 0;
            for (const auto& annotation : (*meta)["annotations"]) {
                const std::string annotation_text =
                    json_string_field(annotation, "text");
                if (!has_non_whitespace(annotation_text)) continue;
                body << ++annotation_number << ". " << annotation_text << "\n";
            }
            body << "\n";
        }
    }

    if (count > 0) {
        out.prompt =
            "The user pinned the following selected text as reference context. "
            "Use it when it is relevant to the request.\n\n" + body.str();
    }
    return out;
}

std::string build_selection_augmented_prompt(const SelectionPromptContext& selection,
                                              const std::string& original_text) {
    std::ostringstream out;
    out << selection.prompt << "User request:\n";
    if (original_text.empty()) {
        out << "(no additional typed prompt)";
    } else {
        out << original_text;
    }
    return out.str();
}

json session_event_to_json(const SessionEvent& evt,
                            const std::string& session_id,
                            const std::string& workspace_hash,
                            const std::string& cwd) {
    json msg;
    msg["type"]         = to_string(evt.kind);
    msg["seq"]          = evt.seq;
    msg["timestamp_ms"] = evt.timestamp_ms;
    msg["payload"]      = evt.payload;
    if (!session_id.empty()) {
        msg["session_id"] = session_id;
        if (msg["payload"].is_object() && !msg["payload"].contains("session_id")) {
            msg["payload"]["session_id"] = session_id;
        }
    }
    if (!workspace_hash.empty()) {
        msg["workspace_hash"] = workspace_hash;
        if (msg["payload"].is_object() && !msg["payload"].contains("workspace_hash")) {
            msg["payload"]["workspace_hash"] = workspace_hash;
        }
    }
    if (!cwd.empty()) {
        if (msg["payload"].is_object() && !msg["payload"].contains("cwd")) {
            msg["payload"]["cwd"] = cwd;
        }
    }
    return msg;
}

void log_unauthorized(const std::string& path,
                       const std::string& client_ip,
                       const char* reason) {
    LOG_WARN(std::string("[web] 401 ") + reason + " path=" + path
             + " client_ip=" + client_ip);
}

bool is_loopback_origin(const std::string& origin) {
    return origin.rfind("http://127.0.0.1:", 0) == 0 ||
           origin.rfind("http://localhost:", 0) == 0 ||
           origin.rfind("http://[::1]:", 0) == 0 ||
           origin.rfind("https://127.0.0.1:", 0) == 0 ||
           origin.rfind("https://localhost:", 0) == 0 ||
           origin.rfind("https://[::1]:", 0) == 0;
}

std::string ascii_lower(std::string s) {
    std::transform(s.begin(), s.end(), s.begin(), [](unsigned char c) {
        return static_cast<char>(std::tolower(c));
    });
    return s;
}

bool is_loopback_host(const std::string& host) {
    auto h = ascii_lower(host);
    return h == "localhost" || h == "::1" ||
           h == "127.0.0.1" ||
           (h.size() > 4 && h.substr(0, 4) == "127.");
}

bool is_same_request_origin(const crow::request& req,
                             const std::string& origin) {
    auto host = req.get_header_value("Host");
    if (host.empty()) return false;
    if (origin == ("http://" + host) || origin == ("https://" + host)) {
        return true;
    }

    auto o = parse_origin(origin);
    auto h = split_host_port(host);
    if (h.port.empty()) h.port = (o.scheme == "https") ? "443" : "80";
    return !o.host.empty() && !h.host.empty() &&
           o.port == h.port &&
           is_loopback_host(o.host) &&
           is_loopback_host(h.host);
}

AuthResult check_explicit_token(std::string_view server_token,
                                 std::string_view header_token,
                                 std::string_view query_token) {
    if (header_token.empty() && query_token.empty()) return AuthResult::NoToken;
    if (!server_token.empty() &&
        (header_token == server_token || query_token == server_token)) {
        return AuthResult::Allowed;
    }
    return AuthResult::BadToken;
}

// =====================================================================
// Impl member helpers — Auth
// =====================================================================

AuthResult WebServer::Impl::auth_result_for_request(const crow::request& req,
                                                      const std::string& header_token,
                                                      const std::string& query_token) const {
    auto origin = req.get_header_value("Origin");
    if (!origin.empty() && !is_same_request_origin(req, origin)) {
        if (!is_loopback_origin(origin)) return AuthResult::BadToken;
        return check_explicit_token(deps.token, header_token, query_token);
    }
    return check_request_auth(req.remote_ip_address, deps.token,
                              header_token, query_token);
}

std::optional<crow::response> WebServer::Impl::require_auth(const crow::request& req) {
    std::string header_token;
    auto h = req.get_header_value("X-ACECode-Token");
    if (!h.empty()) header_token = h;
    std::string query_token;
    auto qt = req.url_params.get("token");
    if (qt) query_token = qt;

    auto result = auth_result_for_request(req, header_token, query_token);
    if (result == AuthResult::Allowed) return std::nullopt;

    const char* reason = (result == AuthResult::NoToken)
                          ? "no token" : "bad token";
    log_unauthorized(req.url, req.remote_ip_address, reason);
    crow::response resp(401);
    resp.add_header("Content-Type", "application/json");
    resp.body = json{{"error", reason}}.dump();
    add_cors(req, resp);
    return resp;
}

void WebServer::Impl::add_cors(const crow::request& req, crow::response& resp) {
    std::string origin = req.get_header_value("Origin");
    if (origin.empty() || !is_loopback_origin(origin)) return;
    resp.add_header("Access-Control-Allow-Origin", origin);
    resp.add_header("Vary", "Origin");
    resp.add_header("Access-Control-Allow-Credentials", "false");
    resp.add_header("Access-Control-Allow-Headers", "Content-Type, X-ACECode-Token");
    resp.add_header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
}

crow::response WebServer::Impl::with_cors(const crow::request& req, crow::response resp) {
    add_cors(req, resp);
    return resp;
}

crow::response WebServer::Impl::cors_preflight(const crow::request& req) {
    crow::response r(204);
    add_cors(req, r);
    return r;
}

// =====================================================================
// Impl member helpers — Workspace
// =====================================================================

std::string WebServer::Impl::projects_dir() const {
    if (!deps.projects_dir.empty()) return deps.projects_dir;
    return path_to_utf8(path_from_utf8(get_acecode_dir()) / "projects");
}

std::string WebServer::Impl::no_workspace_cache_root() const {
    return deps.no_workspace_cache_root.empty()
        ? default_no_workspace_cache_root()
        : deps.no_workspace_cache_root;
}

acecode::desktop::WorkspaceMeta WebServer::Impl::compatibility_workspace() const {
    acecode::desktop::WorkspaceMeta m;
    m.cwd = deps.cwd;
    m.hash = compute_cwd_hash(deps.cwd);
    m.name = acecode::desktop::default_workspace_name(deps.cwd);
    return m;
}

std::optional<acecode::desktop::WorkspaceMeta> WebServer::Impl::resolve_workspace(const std::string& hash) const {
    if (hash == "__local__") return compatibility_workspace();
    if (deps.workspace_registry) {
        if (auto m = deps.workspace_registry->get(hash)) {
            return m;
        }
    } else {
        auto compat = compatibility_workspace();
        if (hash == compat.hash) return compat;
    }

    // Registry membership means "visible in Desktop", not "valid session
    // workspace". Fall back to the exact persisted project directory without
    // registering it or changing desktop_visible. Restrict the path component
    // to the canonical 16-hex hash format before touching disk.
    const bool safe_hash = hash.size() == 16 &&
        std::all_of(hash.begin(), hash.end(), [](unsigned char c) {
            return (c >= '0' && c <= '9') ||
                   (c >= 'a' && c <= 'f') ||
                   (c >= 'A' && c <= 'F');
        });
    if (!safe_hash) return std::nullopt;

    if (auto persisted = acecode::desktop::load_workspace_metadata(
            projects_dir(), hash)) {
        if (acecode::desktop::workspace_hash_matches_cwd(hash, persisted->cwd)) {
            return persisted;
        }
    }

    const std::string project_dir = path_to_utf8(
        path_from_utf8(projects_dir()) / hash);
    try {
        for (const auto& meta : SessionStorage::list_session_metadata(project_dir)) {
            if (meta.no_workspace || meta.cwd.empty()) continue;
            if (!acecode::desktop::workspace_hash_matches_cwd(hash, meta.cwd)) {
                continue;
            }
            acecode::desktop::WorkspaceMeta inferred;
            inferred.hash = hash;
            inferred.cwd = meta.cwd;
            inferred.name = acecode::desktop::default_workspace_name(meta.cwd);
            inferred.desktop_visible = false;
            return inferred;
        }
    } catch (const std::exception& e) {
        LOG_WARN("[web] hidden workspace metadata scan failed for " + hash +
                 ": " + e.what());
    }
    return std::nullopt;
}

bool WebServer::Impl::archived_query_requested(const crow::request& req) const {
    auto raw = req.url_params.get("archived");
    if (!raw) return false;
    const std::string value = ascii_lower(raw);
    return value == "1" || value == "true" || value == "yes";
}

UsageLedgerQuery WebServer::Impl::usage_query_from_request(const crow::request& req) const {
    UsageLedgerQuery query;
    if (auto raw_days = req.url_params.get("days")) {
        try {
            query.days = std::stoi(raw_days);
        } catch (...) {
            query.days = 30;
        }
    }
    if (auto raw_workspace = req.url_params.get("workspace")) {
        query.workspace_hash = raw_workspace;
    }
    if (auto raw_tz = req.url_params.get("timezone_offset_minutes")) {
        try {
            query.timezone_offset_minutes = std::clamp(std::stoi(raw_tz), -1440, 1440);
        } catch (...) {
            query.timezone_offset_minutes = 0;
        }
    }
    return query;
}

std::vector<UsageLedgerScope> WebServer::Impl::usage_scopes_for_request(
    const std::string& workspace_hash) const {
    std::vector<UsageLedgerScope> scopes;
    std::unordered_set<std::string> seen;
    auto add = [&](const acecode::desktop::WorkspaceMeta& ws) {
        if (!workspace_hash.empty() &&
            workspace_hash != "__local__" &&
            ws.hash != workspace_hash) {
            return;
        }
        if (ws.hash.empty() || seen.count(ws.hash)) return;
        seen.insert(ws.hash);
        scopes.push_back(UsageLedgerScope{
            SessionStorage::get_project_dir(ws.cwd),
            ws.hash,
            ws.name.empty() ? acecode::desktop::default_workspace_name(ws.cwd) : ws.name,
            ws.cwd,
        });
    };

    if (workspace_hash == "__local__") {
        add(compatibility_workspace());
        return scopes;
    }

    add(compatibility_workspace());
    if (deps.workspace_registry) {
        deps.workspace_registry->scan(projects_dir());
        for (const auto& ws : deps.workspace_registry->list()) {
            add(ws);
        }
    }
    return scopes;
}

std::vector<std::string> WebServer::Impl::allowed_file_cwds() const {
    std::vector<std::string> out;
    std::unordered_set<std::string> seen;
    auto add = [&](const std::string& cwd) {
        if (cwd.empty() || seen.count(cwd)) return;
        seen.insert(cwd);
        out.push_back(cwd);
    };

    add(deps.cwd);
    if (deps.workspace_registry) {
        for (const auto& m : deps.workspace_registry->list()) {
            add(m.cwd);
        }
    }
    if (deps.session_registry) {
        for (const auto& session : deps.session_registry->list_active()) {
            // A session's own cwd is a legitimate file root: it is where that
            // session's tools already read and write. no-workspace sessions live
            // under <data_dir>/cache/no-workspace/<id> and belong to no registered
            // workspace, so without this they matched nothing in the allow list and
            // every preview request came back 400 — files the agent had just
            // created in that very directory were unopenable.
            add(session.cwd);
            add(session.worktree_path);
        }
    }
    return out;
}

json WebServer::Impl::workspace_to_json(const acecode::desktop::WorkspaceMeta& m) const {
    json o;
    o["hash"] = m.hash;
    o["cwd"] = m.cwd;
    o["name"] = m.name;
    o["available"] = cwd_is_directory(m.cwd);
    return o;
}

// =====================================================================
// Impl member helpers — Session serialization
// =====================================================================

bool WebServer::Impl::token_usage_has_values(const TokenUsage& usage) {
    return usage.has_data ||
           usage.prompt_tokens != 0 ||
           usage.completion_tokens != 0 ||
           usage.total_tokens != 0 ||
           usage.cache_read_tokens != 0 ||
           usage.cache_write_tokens != 0 ||
           usage.reasoning_tokens != 0 ||
           usage.context_breakdown.has_data;
}

json WebServer::Impl::token_usage_to_json(const TokenUsage& usage) {
    json value = {
        {"prompt_tokens", usage.prompt_tokens},
        {"completion_tokens", usage.completion_tokens},
        {"total_tokens", usage.total_tokens},
        {"cache_read_tokens", usage.cache_read_tokens},
        {"cache_write_tokens", usage.cache_write_tokens},
        {"reasoning_tokens", usage.reasoning_tokens},
        {"has_data", usage.has_data},
    };
    if (usage.context_breakdown.has_data) {
        value["context_breakdown"] =
            context_usage_breakdown_to_json(usage.context_breakdown);
    }
    return value;
}

json WebServer::Impl::token_usage_or_null(const TokenUsage& usage) {
    return token_usage_has_values(usage) ? token_usage_to_json(usage) : json(nullptr);
}

bool WebServer::Impl::session_model_deleted(const std::string& model_name) const {
    if (model_name.empty() || model_name.rfind("(session:", 0) == 0 || !deps.app_config) {
        return false;
    }
    std::shared_lock<std::shared_mutex> config_lock(app_config_mu);
    for (const auto& entry : deps.app_config->saved_models) {
        if (entry.name == model_name) return false;
    }
    return true;
}

namespace {

void append_worktree_session(json& target, const WorktreeSessionInfo& worktree) {
    if (!worktree.active()) return;
    target["worktree"] = {
        {"name", worktree.worktree_name},
        {"branch", worktree.worktree_branch},
        {"path", worktree.worktree_path},
    };
}

void append_loop_execution(json& target,
                           const std::string& loop_id,
                           const std::string& loop_run_id) {
    if (loop_id.empty()) return;
    target["loop_execution"] = {
        {"loop_id", loop_id},
        {"run_id", loop_run_id},
    };
}

std::string existing_session_jsonl_path(const std::string& cwd,
                                        const std::string& session_id) {
    if (cwd.empty() || session_id.empty()) return {};
    const std::string path = SessionStorage::session_path(
        SessionStorage::get_project_dir(cwd), session_id);
    std::error_code ec;
    if (!std::filesystem::is_regular_file(path_from_utf8(path), ec) || ec) {
        return {};
    }
    return path;
}

} // namespace

json WebServer::Impl::session_info_to_json(const SessionInfo& s, const SessionMeta* m) const {
    json o;
    const std::string model_name =
        !s.model_name.empty() ? s.model_name : (m ? m->model_preset : "");
    const bool model_deleted = s.model_deleted || session_model_deleted(model_name);
    const bool no_workspace = s.no_workspace || (m && m->no_workspace);
    const std::string workspace_hash = no_workspace
        ? std::string{}
        : (!s.workspace_hash.empty() ? s.workspace_hash : (m ? compute_cwd_hash(m->cwd) : ""));
    const std::string storage_cwd = !s.cwd.empty() ? s.cwd : (m ? m->cwd : "");
    const std::string cwd = no_workspace ? std::string{} : storage_cwd;
    o["id"]            = s.id;
    o["active"]        = true;
    o["status"]        = s.busy ? "running" : "idle";
    if (!s.active_turn_id.empty()) {
        o["active_turn_id"] = s.active_turn_id;
    }
    o["workspace_hash"] = workspace_hash;
    o["cwd"]           = cwd;
    // `cwd` stays empty for no-workspace sessions because callers treat it as the
    // workspace binding. File preview needs the real directory regardless of
    // workspace membership, so it is published separately instead of overloading
    // `cwd` and disturbing workspace attribution.
    o["working_cwd"]   = storage_cwd;
    o["session_path"]  = existing_session_jsonl_path(storage_cwd, s.id);
    o["no_workspace"]  = no_workspace;
    // A user rename persisted by another process (Desktop keeps one daemon per
    // workspace, and only the active one serves the UI) leaves this daemon's
    // in-memory title stale. The disk snapshot is read after list_active(), so
    // a persisted user title is authoritative even when the live copy already
    // carries an older user title from an earlier rename.
    const bool meta_user_title =
        m && (m->title_source == "user" || m->title_source == "user-cleared");
    if (meta_user_title) {
        o["title"]        = m->title;
        o["title_source"] = m->title_source;
    } else {
        o["title"]        = !s.title.empty() ? s.title : (m ? m->title : "");
        o["title_source"] = !s.title_source.empty()
            ? s.title_source
            : (m ? m->title_source : "");
    }
    o["summary"]       = !s.summary.empty() ? s.summary : (m ? m->summary : "");
    o["created_at"]    = !s.created_at.empty() ? s.created_at : (m ? m->created_at : "");
    o["updated_at"]    = !s.updated_at.empty() ? s.updated_at : (m ? m->updated_at : "");
    o["provider"]      = model_deleted ? "" : (!s.provider.empty() ? s.provider : (m ? m->provider : ""));
    o["model"]         = model_deleted ? "" : (!s.model.empty() ? s.model : (m ? m->model : ""));
    o["model_name"]    = model_name;
    o["model_preset"]  = o["model_name"];
    o["context_window"] = s.context_window;
    o["deleted"]       = model_deleted;
    o["message_count"] = s.message_count > 0 ? s.message_count : (m ? m->message_count : 0);
    o["turn_count"]    = s.turn_count > 0 ? s.turn_count : (m ? m->turn_count : 0);
    o["permission_mode"] = !s.permission_mode.empty()
        ? s.permission_mode
        : (m ? m->permission_mode : "default");
    o["token_usage"] = token_usage_or_null(
        token_usage_has_values(s.last_token_usage)
            ? s.last_token_usage
            : (m ? m->last_token_usage : TokenUsage{}));
    o["session_token_usage"] = token_usage_or_null(
        token_usage_has_values(s.session_token_usage)
            ? s.session_token_usage
            : (m ? m->session_token_usage : TokenUsage{}));
    WorktreeSessionInfo worktree = m ? m->worktree : WorktreeSessionInfo{};
    if (!s.worktree_path.empty()) {
        worktree.worktree_path = s.worktree_path;
        if (!s.worktree_name.empty()) worktree.worktree_name = s.worktree_name;
        if (!s.worktree_branch.empty()) worktree.worktree_branch = s.worktree_branch;
    }
    append_worktree_session(o, worktree);
    if (m) {
        append_loop_execution(o, m->loop_id, m->loop_run_id);
    }
    if (!o.contains("loop_execution") && deps.session_registry) {
        if (auto entry = deps.session_registry->acquire(s.id);
            entry && entry->loop_execution) {
            append_loop_execution(o, entry->loop_id, entry->loop_run_id);
        }
    }
    if (m && !m->todos.empty()) {
        o["todos"] = todo_items_to_json(m->todos);
        o["todo_summary"] = todo_summary_to_json(m->todos);
    }
    o["archived"]      = m ? m->archived : false;
    o["parent_session_id"] = !s.parent_session_id.empty()
        ? s.parent_session_id
        : (m ? m->parent_session_id : std::string{});
    const std::string expert_id = !s.expert_id.empty()
        ? s.expert_id : (m ? m->expert_id : std::string{});
    const std::string expert_member_id = !s.expert_member_id.empty()
        ? s.expert_member_id : (m ? m->expert_member_id : std::string{});
    o["expert_id"] = expert_id;
    o["expert_member_id"] = expert_member_id;
    if (!expert_id.empty()) {
        json expert_json = {
            {"id", expert_id},
            {"member_id", expert_member_id},
            {"missing", s.expert_missing},
        };
        if (!s.expert_display_name.empty()) {
            expert_json["display_name"] = s.expert_display_name;
            expert_json["type"] = s.expert_type;
            expert_json["source"] = s.expert_source;
        } else if (deps.expert_registry && m) {
            if (auto resolved = deps.expert_registry->find(m->cwd, expert_id)) {
                expert_json["display_name"] = resolved->display_name;
                expert_json["type"] = to_string(resolved->type);
                expert_json["source"] = resolved->source;
                expert_json["missing"] = false;
            } else {
                expert_json["missing"] = true;
            }
        }
        o["expert"] = std::move(expert_json);
    }
    append_attention_fields(o, s.id, workspace_hash, cwd, s.busy);
    return o;
}

json WebServer::Impl::session_meta_to_json(const SessionMeta& m, const std::string& workspace_hash) const {
    json o;
    const bool model_deleted = session_model_deleted(m.model_preset);
    const std::string effective_workspace_hash = m.no_workspace ? std::string{} : workspace_hash;
    const std::string effective_cwd = m.no_workspace ? std::string{} : m.cwd;
    o["id"]             = m.id;
    o["active"]         = false;
    o["status"]         = "idle";
    o["workspace_hash"] = effective_workspace_hash;
    o["cwd"]            = effective_cwd;
    o["session_path"]   = existing_session_jsonl_path(m.cwd, m.id);
    o["no_workspace"]   = m.no_workspace;
    o["title"]          = m.title;
    o["title_source"]   = m.title_source;
    o["summary"]        = m.summary;
    o["created_at"]     = m.created_at;
    o["updated_at"]     = m.updated_at;
    o["provider"]       = model_deleted ? "" : m.provider;
    o["model"]          = model_deleted ? "" : m.model;
    o["model_name"]     = m.model_preset;
    o["model_preset"]   = m.model_preset;
    o["deleted"]        = model_deleted;
    o["message_count"]  = m.message_count;
    o["turn_count"]     = m.turn_count;
    o["permission_mode"] = m.permission_mode.empty() ? "default" : m.permission_mode;
    o["token_usage"] = token_usage_or_null(m.last_token_usage);
    o["session_token_usage"] = token_usage_or_null(m.session_token_usage);
    // 会话的 worktree 状态(add-webui-git-session-pill):前端 pill 与侧栏
    // 据此恢复只读状态。inactive 时省略字段。
    append_worktree_session(o, m.worktree);
    append_loop_execution(o, m.loop_id, m.loop_run_id);
    if (!m.todos.empty()) {
        o["todos"] = todo_items_to_json(m.todos);
        o["todo_summary"] = todo_summary_to_json(m.todos);
    }
    o["archived"]       = m.archived;
    o["parent_session_id"] = m.parent_session_id;
    o["expert_id"] = m.expert_id;
    o["expert_member_id"] = m.expert_member_id;
    if (!m.expert_id.empty()) {
        json expert_json = {
            {"id", m.expert_id},
            {"member_id", m.expert_member_id},
            {"missing", true},
        };
        if (deps.expert_registry) {
            if (auto resolved = deps.expert_registry->find(m.cwd, m.expert_id)) {
                expert_json["display_name"] = resolved->display_name;
                expert_json["type"] = to_string(resolved->type);
                expert_json["source"] = resolved->source;
                expert_json["missing"] = false;
            }
        }
        o["expert"] = std::move(expert_json);
    }
    append_attention_fields(o, m.id, effective_workspace_hash, effective_cwd, false);
    return o;
}

void WebServer::Impl::append_session_runtime_snapshot(json& wrapper,
                                                        const std::string& session_id) const {
    if (session_id.empty()) return;
    SessionMeta meta;
    bool have_meta = false;
    if (deps.session_registry) {
        if (auto entry = deps.session_registry->acquire(session_id)) {
            if (entry->no_workspace) {
                wrapper["no_workspace"] = true;
                wrapper["workspace_hash"] = "";
                wrapper["cwd"] = "";
            }
            if (entry->loop) {
                wrapper["busy"] = entry->loop->is_busy();
                const std::string active_turn_id =
                    entry->loop->active_turn_id();
                if (!active_turn_id.empty()) {
                    wrapper["active_turn_id"] = active_turn_id;
                }
            }
            if (entry->sm) {
                meta = entry->sm->load_session_meta(session_id);
                have_meta = !meta.id.empty();
                wrapper["turn_count"] = entry->sm->current_turn_count();
                wrapper["permission_mode"] = entry->sm->current_permission_mode();
                wrapper["token_usage"] = token_usage_or_null(entry->sm->current_last_token_usage());
                wrapper["session_token_usage"] =
                    token_usage_or_null(entry->sm->current_session_token_usage());
                auto todos = entry->sm->current_todos();
                if (!todos.empty()) {
                    wrapper["todos"] = todo_items_to_json(todos);
                    wrapper["todo_summary"] = todo_summary_to_json(todos);
                }
            }
        }
    }

    if (!have_meta) {
        auto project_dir = SessionStorage::get_project_dir(deps.cwd);
        auto meta_path = SessionStorage::meta_path(project_dir, session_id);
        meta = SessionStorage::read_meta(meta_path);
        have_meta = !meta.id.empty();
        if (!have_meta) {
            auto no_workspace_meta = find_no_workspace_session_meta(session_id);
            if (no_workspace_meta.has_value()) {
                meta = *no_workspace_meta;
                have_meta = true;
            }
        }
    }
    if (have_meta) {
        if (meta.no_workspace) {
            wrapper["no_workspace"] = true;
            wrapper["workspace_hash"] = "";
            wrapper["cwd"] = "";
        }
        if (!wrapper.contains("turn_count")) wrapper["turn_count"] = meta.turn_count;
        if (!wrapper.contains("permission_mode")) {
            wrapper["permission_mode"] = meta.permission_mode.empty() ? "default" : meta.permission_mode;
        }
        if (!wrapper.contains("token_usage")) {
            wrapper["token_usage"] = token_usage_or_null(meta.last_token_usage);
        }
        if (!wrapper.contains("session_token_usage")) {
            wrapper["session_token_usage"] = token_usage_or_null(meta.session_token_usage);
        }
        if (!wrapper.contains("todos") && !meta.todos.empty()) {
            wrapper["todos"] = todo_items_to_json(meta.todos);
            wrapper["todo_summary"] = todo_summary_to_json(meta.todos);
        }
    }

    if (!deps.session_registry) return;
    auto entry = deps.session_registry->acquire(session_id);
    if (!entry) return;

    if (entry->sm) {
        if (auto* store = entry->sm->existing_goal_store()) {
            std::string error;
            auto goal = store->get_thread_goal(session_id, &error);
            if (!error.empty()) {
                LOG_WARN("[web] failed to snapshot thread goal: " + error);
            } else {
                wrapper["goal"] = goal.has_value()
                    ? thread_goal_to_json(*goal)
                    : nlohmann::json(nullptr);
            }
        }
    }
}

json WebServer::Impl::sessions_for_workspace(const acecode::desktop::WorkspaceMeta& ws,
                                               bool archived_only,
                                               bool include_no_workspace,
                                               const std::string& parent_filter,
                                               int limit,
                                               SessionListPage* page_out) const {
    std::vector<SessionInfo> active;
    if (deps.session_client) active = deps.session_client->list_sessions();

    const auto project_dir = SessionStorage::get_project_dir(ws.cwd);

    // 子会话过滤:常规列表(parent_filter 空)隐藏所有后台任务子会话;
    // 后台任务查询(parent_filter 非空)只保留指定父会话的子会话。
    const auto parent_mismatch = [&](const std::string& parent_id) {
        if (parent_filter.empty()) return !parent_id.empty();
        return parent_id != parent_filter;
    };

    // 会话 meta 的真实落盘目录恒为 get_project_dir(该会话自己的 cwd)
    // (SessionManager::start_session 就是这么算 project_dir_ 的),不一定等于
    // 调用方 workspace 的 project_dir —— 一个 daemon 经 routes_workspaces
    // 服务多个 workspace 时,进程 cwd ≠ 会话 cwd。用 ws.cwd 去读别的
    // workspace 的会话 meta 只会读到空,created_at/updated_at 随之为空。
    // 顺带治掉 junction 形态差异(C:\Users\x 与 N:\Users\x 哈希不同)。
    const auto session_project_dir = [&](const SessionInfo& s) {
        return s.cwd.empty() ? project_dir : SessionStorage::get_project_dir(s.cwd);
    };

    // 后台任务查询的磁盘枚举同理:子会话跟随父会话归属,已结束的子会话只
    // 存在于父会话所在 workspace 的目录里。父会话就是当前打开的那个会话,
    // 面板可见时它必然是活跃的,从活跃列表里取它的 cwd 即可。
    std::string disk_dir = project_dir;
    if (!parent_filter.empty()) {
        for (const auto& s : active) {
            if (s.id == parent_filter && !s.no_workspace && !s.cwd.empty()) {
                disk_dir = SessionStorage::get_project_dir(s.cwd);
                break;
            }
        }
    }

    // include_no_workspace(/api/sessions 的兼容 workspace)要把 no-workspace
    // 缓存目录一起并进来,那条路径本来就得全量枚举,分页在这里没有意义。
    const bool bounded = limit > 0 && !include_no_workspace;

    // 行先攒成 (updated_at, id, JSON) 再统一排序截断。旧实现是 active 一段、
    // disk 一段各自 push,截断落在拼接顺序上 —— 取出来的前 N 条不保证是
    // 最新的 N 条。
    struct Row {
        std::string updated_at;
        std::string id;
        json body;
    };
    std::vector<Row> rows;
    std::unordered_set<std::string> seen;

    const auto push_row = [&rows](std::string id, json body) {
        Row row;
        row.updated_at = body.value("updated_at", std::string{});
        row.id = std::move(id);
        row.body = std::move(body);
        rows.push_back(std::move(row));
    };

    for (const auto& s : active) {
        if (parent_mismatch(s.parent_session_id)) continue;
        if (parent_filter.empty()) {
            // 常规列表按 workspace 归属过滤;后台任务查询跳过该过滤
            // (子会话跟随父会话归属,包括 no-workspace 父的子会话)。
            if (s.no_workspace) {
                if (!include_no_workspace) continue;
            } else if (s.workspace_hash != ws.hash) {
                continue;
            }
        }
        seen.insert(s.id);
        // 活跃会话是内存里的个位数,逐个点读它自己那一个 .meta.json 就够了。
        // 旧实现为了给它们配 meta 先把整个项目目录读了一遍,上千会话的
        // workspace 里这一步就是列表接口的全部耗时。
        std::optional<SessionMeta> meta;
        if (s.no_workspace) {
            meta = find_no_workspace_session_meta(s.id);
        } else {
            auto disk_meta = SessionStorage::read_meta(
                SessionStorage::meta_path(session_project_dir(s), s.id));
            if (!disk_meta.id.empty()) meta = std::move(disk_meta);
        }
        const bool archived = meta ? meta->archived : false;
        if (archived != archived_only) continue;
        push_row(s.id, session_info_to_json(s, meta ? &*meta : nullptr));
    }
    const std::size_t active_rows = rows.size();

    const auto accept_disk = [&](const SessionMeta& m) {
        if (seen.count(m.id)) return false;
        if (parent_mismatch(m.parent_session_id)) return false;
        if (m.archived != archived_only) return false;
        if (m.no_workspace && !include_no_workspace) return false;
        return true;
    };

    SessionStorage::MetadataPage disk_page;
    if (include_no_workspace) {
        auto metas = SessionStorage::list_session_metadata(disk_dir);
        auto no_workspace_disk = no_workspace_disk_sessions();
        metas.insert(metas.end(), no_workspace_disk.begin(), no_workspace_disk.end());
        disk_page.candidate_files = metas.size();
        for (auto& m : metas) {
            if (!accept_disk(m)) continue;
            disk_page.sessions.push_back(std::move(m));
            ++disk_page.accepted;
        }
    } else {
        disk_page = SessionStorage::list_session_metadata_page(
            disk_dir, bounded ? limit : 0, accept_disk);
    }
    for (auto& m : disk_page.sessions) {
        const std::string hash = m.no_workspace ? std::string{} : ws.hash;
        const std::string id = m.id;
        push_row(id, session_meta_to_json(m, hash));
    }

    std::sort(rows.begin(), rows.end(), [](const Row& a, const Row& b) {
        if (a.updated_at != b.updated_at) return a.updated_at > b.updated_at;
        return a.id > b.id;
    });

    SessionListPage page;
    page.total = active_rows + disk_page.accepted;
    page.total_exact = disk_page.exhausted;
    if (!disk_page.exhausted) {
        // 磁盘侧提前停在了 limit 上,精确总数拿不到。退回目录里的候选文件
        // 数当上界(含归档、子会话、以及已从 active 算过一次的那些)。宁可
        // 偏大:前端据此保留展开入口,点开会走全量拉取。
        page.total = std::max(page.total, disk_page.candidate_files);
    }

    json arr = json::array();
    const std::size_t emit = bounded
        ? std::min(rows.size(), static_cast<std::size_t>(limit))
        : rows.size();
    for (std::size_t i = 0; i < emit; ++i) {
        arr.push_back(std::move(rows[i].body));
    }
    page.has_more = emit < rows.size() || !disk_page.exhausted;

    // Desktop 的 /rc 会话背景以 daemon 持久化绑定为权威。只在锁内快照
    // session id，随后再标注列表，避免序列化每一项时重复持锁，也绝不把
    // remote-control token / channel 配置暴露给前端。
    std::string remote_control_session_id;
    if (deps.app_config) {
        std::shared_lock<std::shared_mutex> config_lock(app_config_mu);
        remote_control_session_id = deps.app_config->remote_control.bound_session_id;
    }
    for (auto& item : arr) {
        item["remote_control_bound"] =
            !remote_control_session_id.empty() &&
            item.value("id", std::string{}) == remote_control_session_id;
    }
    if (page_out) *page_out = page;
    return arr;
}

std::vector<SessionMeta> WebServer::Impl::no_workspace_disk_sessions() const {
    std::vector<SessionMeta> out;
    for (const auto& cwd : list_no_workspace_session_cwds(no_workspace_cache_root())) {
        for (const auto& meta : SessionStorage::list_session_metadata(SessionStorage::get_project_dir(cwd))) {
            if (meta.no_workspace) out.push_back(meta);
        }
    }
    return out;
}

std::optional<SessionMeta>
WebServer::Impl::find_no_workspace_session_meta(const std::string& id) const {
    // 逻辑下沉到 session 层与 remote-control binder 的启动重建共用;
    // 空 cache_root 由被调方回退 default_no_workspace_cache_root()。
    return acecode::find_no_workspace_session_meta(id, deps.no_workspace_cache_root);
}

bool WebServer::Impl::session_entry_matches_workspace(const SessionEntry& entry,
                                                        const acecode::desktop::WorkspaceMeta& ws) const {
    if (entry.no_workspace) return false;
    if (!entry.workspace_hash.empty()) return entry.workspace_hash == ws.hash;
    return entry.cwd == ws.cwd;
}

std::optional<SessionMeta> WebServer::Impl::find_session_meta_for_workspace(
    const acecode::desktop::WorkspaceMeta& ws,
    const std::string& id) const {
    if (id.empty()) return std::nullopt;

    const auto project_dir = SessionStorage::get_project_dir(ws.cwd);
    const auto direct_meta_path = SessionStorage::meta_path(project_dir, id);
    std::error_code ec;
    if (std::filesystem::is_regular_file(path_from_utf8(direct_meta_path), ec)) {
        auto meta = SessionStorage::read_meta(direct_meta_path);
        if (!meta.id.empty()) return meta;
    }

    const auto candidates = SessionStorage::find_session_files(project_dir, id);
    if (!candidates.empty() && !candidates.front().meta_path.empty()) {
        auto meta = SessionStorage::read_meta(candidates.front().meta_path);
        if (!meta.id.empty()) return meta;
    }

    if (auto meta = find_no_workspace_session_meta(id)) {
        return meta;
    }

    if (deps.session_registry) {
        if (auto entry = deps.session_registry->acquire(id)) {
            if (!session_entry_matches_workspace(*entry, ws)) return std::nullopt;
            const auto now = SessionStorage::now_iso8601();
            SessionMeta meta;
            meta.id = id;
            meta.cwd = entry->cwd.empty() ? ws.cwd : entry->cwd;
            meta.created_at = now;
            meta.updated_at = now;
            const auto model_state = entry->model_binding
                ? entry->model_binding->state_snapshot()
                : SessionModelState{};
            meta.provider = model_state.provider;
            meta.model = model_state.model;
            meta.model_preset = model_state.name;
            meta.no_workspace = entry->no_workspace;
            meta.parent_session_id = entry->parent_session_id;
            if (entry->sm) {
                meta.title = entry->sm->current_title();
                meta.title_source = entry->sm->current_title_source();
                meta.input_draft = entry->sm->current_input_draft();
            }
            return meta;
        }
    }

    return std::nullopt;
}

// =====================================================================
// Impl member helpers — Session draft/title/todo/response
// =====================================================================

crow::response WebServer::Impl::set_session_archive_state(
    const crow::request& req,
    const acecode::desktop::WorkspaceMeta& ws,
    const std::string& id,
    bool archived) {
    auto maybe_meta = find_session_meta_for_workspace(ws, id);
    if (!maybe_meta.has_value()) {
        crow::response r(404);
        r.body = R"({"error":"session not found"})";
        r.add_header("Content-Type", "application/json");
        return with_cors(req, std::move(r));
    }

    SessionMeta meta = *maybe_meta;
    if (archived && deps.session_client) {
        deps.session_client->destroy_session(id);
        const auto reread = find_session_meta_for_workspace(ws, id);
        if (reread.has_value()) meta = *reread;
    } else if (!archived && deps.session_registry) {
        if (auto entry = deps.session_registry->acquire(id)) {
            if (session_entry_matches_workspace(*entry, ws) && entry->sm) {
                entry->sm->set_session_archived(false);
                const auto reread = find_session_meta_for_workspace(ws, id);
                if (reread.has_value()) meta = *reread;
            }
        }
    }

    meta.archived = archived;
    const auto project_dir = SessionStorage::get_project_dir(
        meta.no_workspace && !meta.cwd.empty() ? meta.cwd : ws.cwd);
    SessionStorage::write_meta(SessionStorage::meta_path(project_dir, id), meta);
    if (global_session_search) {
        global_session_search->invalidate_project(ws.hash);
    }

    crow::response r(session_meta_to_json(meta, ws.hash).dump());
    r.add_header("Content-Type", "application/json");
    return with_cors(req, std::move(r));
}

crow::response WebServer::Impl::purge_session_data(
    const crow::request& req,
    const acecode::desktop::WorkspaceMeta& ws,
    const std::string& id,
    bool require_archived) {
    const auto error_response = [this, &req](int status, const std::string& message) {
        crow::response r(status);
        r.body = json{{"error", message}}.dump();
        r.add_header("Content-Type", "application/json");
        return with_cors(req, std::move(r));
    };

    const bool valid_id = !id.empty() && id.size() <= 64 &&
        std::all_of(id.begin(), id.end(), [](unsigned char c) {
            return (c >= 'a' && c <= 'z') ||
                   (c >= 'A' && c <= 'Z') ||
                   (c >= '0' && c <= '9') ||
                   c == '_' || c == '-';
        });
    if (!valid_id) {
        return error_response(400, "invalid session id");
    }
    if (!deps.session_client) {
        return error_response(503, "session client unavailable");
    }

    const auto maybe_meta = find_session_meta_for_workspace(ws, id);
    if (!maybe_meta.has_value()) {
        return error_response(404, "session not found");
    }
    const SessionMeta meta = *maybe_meta;
    if (require_archived && !meta.archived) {
        return error_response(409, "session must be archived before permanent deletion");
    }
    if (!require_archived && !meta.archived && meta.parent_session_id.empty()) {
        // Preserve the existing compatibility-route error for active main
        // sessions while allowing archived main sessions through the same
        // explicit ?purge=1 path.
        return error_response(400, "only subagent sessions can be purged");
    }

    if (deps.session_registry) {
        if (auto entry = deps.session_registry->acquire(id)) {
            const bool same_workspace = entry->no_workspace
                ? meta.no_workspace
                : session_entry_matches_workspace(*entry, ws);
            if (same_workspace && entry->loop && entry->loop->is_busy()) {
                return error_response(409, "session is busy; abort it first");
            }
        }
    }

    // Destroy first so SessionManager flushes and releases the writer lease.
    deps.session_client->destroy_session(id);

    const std::string storage_cwd = meta.no_workspace
        ? meta.cwd
        : (meta.archived
            ? ws.cwd
            : (meta.cwd.empty() ? ws.cwd : meta.cwd));
    const auto project_dir = SessionStorage::get_project_dir(storage_cwd);

    // Remove the full-text projection first. If this fails, leave the files
    // and metadata untouched so the settings row remains retryable.
    SessionUserMessageIndex search_index(project_dir);
    std::string index_error;
    if (!search_index.remove_session(id, &index_error)) {
        LOG_WARN("[web] purge failed to remove search index for " + id +
                 ": " + index_error);
        return error_response(500, "failed to remove session search index");
    }

    std::string purge_error;
    if (!SessionStorage::purge_session_files(project_dir, id, &purge_error)) {
        LOG_WARN("[web] purge failed to remove session files for " + id +
                 ": " + purge_error);
        return error_response(500, purge_error.empty()
            ? "failed to remove session files"
            : purge_error);
    }

    if (global_session_search) {
        global_session_search->invalidate_project(ws.hash);
    }

    LOG_INFO("[web] permanently deleted session " + id +
             (meta.parent_session_id.empty()
                  ? std::string{" (archived)"}
                  : " (parent=" + meta.parent_session_id + ")"));
    return with_cors(req, crow::response(204));
}

crow::response WebServer::Impl::session_input_draft_response(
    const crow::request& req,
    const std::string& id,
    const std::string& text) {
    crow::response r(json{{"session_id", id}, {"id", id}, {"text", text}}.dump());
    r.add_header("Content-Type", "application/json");
    return with_cors(req, std::move(r));
}

crow::response WebServer::Impl::session_todos_response(
    const crow::request& req,
    const acecode::desktop::WorkspaceMeta& ws,
    const std::string& id,
    const std::vector<TodoItem>& todos) {
    crow::response r(json{
        {"session_id", id},
        {"id", id},
        {"workspace_hash", ws.hash},
        {"todos", todo_items_to_json(todos)},
        {"todo_summary", todo_summary_to_json(todos)},
    }.dump());
    r.add_header("Content-Type", "application/json");
    return with_cors(req, std::move(r));
}

std::optional<crow::response> WebServer::Impl::parse_session_input_draft_request(
    const crow::request& req,
    std::string& text) {
    try {
        auto j = json::parse(req.body);
        if (!j.contains("text") || !j["text"].is_string()) {
            crow::response r(400);
            r.body = R"({"error":"text required"})";
            r.add_header("Content-Type", "application/json");
            return with_cors(req, std::move(r));
        }
        text = j["text"].get<std::string>();
        return std::nullopt;
    } catch (const std::exception& e) {
        crow::response r(400);
        r.body = json{{"error", std::string("bad json: ") + e.what()}}.dump();
        r.add_header("Content-Type", "application/json");
        return with_cors(req, std::move(r));
    }
}

std::shared_ptr<SessionEntry> WebServer::Impl::active_session_entry_for_workspace(
    const acecode::desktop::WorkspaceMeta& ws,
    const std::string& id) const {
    if (!deps.session_registry) return nullptr;
    auto entry = deps.session_registry->acquire(id);
    if (!entry || !session_entry_matches_workspace(*entry, ws)) return nullptr;
    return entry;
}

void WebServer::Impl::emit_session_title_update(SessionEntry& entry) const {
    if (!entry.loop || !entry.sm) return;
    entry.loop->events().emit(SessionEventKind::SessionUpdated, json{
        {"session_id", entry.id},
        {"workspace_hash", entry.workspace_hash},
        {"cwd", entry.cwd},
        {"title", entry.sm->current_title()},
        {"title_source", entry.sm->current_title_source()},
    });
}

std::optional<crow::response> WebServer::Impl::parse_session_title_request(
    const crow::request& req,
    std::string& title) {
    try {
        auto j = json::parse(req.body);
        if (!j.contains("title") || !j["title"].is_string()) {
            crow::response r(400);
            r.body = R"({"error":"title required"})";
            r.add_header("Content-Type", "application/json");
            return with_cors(req, std::move(r));
        }
        title = j["title"].get<std::string>();
    } catch (const std::exception& e) {
        crow::response r(400);
        r.body = json{{"error", std::string("bad json: ") + e.what()}}.dump();
        r.add_header("Content-Type", "application/json");
        return with_cors(req, std::move(r));
    }

    while (!title.empty() && std::isspace(static_cast<unsigned char>(title.front()))) {
        title.erase(title.begin());
    }
    while (!title.empty() && std::isspace(static_cast<unsigned char>(title.back()))) {
        title.pop_back();
    }
    std::string err;
    if (!sanitize_title(title, err)) {
        crow::response r(400);
        r.body = json{{"error", "invalid title"}, {"message", err}}.dump();
        r.add_header("Content-Type", "application/json");
        return with_cors(req, std::move(r));
    }
    return std::nullopt;
}

crow::response WebServer::Impl::set_session_title_response(
    const crow::request& req,
    const acecode::desktop::WorkspaceMeta& ws,
    const std::string& id) {
    std::string title;
    if (auto err = parse_session_title_request(req, title)) return std::move(*err);

    if (auto entry = active_session_entry_for_workspace(ws, id)) {
        if (entry->sm) {
            entry->sm->ensure_active_session_id();
            entry->sm->set_session_title(title);
            emit_session_title_update(*entry);
            if (entry->loop) {
                entry->loop->dispatch_session_title_changed_hook(
                    entry->sm->current_title(),
                    "user",
                    entry->sm->current_title_source());
            }
            if (auto meta = find_session_meta_for_workspace(ws, id)) {
                if (global_session_search) {
                    global_session_search->invalidate_project(ws.hash);
                }
                const auto model_state = entry->model_binding
                    ? entry->model_binding->state_snapshot()
                    : SessionModelState{};
                crow::response r(session_info_to_json(
                    SessionInfo{
                        id,
                        entry->cwd,
                        entry->workspace_hash,
                        meta->created_at,
                        meta->updated_at,
                        meta->summary,
                        model_state.name,
                        model_state.provider,
                        model_state.model,
                        model_state.context_window,
                        model_state.deleted,
                        entry->sm->current_title(),
                        entry->sm->current_title_source(),
                        meta->message_count,
                        entry->sm->current_turn_count(),
                        entry->sm->current_permission_mode(),
                        entry->sm->current_last_token_usage(),
                        entry->sm->current_session_token_usage(),
                        true,
                        entry->loop ? entry->loop->is_busy() : false,
                    },
                    &*meta).dump());
                r.add_header("Content-Type", "application/json");
                return with_cors(req, std::move(r));
            }
        }
    }

    auto maybe_meta = find_session_meta_for_workspace(ws, id);
    if (!maybe_meta.has_value()) {
        crow::response r(404);
        r.body = R"({"error":"session not found"})";
        r.add_header("Content-Type", "application/json");
        return with_cors(req, std::move(r));
    }

    SessionMeta meta = *maybe_meta;
    meta.title = title;
    meta.title_source = title.empty() ? "user-cleared" : "user";
    const auto project_dir = SessionStorage::get_project_dir(
        meta.no_workspace && !meta.cwd.empty() ? meta.cwd : ws.cwd);
    SessionStorage::write_meta(SessionStorage::meta_path(project_dir, id), meta);
    if (global_session_search) {
        global_session_search->invalidate_project(ws.hash);
    }

    // The session can still be live in this process even though it failed the
    // workspace scoping check above: no-workspace sessions never match a
    // workspace, and a cwd recorded in a different path form does not either.
    // list_active()'s in-memory title shadows the meta written just above and
    // the entry's next update_meta() would write the stale title back, so the
    // live copy has to learn about the rename too. The session id already
    // identified the target uniquely, and reaching this point means the meta
    // lookup accepted it for this workspace.
    if (deps.session_registry) {
        if (auto live = deps.session_registry->acquire(id); live && live->sm) {
            live->sm->set_session_title(title);
            emit_session_title_update(*live);
            if (live->loop) {
                live->loop->dispatch_session_title_changed_hook(
                    live->sm->current_title(),
                    "user",
                    live->sm->current_title_source());
            }
        }
    }

    crow::response r(session_meta_to_json(meta, ws.hash).dump());
    r.add_header("Content-Type", "application/json");
    return with_cors(req, std::move(r));
}

crow::response WebServer::Impl::get_session_input_draft(
    const crow::request& req,
    const acecode::desktop::WorkspaceMeta& ws,
    const std::string& id) {
    if (auto entry = active_session_entry_for_workspace(ws, id)) {
        const std::string text = entry->sm ? entry->sm->current_input_draft() : std::string{};
        return session_input_draft_response(req, id, text);
    }

    auto maybe_meta = find_session_meta_for_workspace(ws, id);
    if (!maybe_meta.has_value()) {
        crow::response r(404);
        r.body = R"({"error":"session not found"})";
        r.add_header("Content-Type", "application/json");
        return with_cors(req, std::move(r));
    }
    return session_input_draft_response(req, id, maybe_meta->input_draft);
}

crow::response WebServer::Impl::set_session_input_draft(
    const crow::request& req,
    const acecode::desktop::WorkspaceMeta& ws,
    const std::string& id) {
    std::string text;
    if (auto err = parse_session_input_draft_request(req, text)) return std::move(*err);

    if (auto entry = active_session_entry_for_workspace(ws, id)) {
        if (entry->sm) {
            entry->sm->set_input_draft(text);
            return session_input_draft_response(req, id, entry->sm->current_input_draft());
        }
    }

    auto maybe_meta = find_session_meta_for_workspace(ws, id);
    if (!maybe_meta.has_value()) {
        crow::response r(404);
        r.body = R"({"error":"session not found"})";
        r.add_header("Content-Type", "application/json");
        return with_cors(req, std::move(r));
    }

    SessionMeta meta = *maybe_meta;
    meta.input_draft = text;
    const auto project_dir = SessionStorage::get_project_dir(
        meta.no_workspace && !meta.cwd.empty() ? meta.cwd : ws.cwd);
    SessionStorage::write_meta(SessionStorage::meta_path(project_dir, id), meta);
    return session_input_draft_response(req, id, text);
}

crow::response WebServer::Impl::clear_session_todos(
    const crow::request& req,
    const acecode::desktop::WorkspaceMeta& ws,
    const std::string& id) {
    if (auto entry = active_session_entry_for_workspace(ws, id)) {
        if (entry->sm) {
            entry->sm->set_todos({});
            return session_todos_response(req, ws, id, entry->sm->current_todos());
        }
    }

    auto maybe_meta = find_session_meta_for_workspace(ws, id);
    if (!maybe_meta.has_value()) {
        crow::response r(404);
        r.body = R"({"error":"session not found"})";
        r.add_header("Content-Type", "application/json");
        return with_cors(req, std::move(r));
    }

    SessionMeta meta = *maybe_meta;
    meta.todos.clear();
    const auto project_dir = SessionStorage::get_project_dir(
        meta.no_workspace && !meta.cwd.empty() ? meta.cwd : ws.cwd);
    SessionStorage::write_meta(SessionStorage::meta_path(project_dir, id), meta);
    return session_todos_response(req, ws, id, meta.todos);
}

std::filesystem::path WebServer::Impl::pinned_sessions_path_for_cwd(const std::string& cwd) const {
    return path_from_utf8(SessionStorage::get_project_dir(cwd)) /
           "pinned_sessions.json";
}

std::filesystem::path WebServer::Impl::no_workspace_pinned_sessions_path() const {
    return path_from_utf8(no_workspace_cache_root()) / "pinned_sessions.json";
}

std::filesystem::path WebServer::Impl::pinned_session_order_path() const {
    return path_from_utf8(projects_dir()) / "pinned_sessions_order.json";
}

std::vector<std::string> WebServer::Impl::session_ids_for_workspace(
    const acecode::desktop::WorkspaceMeta& ws) const {
    std::vector<std::string> out;
    std::unordered_set<std::string> seen;
    auto add = [&](const std::string& id) {
        if (id.empty() || seen.count(id)) return;
        seen.insert(id);
        out.push_back(id);
    };

    auto project_dir = SessionStorage::get_project_dir(ws.cwd);
    // 这里只用到 id 与 archived。list_sessions() 会为补全 summary /
    // message_count 逐个打开 JSONL,而一个项目目录的 transcript 可达数百 MB
    // (实测单个 workspace 523MB);而且原实现把同一个目录扫了两遍。
    // list_session_metadata() 只读 .meta.json,一遍就够。
    const auto disk = SessionStorage::list_session_metadata(project_dir);
    std::unordered_set<std::string> archived_ids;
    for (const auto& m : disk) {
        if (m.archived) archived_ids.insert(m.id);
    }

    if (deps.session_client) {
        for (const auto& s : deps.session_client->list_sessions()) {
            const bool same_workspace = s.workspace_hash == ws.hash ||
                (s.workspace_hash.empty() && s.cwd == ws.cwd);
            if (archived_ids.count(s.id)) continue;
            if (same_workspace) add(s.id);
        }
    }

    for (const auto& m : disk) {
        if (m.archived) continue;
        add(m.id);
    }
    return out;
}

std::vector<std::string> WebServer::Impl::session_ids_for_no_workspace() const {
    std::vector<std::string> out;
    std::unordered_set<std::string> seen;
    std::unordered_map<std::string, SessionMeta> disk_by_id;
    auto add = [&](const std::string& id) {
        if (id.empty() || seen.count(id)) return;
        seen.insert(id);
        out.push_back(id);
    };

    for (auto& meta : no_workspace_disk_sessions()) {
        if (!meta.no_workspace || !meta.parent_session_id.empty()) continue;
        disk_by_id[meta.id] = std::move(meta);
    }

    if (deps.session_client) {
        for (const auto& session : deps.session_client->list_sessions()) {
            if (!session.no_workspace || !session.parent_session_id.empty()) continue;
            const auto disk = disk_by_id.find(session.id);
            if (disk != disk_by_id.end() && disk->second.archived) continue;
            add(session.id);
        }
    }

    for (const auto& [id, meta] : disk_by_id) {
        if (!meta.archived) add(id);
    }
    return out;
}

json WebServer::Impl::pinned_sessions_to_json(const acecode::desktop::WorkspaceMeta& ws,
                                                 const std::vector<std::string>& session_ids) const {
    return json{{"workspace_hash", ws.hash}, {"cwd", ws.cwd}, {"session_ids", session_ids}};
}

json WebServer::Impl::no_workspace_pinned_sessions_to_json(
    const std::vector<std::string>& session_ids) const {
    return json{
        {"no_workspace", true},
        {"pin_scope", "__no_workspace__"},
        {"session_ids", session_ids},
    };
}

std::vector<PinnedSessionOrderItem> WebServer::Impl::available_pinned_session_order_items() const {
    std::vector<PinnedSessionOrderItem> out;
    std::unordered_set<std::string> seen;

    auto add_workspace = [&](const acecode::desktop::WorkspaceMeta& ws) {
        if (ws.hash.empty()) return;
        const auto path = pinned_sessions_path_for_cwd(ws.cwd);
        auto state = read_pinned_sessions_state(path);
        const auto pruned = prune_pinned_session_ids(
            state.session_ids, session_ids_for_workspace(ws));
        if (pruned != state.session_ids) {
            std::string ignored;
            write_pinned_sessions_state(path, PinnedSessionsState{pruned}, &ignored);
        }
        for (const auto& id : pruned) {
            if (id.empty()) continue;
            const auto key = ws.hash + '\0' + id;
            if (seen.count(key)) continue;
            seen.insert(key);
            out.push_back(PinnedSessionOrderItem{ws.hash, id});
        }
    };

    const auto no_workspace_path = no_workspace_pinned_sessions_path();
    auto no_workspace_state = read_pinned_sessions_state(no_workspace_path);
    const auto no_workspace_pruned = prune_pinned_session_ids(
        no_workspace_state.session_ids, session_ids_for_no_workspace());
    if (no_workspace_pruned != no_workspace_state.session_ids) {
        std::string ignored;
        write_pinned_sessions_state(
            no_workspace_path, PinnedSessionsState{no_workspace_pruned}, &ignored);
    }
    for (const auto& id : no_workspace_pruned) {
        if (id.empty()) continue;
        const auto key = std::string("__no_workspace__") + '\0' + id;
        if (seen.count(key)) continue;
        seen.insert(key);
        out.push_back(PinnedSessionOrderItem{"__no_workspace__", id});
    }

    if (deps.workspace_registry) {
        deps.workspace_registry->scan(projects_dir());
        for (const auto& ws : deps.workspace_registry->list()) {
            add_workspace(ws);
        }
    } else {
        add_workspace(compatibility_workspace());
    }
    return out;
}

json WebServer::Impl::pinned_session_order_to_json(
    const std::vector<PinnedSessionOrderItem>& items) const {
    json arr = json::array();
    for (const auto& item : items) {
        arr.push_back(json{
            {"workspace_hash", item.workspace_hash},
            {"session_id", item.session_id},
        });
    }
    return json{{"items", arr}};
}

// =====================================================================
// Impl member helpers — Attention state
// =====================================================================

std::string WebServer::Impl::attention_store_path_for_cwd(const std::string& cwd) const {
    return path_to_utf8(path_from_utf8(SessionStorage::get_project_dir(cwd)) /
                        "session_read_state.json");
}

void WebServer::Impl::load_attention_workspace_locked(const std::string& workspace_hash,
                                                        const std::string& cwd) const {
    if (workspace_hash.empty()) return;
    attention_workspace_cwds[workspace_hash] = cwd;
    if (loaded_attention_workspaces.count(workspace_hash)) return;
    loaded_attention_workspaces.insert(workspace_hash);

    std::ifstream in(path_from_utf8(attention_store_path_for_cwd(cwd)));
    if (!in) return;
    try {
        json root = json::parse(in, nullptr, true, true);
        if (!root.contains("sessions") || !root["sessions"].is_object()) return;
        const auto& sessions = root["sessions"];
        auto& records = attention_by_workspace[workspace_hash];
        for (auto it = sessions.begin(); it != sessions.end(); ++it) {
            if (!it.value().is_object()) continue;
            SessionAttentionRecord r;
            r.read_cursor = it.value().value("read_cursor", static_cast<std::uint64_t>(0));
            r.update_cursor = it.value().value("update_cursor", static_cast<std::uint64_t>(0));
            r.updated_at_ms = it.value().value("updated_at_ms", static_cast<std::int64_t>(0));
            records[it.key()] = r;
        }
    } catch (const std::exception& e) {
        LOG_WARN(std::string("[web] failed to load session read state: ") + e.what());
    }
}

void WebServer::Impl::save_attention_workspace_locked(const std::string& workspace_hash) const {
    // 直接调用者（例如 mark_session_read_status）同样需要失败重试语义。
    // 先标脏，只有完整写出并 rename 成功后才摘掉。
    attention_dirty_workspaces.insert(workspace_hash);

    auto cwd_it = attention_workspace_cwds.find(workspace_hash);
    if (cwd_it == attention_workspace_cwds.end() || cwd_it->second.empty()) {
        // 没有 cwd 就无法推导持久化路径，继续重试没有意义。
        attention_dirty_workspaces.erase(workspace_hash);
        return;
    }

    json root;
    root["version"] = 1;
    root["sessions"] = json::object();
    const auto records_it = attention_by_workspace.find(workspace_hash);
    if (records_it != attention_by_workspace.end()) {
        for (const auto& [sid, record] : records_it->second) {
            root["sessions"][sid] = json{
                {"read_cursor", record.read_cursor},
                {"update_cursor", record.update_cursor},
                {"updated_at_ms", record.updated_at_ms},
            };
        }
    }

    const auto path = path_from_utf8(attention_store_path_for_cwd(cwd_it->second));
    std::error_code ec;
    std::filesystem::create_directories(path.parent_path(), ec);
    if (ec) {
        LOG_WARN("[web] failed to create session read state directory: " + ec.message());
        return;
    }
    auto tmp = path;
    tmp += ".tmp";
    {
        std::ofstream out(tmp, std::ios::binary | std::ios::trunc);
        if (!out) {
            LOG_WARN("[web] failed to open session read state temp file");
            return;
        }
        // 机器读的状态文件,不需要缩进 —— dump(2) 会把体积放大近一倍。
        out << root.dump();
        out << '\n';
        if (!out) {
            LOG_WARN("[web] failed to write session read state temp file");
            out.close();
            std::filesystem::remove(tmp, ec);
            return;
        }
        out.close();
        if (!out) {
            LOG_WARN("[web] failed to close session read state temp file");
            std::filesystem::remove(tmp, ec);
            return;
        }
    }
    std::filesystem::rename(tmp, path, ec);
    if (ec) {
        std::filesystem::remove(path, ec);
        ec.clear();
        std::filesystem::rename(tmp, path, ec);
    }
    if (ec) {
        LOG_WARN("[web] failed to save session read state: " + ec.message());
        return;
    }
    attention_dirty_workspaces.erase(workspace_hash);
}

void WebServer::Impl::flush_dirty_attention_workspaces_locked() const {
    if (attention_dirty_workspaces.empty()) return;
    // save_attention_workspace_locked 成功时会从集合里删元素，失败时会保留，
    // 所以先拷一份再遍历，不能在末尾无条件 clear。
    const std::vector<std::string> pending(attention_dirty_workspaces.begin(),
                                           attention_dirty_workspaces.end());
    for (const auto& hash : pending) {
        save_attention_workspace_locked(hash);
    }
}

void WebServer::Impl::start_attention_flusher() {
    attention_flush_thread = std::thread([this] {
        std::unique_lock<std::mutex> lk(attention_mu);
        while (!attention_flush_stop) {
            attention_flush_cv.wait_for(
                lk,
                std::chrono::milliseconds(kAttentionFlushIntervalMs),
                [this] { return attention_flush_stop; });
            if (attention_flush_stop) break;
            flush_dirty_attention_workspaces_locked();
        }
    });
}

void WebServer::Impl::stop_attention_flusher() {
    if (!attention_flush_thread.joinable()) return;
    {
        std::lock_guard<std::mutex> lk(attention_mu);
        attention_flush_stop = true;
        // 正常退出路径把最后一个周期的脏数据落盘,别让 daemon 关闭吞掉未读态。
        flush_dirty_attention_workspaces_locked();
    }
    attention_flush_cv.notify_all();
    attention_flush_thread.join();
}

SessionAttentionRecord WebServer::Impl::attention_record_for_session(
    const std::string& workspace_hash,
    const std::string& cwd,
    const std::string& session_id,
    bool busy) const {
    std::lock_guard<std::mutex> lk(attention_mu);
    load_attention_workspace_locked(workspace_hash, cwd);
    auto record = attention_by_workspace[workspace_hash][session_id];
    record.busy = busy;
    return record;
}

json WebServer::Impl::attention_payload_for_record(
    const std::string& session_id,
    const std::string& workspace_hash,
    const std::string& cwd,
    const SessionAttentionRecord& record) const {
    const auto state = session_attention_state_for(record);
    json payload;
    payload["session_id"] = session_id;
    payload["workspace_hash"] = workspace_hash;
    if (!cwd.empty()) payload["cwd"] = cwd;
    payload["state"] = to_string(state);
    payload["attention_state"] = to_string(state);
    payload["read_state"] = to_string(state);
    payload["busy"] = record.busy;
    payload["cursor"] = record.update_cursor;
    payload["update_cursor"] = record.update_cursor;
    payload["read_cursor"] = record.read_cursor;
    payload["timestamp_ms"] = record.updated_at_ms > 0 ? record.updated_at_ms : now_unix_ms();
    if (deps.session_registry) {
        if (auto entry = deps.session_registry->acquire(session_id);
            entry && !entry->parent_session_id.empty()) {
            payload["parent_session_id"] = entry->parent_session_id;
        }
    }
    return payload;
}

void WebServer::Impl::append_attention_fields(json& o,
                                                 const std::string& session_id,
                                                 const std::string& workspace_hash,
                                                 const std::string& cwd,
                                                 bool busy) const {
    auto record = attention_record_for_session(workspace_hash, cwd, session_id, busy);
    auto payload = attention_payload_for_record(session_id, workspace_hash, cwd, record);
    o["attention_state"] = payload["attention_state"];
    o["read_state"] = payload["read_state"];
    o["busy"] = payload["busy"];
    o["status_cursor"] = payload["cursor"];
    o["update_cursor"] = payload["update_cursor"];
    o["read_cursor"] = payload["read_cursor"];
}

std::optional<acecode::desktop::WorkspaceMeta> WebServer::Impl::resolve_session_workspace(
    const std::string& session_id,
    const std::string& workspace_hash_hint) const {
    if (!session_id.empty() && deps.session_registry) {
        if (auto entry = deps.session_registry->acquire(session_id)) {
            acecode::desktop::WorkspaceMeta ws;
            if (entry->no_workspace) {
                ws.cwd = entry->cwd;
                ws.name = "";
                return ws;
            }
            ws.hash = !entry->workspace_hash.empty() ? entry->workspace_hash : compute_cwd_hash(entry->cwd);
            ws.cwd = entry->cwd;
            ws.name = acecode::desktop::default_workspace_name(entry->cwd);
            return ws;
        }
    }
    if (!workspace_hash_hint.empty()) {
        if (auto ws = resolve_workspace(workspace_hash_hint)) return ws;
    }
    return compatibility_workspace();
}

void WebServer::Impl::broadcast_session_status(const json& payload) {
    json msg;
    msg["type"] = "session_status";
    msg["timestamp_ms"] = now_unix_ms();
    msg["session_id"] = payload.value("session_id", std::string{});
    msg["workspace_hash"] = payload.value("workspace_hash", std::string{});
    if (payload.contains("parent_session_id")) {
        msg["parent_session_id"] = payload["parent_session_id"];
    }
    msg["payload"] = payload;
    const auto text = msg.dump();

    std::lock_guard<std::mutex> lk(ws_mu);
    for (const auto& [conn, state] : ws_connections) {
        if (!state) continue;
        const auto workspace_hash = payload.value("workspace_hash", std::string{});
        const auto session_id = payload.value("session_id", std::string{});
        const auto parent_session_id =
            payload.value("parent_session_id", std::string{});
        const bool wants_workspace = !workspace_hash.empty() && state->status_workspaces.count(workspace_hash);
        const bool wants_session = session_status_matches_subscriptions(
            state->status_sessions, session_id, parent_session_id);
        if (!wants_workspace && !wants_session) continue;
        try { conn->send_text(text); } catch (...) {}
    }
}

void WebServer::Impl::broadcast_remote_control_session_selected(
    const std::string& session_id,
    const std::string& workspace_hash,
    const std::string& cwd,
    bool no_workspace,
    const std::string& title,
    const std::string& updated_at) {
    if (session_id.empty()) return;
    const json msg = remote_control_session_selected_event_json(
        session_id, workspace_hash, cwd, no_workspace, title, updated_at);
    const auto text = msg.dump();
    std::lock_guard<std::mutex> lk(ws_mu);
    for (const auto& [conn, state] : ws_connections) {
        if (!state) continue;
        try { conn->send_text(text); } catch (...) {}
    }
}

void WebServer::Impl::track_subagent(const std::string& child_id) {
    if (child_id.empty() || !deps.session_client || !deps.session_registry) return;
    {
        std::lock_guard<std::mutex> lk(tracked_subagents_mu);
        if (tracked_subagent_subscriptions.find(child_id) !=
            tracked_subagent_subscriptions.end()) {
            return;
        }
    }
    std::string ws_hash;
    std::string cwd;
    if (auto e = deps.session_registry->acquire(child_id)) {
        ws_hash = e->workspace_hash;
        cwd = e->cwd;
    }
    // since=0:只关心从现在起的实时事件(子会话刚 spawn,还没历史)。回调仅把
    // 事件喂给 attention/status 广播,不向任何 WS 连接直发(那由各自的订阅负责)。
    auto tracker = std::weak_ptr<SubagentTrackerState>(subagent_tracker_state);
    auto sub = deps.session_client->subscribe(child_id,
        [tracker, child_id, ws_hash, cwd](const SessionEvent& evt) {
            auto state = tracker.lock();
            if (!state) return;
            std::lock_guard<std::mutex> lk(state->mu);
            if (!state->impl) return;
            state->impl->note_session_event_for_attention(child_id, ws_hash, cwd, evt);
        },
        /*since_seq=*/0);
    if (sub == 0) return;
    bool duplicate = false;
    {
        std::lock_guard<std::mutex> lk(tracked_subagents_mu);
        auto [_, inserted] = tracked_subagent_subscriptions.emplace(child_id, sub);
        duplicate = !inserted;
    }
    if (duplicate) {
        deps.session_client->unsubscribe(child_id, sub);
        return;
    }
    LOG_INFO("[web] track_subagent " + child_id + " ws=" + ws_hash);
}

void WebServer::Impl::note_session_event_for_attention(
    const std::string& session_id,
    const std::string& workspace_hash,
    const std::string& cwd,
    const SessionEvent& evt) {
    if (session_id.empty()) return;
    json payload;
    bool changed = false;
    {
        std::lock_guard<std::mutex> lk(attention_mu);
        load_attention_workspace_locked(workspace_hash, cwd);
        auto& record = attention_by_workspace[workspace_hash][session_id];
        const auto before_state = session_attention_state_for(record);
        const auto before_record = record;
        const auto cursor = evt.timestamp_ms > 0
            ? static_cast<std::uint64_t>(evt.timestamp_ms)
            : evt.seq;
        record = apply_session_attention_event(record, evt.kind, evt.payload, cursor, evt.timestamp_ms);
        const auto after_state = session_attention_state_for(record);
        changed = before_state != after_state || before_record.busy != record.busy;
        if (record.read_cursor != before_record.read_cursor ||
            record.update_cursor != before_record.update_cursor ||
            record.updated_at_ms != before_record.updated_at_ms ||
            record.busy != before_record.busy) {
            // 热路径:每个 token 都会走到这里,只标脏。见 Impl 里
            // kAttentionFlushIntervalMs 附近对写放大的说明。
            attention_dirty_workspaces.insert(workspace_hash);
        }
        if (changed) {
            // 状态跃迁 / busy 翻转 = 回合边界,一个回合只有几次,立即落盘
            // 保证异常退出后未读态与实际一致。
            flush_dirty_attention_workspaces_locked();
            payload = attention_payload_for_record(session_id, workspace_hash, cwd, record);
        }
    }
    if (changed) broadcast_session_status(payload);
}

json WebServer::Impl::mark_session_read_status(
    const std::string& session_id,
    const std::string& workspace_hash,
    const std::string& cwd,
    std::uint64_t cursor) {
    json payload;
    bool changed = false;
    bool current_busy = false;
    if (deps.session_registry) {
        if (auto entry = deps.session_registry->acquire(session_id)) {
            current_busy = entry->loop && entry->loop->is_busy();
        }
    }
    {
        std::lock_guard<std::mutex> lk(attention_mu);
        load_attention_workspace_locked(workspace_hash, cwd);
        auto& record = attention_by_workspace[workspace_hash][session_id];
        record.busy = current_busy;
        const auto before_state = session_attention_state_for(record);
        const auto before_record = record;
        record = mark_session_attention_read(record, cursor, now_unix_ms());
        const auto after_state = session_attention_state_for(record);
        changed = before_state != after_state || before_record.read_cursor != record.read_cursor;
        if (changed || before_record.updated_at_ms != record.updated_at_ms) {
            save_attention_workspace_locked(workspace_hash);
        }
        payload = attention_payload_for_record(session_id, workspace_hash, cwd, record);
    }
    if (changed) broadcast_session_status(payload);
    return payload;
}

void WebServer::Impl::send_status_snapshot(crow::websocket::connection& conn,
                                             const acecode::desktop::WorkspaceMeta& ws) {
    json sessions = json::array();
    for (const auto& s : sessions_for_workspace(ws)) {
        json item;
        item["session_id"] = s.value("id", std::string{});
        item["workspace_hash"] = s.value("workspace_hash", ws.hash);
        item["cwd"] = s.value("cwd", ws.cwd);
        item["state"] = s.value("attention_state", std::string("read"));
        item["attention_state"] = item["state"];
        item["read_state"] = s.value("read_state", item["state"].get<std::string>());
        item["busy"] = s.value("busy", false);
        item["cursor"] = s.value("status_cursor", static_cast<std::uint64_t>(0));
        item["update_cursor"] = s.value("update_cursor", static_cast<std::uint64_t>(0));
        item["read_cursor"] = s.value("read_cursor", static_cast<std::uint64_t>(0));
        sessions.push_back(std::move(item));
    }
    json msg;
    msg["type"] = "session_status_snapshot";
    msg["timestamp_ms"] = now_unix_ms();
    msg["workspace_hash"] = ws.hash;
    msg["payload"] = json{{"workspace_hash", ws.hash}, {"sessions", sessions}};
    conn.send_text(msg.dump());
}

// =====================================================================
// Impl member helpers — Connector hooks
// =====================================================================

void WebServer::Impl::refresh_saved_models_from_disk() {
    std::lock_guard<std::shared_mutex> lock(app_config_mu);
    if (!deps.app_config) return;
    try {
        AppConfig disk = deps.config_path.empty()
            ? load_config()
            : load_config_from_path(deps.config_path, false);
        if (publish_live_saved_models(
                *deps.app_config, std::move(disk.saved_models))) {
            LOG_INFO("saved_models refreshed from disk after connector hook");
        }
    } catch (const std::exception& e) {
        LOG_WARN(std::string("saved_models refresh failed: ") + e.what());
    }
}

// =====================================================================
// Impl member helpers — Session options
// =====================================================================

void WebServer::Impl::refresh_default_session_preferences_for_new_session() {
    std::lock_guard<std::shared_mutex> config_lock(app_config_mu);
    refresh_default_session_preferences_for_new_session_locked();
}

void WebServer::Impl::refresh_default_session_preferences_for_new_session_locked() {
    if (!deps.app_config) return;
    std::string err;
    if (!refresh_default_session_preferences_from_config(
            *deps.app_config, deps.config_path, &err)) {
        LOG_WARN("[web] failed to refresh default session preferences: " + err);
        return;
    }
    if (deps.session_registry) {
        auto parsed = parse_permission_mode_name(deps.app_config->default_permission_mode);
        deps.session_registry->set_default_permission_mode(
            parsed.value_or(PermissionMode::Default));
    }
}

std::optional<crow::response> WebServer::Impl::parse_session_options(
    const crow::request& req,
    const acecode::desktop::WorkspaceMeta& ws,
    SessionOptions& opts) {
    opts.cwd = ws.cwd;
    opts.workspace_hash = ws.hash;
    if (req.body.empty()) return std::nullopt;
    try {
        auto j = json::parse(req.body);
        if (j.contains("model") && j["model"].is_string())
            opts.model_name = j["model"].get<std::string>();
        if (j.contains("name") && j["name"].is_string())
            opts.model_name = j["name"].get<std::string>();
        std::string permission_mode_name;
        if (j.contains("permission_mode") && j["permission_mode"].is_string()) {
            permission_mode_name = j["permission_mode"].get<std::string>();
        } else if (j.contains("permissionMode") && j["permissionMode"].is_string()) {
            permission_mode_name = j["permissionMode"].get<std::string>();
        }
        if (!permission_mode_name.empty()) {
            auto parsed = parse_permission_mode_name(permission_mode_name);
            if (!parsed.has_value()) {
                crow::response r(400);
                r.body = json{{"error", "INVALID_PERMISSION_MODE"},
                              {"message", "invalid permission mode"}}.dump();
                r.add_header("Content-Type", "application/json");
                return with_cors(req, std::move(r));
            }
            opts.permission_mode = PermissionManager::mode_name(*parsed);
        }
        if (j.contains("initial_user_message") && j["initial_user_message"].is_string())
            opts.initial_user_message = j["initial_user_message"].get<std::string>();
        if (j.contains("expert_id") && j["expert_id"].is_string()) {
            opts.expert_id = j["expert_id"].get<std::string>();
        } else if (j.contains("expertId") && j["expertId"].is_string()) {
            opts.expert_id = j["expertId"].get<std::string>();
        }
        if (j.contains("auto_start") && j["auto_start"].is_boolean())
            opts.auto_start = j["auto_start"].get<bool>();
        const bool no_workspace =
            (j.contains("no_workspace") && j["no_workspace"].is_boolean() && j["no_workspace"].get<bool>()) ||
            (j.contains("noWorkspace") && j["noWorkspace"].is_boolean() && j["noWorkspace"].get<bool>());
        if (no_workspace) {
            opts.no_workspace = true;
            opts.workspace_hash.clear();
        }
    } catch (const std::exception& e) {
        crow::response r(400);
        r.body = json{{"error", std::string("bad json: ") + e.what()}}.dump();
        r.add_header("Content-Type", "application/json");
        return with_cors(req, std::move(r));
    }
    return std::nullopt;
}

std::optional<SessionModelState> WebServer::Impl::current_model_state_for_session(
    const std::string& session_id,
    const std::string& workspace_hash_hint) const {
    if (session_id.empty() || !deps.session_registry) return std::nullopt;

    if (auto active = deps.session_registry->current_model_state(session_id)) {
        return active;
    }

    std::vector<acecode::desktop::WorkspaceMeta> workspaces;
    if (!workspace_hash_hint.empty()) {
        if (auto ws = resolve_workspace(workspace_hash_hint)) {
            workspaces.push_back(*ws);
        } else {
            return std::nullopt;
        }
    } else {
        workspaces.push_back(compatibility_workspace());
        if (deps.workspace_registry) {
            deps.workspace_registry->scan(projects_dir());
            for (const auto& ws : deps.workspace_registry->list()) {
                if (std::none_of(workspaces.begin(), workspaces.end(),
                    [&](const auto& existing) { return existing.hash == ws.hash; })) {
                    workspaces.push_back(ws);
                }
            }
        }
    }

    for (const auto& ws : workspaces) {
        auto project_dir = SessionStorage::get_project_dir(ws.cwd);
        auto candidates = SessionStorage::find_session_files(project_dir, session_id);
        if (candidates.empty()) continue;
        if (candidates.front().meta_path.empty()) continue;
        auto meta = SessionStorage::read_meta(candidates.front().meta_path);
        if (meta.id.empty()) continue;
        if (auto state = deps.session_registry->model_state_from_meta(meta)) {
            return state;
        }
    }
    if (auto meta = find_no_workspace_session_meta(session_id)) {
        if (auto state = deps.session_registry->model_state_from_meta(*meta)) {
            return state;
        }
    }
    return std::nullopt;
}

} // namespace acecode::web