xlings.cppm

// mcpp.xlings — unified abstraction layer for all xlings (external package
// manager) interactions. Consolidates NDJSON event parsing, subprocess
// command building, path helpers, and bootstrap progress types that were
// previously scattered across config.cppm, package_fetcher.cppm, cli.cppm,
// flags.cppm, ninja_backend.cppm, and stdmod.cppm.
//
// This module is a LEAF dependency: it only imports `std` and
// `mcpp.pm.compat`. It must NOT import mcpp.config or any other mcpp module.

module;
#include <cstdio>      // stderr
#include <cstdlib>

export module mcpp.xlings;

import std;
import mcpp.pm.compat;
import mcpp.pm.index_contract;
import mcpp.pm.index_snapshot;
import mcpp.platform;
import mcpp.log;
import mcpp.home;

export namespace mcpp::xlings {

// ─── Env: resolved xlings binary + home directory ───────────────────

struct Env {
    std::filesystem::path binary;      // xlings binary path
    std::filesystem::path home;        // XLINGS_HOME directory
    std::filesystem::path projectDir;  // XLINGS_PROJECT_DIR (empty = global mode)
};

// ─── Pinned version constants ───────────────────────────────────────

namespace pinned {
    inline constexpr std::string_view kPatchelfVersion = "0.18.0";
    inline constexpr std::string_view kNinjaVersion    = "1.12.1";
    // The xlings a release bundles at <install>/registry/bin/xlings, and the
    // version `mcpp self env` reports.
    //
    // This is the SOURCE OF TRUTH for every xlings pin in .github/, and
    // `.github/tools/check_version_pins.sh` enforces that — CI fails if any
    // pin disagrees. This comment used to instead name three files to keep
    // in lock-step by hand; that list was already missing both composite
    // actions, which is how CI's sandbox sat on 0.4.30 unnoticed while
    // everything else had moved on. Don't reintroduce a hand-maintained list.
    //
    // THIS IS A FLOOR, not just the current pick, and it has been raised
    // twice for reasons that both still hold.
    //
    // First, at 2026.8.27.5. Below 2026.8.27.2 the bundled xlings takes a
    // subos's runtime binding from a compiled-in constant, so a home can
    // declare one glibc and install another the moment the index publishes a
    // packaging revision -- and mcpp is the
    // party that notices, because select_glibc_payload_lib looks up the
    // payload directory by the binding's exact version and refuses to fall
    // back:
    //
    //   error: selected RuntimeBinding glibc@2.44 requires payload
    //          '<store>/xim-x-glibc/2.44', but it is not installed
    //
    // Measured across four xlings versions against an index carrying both
    // 2.44 and 2.44.2: every client whose binding is a constant mismatched;
    // 2026.8.27.4 and .5, which read the index, stayed consistent. .5 also
    // makes the declaration outrank the index during resolution, so it holds
    // even when `latest` is not the highest entry in the table.
    //
    // Second, at 2026.8.30.2 (mcpp#533). Below it, xlings answered "is this
    // package already installed" from the xvm version database keyed on the
    // BARE SHORT NAME, so a package skipped its own `install()` whenever any
    // other namespace held the same `<name>@<version>` —
    // `compat:libdrm@2.4.123` against the
    // `xim:libdrm@2.4.123` that Mesa pulls in. The descriptor's tree was never
    // built, and mcpp is again the party that notices, four layers later:
    //
    //   /bin/sh: 1: -shared: not found
    //
    // mcpp now refuses that link unit by name and withholds `.mcpp_ok` from a
    // directory holding nothing the package installed, so the failure is
    // legible on any client. Only a client at or above this floor INSTALLS
    // correctly — which is why this is a floor and not a preference, and why
    // an index must still not publish a deliberately colliding
    // `<name>@<version>` (see .agents/docs/2026-08-30-cross-repo-fix-plan §1).
    inline constexpr std::string_view kXlingsVersion   = "2026.8.30.2";
    inline constexpr std::string_view kNasmVersion     = "3.02";
}

// ─── Path helpers (pure functions, no subprocess) ───────────────────

namespace paths {

    // xpkgs base: env.home / "data" / "xpkgs"
    std::filesystem::path xpkgs_base(const Env& env);

    // sandbox bin: env.home / "subos" / "default" / "bin"
    std::filesystem::path sandbox_bin(const Env& env);

    // sandbox sysroot: env.home / "subos" / "default"
    std::filesystem::path sysroot(const Env& env);

    // xim tool root: xpkgs_base / "xim-x-<tool>"
    std::filesystem::path xim_tool_root(const Env& env, std::string_view tool);

    // xim tool versioned: xpkgs_base / "xim-x-<tool>" / "<version>"
    std::filesystem::path xim_tool(const Env& env, std::string_view tool,
                                   std::string_view version);

    // ── A declared `[xlings] deps` entry, and where its payload landed ──────
    //
    // The two helpers above hardcode the `xim` namespace, which was right
    // while the only callers were mcpp's own tools (ninja, nasm). A manifest
    // may name any namespace — `local:qemu-riscv` during development,
    // `scode:…` for a source-built package — and the store spells an installed
    // package `<namespace>-x-<name>/<version>`.
    //
    // Here rather than in the build layer because THIS module already owns
    // that layout (`xpkgs_base`, `xim_tool`). A second place deriving it is
    // the shape this codebase has paid for repeatedly: it does not fail when
    // you add it, it fails later, somewhere else.
    struct XpkgRef {
        std::string ns;       // "xim" when the spec omitted one
        std::string name;
        std::string version;  // empty = unpinned
    };

    // Parse `[<ns>:]<name>[@<version>]` exactly as a manifest writes it.
    XpkgRef parse_xpkg_ref(std::string_view spec);

    // Where that package's payload is, or nullopt if it is not installed.
    //
    // A PINNED ref resolves to exactly its version and to nothing else. A
    // build that asked for 1.8.12 and silently got 1.9.0 is the kind of answer
    // that is only discovered later, in the artifact. An unpinned ref takes
    // the highest version present — compared by numeric segments, because a
    // plain string sort puts "0.4.11" before "0.4.9".
    std::optional<std::filesystem::path>
    xpkg_payload(const Env& env, const XpkgRef& ref);

    // The same resolution against an explicit xpkgs base. The Env form
    // delegates here; this one exists so the rule ("pinned means exactly that
    // version") is testable without constructing a home.
    std::optional<std::filesystem::path>
    xpkg_payload_at(const std::filesystem::path& xpkgsBase, const XpkgRef& ref);

    // From compiler binary, climb parent dirs to find "xpkgs" directory.
    // Replaces 3 duplicate implementations in flags.cppm, ninja_backend.cppm,
    // stdmod.cppm.
    std::optional<std::filesystem::path>
    xpkgs_from_compiler(const std::filesystem::path& compilerBin);

    // The subos a TOOLCHAIN belongs to (mcpp#352).
    //
    // Derived from the compiler rather than from a global: a build already
    // knows which home its toolchain came from, and asking a second source
    // would let the two disagree — the "one question, several answerers" shape
    // that the same investigation found four times over on the xlings side.
    //
    // A PURE legacy ownership derivation, with no environment override in it.
    // Project runtime selection no longer calls this helper: it goes through
    // RuntimeSelection -> RuntimeBinding, which is rooted in mcpp.toml and the
    // configured xlings home. This remains useful for locating payload-adjacent
    // tools owned by a compiler installation.
    //
    // Empty when the toolchain is not sandbox-resident — a system compiler is
    // the user's explicit choice of the host world, and there is no subos
    // speaking for it.
    std::optional<std::filesystem::path>
    subos_dir_of(const std::filesystem::path& compilerBin);

    // Find a sibling xim tool relative to a compiler binary.
    // e.g. find_sibling_tool(gcc_bin, "binutils") returns highest version
    // dir of xim-x-binutils.
    std::optional<std::filesystem::path>
    find_sibling_tool(const std::filesystem::path& compilerBin,
                      std::string_view tool);

    // Find a binary inside a sibling tool (e.g. binutils/bin/ar,
    // ninja/ninja).
    std::optional<std::filesystem::path>
    find_sibling_binary(const std::filesystem::path& compilerBin,
                        std::string_view tool,
                        std::string_view binaryRelPath);

    // Find a sibling package across all index prefixes.
    // e.g. find_sibling_package(gcc_bin, "linux-headers") searches for
    // xim-x-linux-headers, scode-x-linux-headers, etc.
    // Metadata-only dirs (.xim-installed/.xpkg.lua husks left by delegating
    // index packages) never qualify; when requiredRelPath is given, only a
    // version dir containing it qualifies (the payload may live under a
    // different prefix than the husk — issue #120).
    std::optional<std::filesystem::path>
    find_sibling_package(const std::filesystem::path& compilerBin,
                         std::string_view packageName,
                         std::string_view requiredRelPath = {});

    // xpkgs root of the ACTIVE mcpp home ($MCPP_HOME or ~/.mcpp). Payload
    // discovery consults this in addition to compiler siblings: an
    // inherited/symlinked compiler resolves into its owner home, while the
    // active home may own (or have just installed) the sysroot payloads.
    std::optional<std::filesystem::path> active_home_xpkgs();

    // Like find_sibling_tool, but anchored at the active home's xpkgs.
    // Searches across index prefixes (xim-x-, scode-x-, …) with the same
    // husk/requiredRelPath rules as find_sibling_package.
    std::optional<std::filesystem::path>
    find_home_tool(std::string_view tool,
                   std::string_view requiredRelPath = {});

    // WHICH INSTALLED PAYLOAD DIRECTORY ANSWERS A REQUESTED VERSION.
    //
    // A request and a resolution are two vocabularies for one fact. A
    // RuntimeBinding carries the DECLARED version (`glibc@2.44`); xlings names
    // the payload directory after what that request RESOLVED to (`2.44.2`).
    // They coincide until the index moves a package within a series, and then
    // every lookup that spells the directory by the declared version stops
    // finding it.
    //
    // STATED ONCE HERE BECAUSE IT HAS TWO CALLERS AND THEY FAILED
    // SEPARATELY. `post_install`'s toolchain fixup and `probe`'s compile-side
    // payload discovery each spelled it themselves; fixing one left the other,
    // and the second failure did not name a version at all — it read
    //
    //     bits/os_defines.h:39: fatal error: features.h: No such file
    //
    // because the glibc include directory had simply not been added.
    //
    // A REFINEMENT, NOT A DIRECTORY-ORDER PICK. `2.44.2` is what the request
    // `2.44` resolved to: its version COMPONENTS begin with the requested ones.
    // `2.4` does not answer `2.44`, because the comparison is per component and
    // not per character. And when two payloads both refine the request, this
    // returns nothing — "the resolution of this request" has to be one payload
    // to be an answer at all, and picking by directory order is the guess every
    // caller here refuses to make.
    std::optional<std::filesystem::path>
    payload_dir_for_version(const std::filesystem::path& packageRoot,
                            std::string_view version);

    // index data root: env.home / "data"
    std::filesystem::path index_data(const Env& env);

    // sandbox init marker: env.home / "subos" / "default" / ".xlings.json"
    std::filesystem::path sandbox_init_marker(const Env& env);

} // namespace paths

// ─── Shell quoting ──────────────────────────────────────────────────

// Shell-escape (single-quote) a string for the command line.
std::string shq(std::string_view s);

// ─── Shell command builders ─────────────────────────────────────────

// Build the standard xlings command prefix with proper env vars.
// cd '<home>' && env -u XLINGS_PROJECT_DIR PATH=<sandbox_bin>:"$PATH"
//     XLINGS_HOME='<home>' '<binary>'
std::string build_command_prefix(const Env& env);

// Build full xlings interface command.
// <prefix> interface <capability> --args '<argsJson>' 2>/dev/null
std::string build_interface_command(const Env& env,
                                    std::string_view capability,
                                    std::string_view argsJson);

// ─── NDJSON event types ─────────────────────────────────────────────

struct ProgressEvent {
    std::string  phase;      // "download", "extract", "configure", ...
    int          percent;    // 0..100
    std::string  message;
};

struct LogEvent {
    std::string  level;      // "debug" | "info" | "warn" | "error"
    std::string  message;
};

struct DataEvent {
    std::string  dataKind;   // "install_plan", "styled_list", ...
    std::string  payloadJson;// raw JSON (let caller parse)
};

struct ErrorEvent {
    std::string  code;
    std::string  message;
    std::string  hint;
    bool         recoverable = false;
};

struct ResultEvent {
    int          exitCode = 0;
    std::string  dataJson;   // additional payload, may be empty
};

using Event = std::variant<ProgressEvent, LogEvent, DataEvent,
                           ErrorEvent, ResultEvent>;

// Parse one NDJSON line into an Event.
std::optional<Event> parse_event_line(std::string_view line);

// ─── JSON extraction helpers (for NDJSON parsing) ───────────────────

std::string extract_string(std::string_view text, std::string_view key);
std::optional<long long> extract_int(std::string_view text, std::string_view key);
std::optional<bool> extract_bool(std::string_view text, std::string_view key);
std::string extract_object(std::string_view text, std::string_view key);

// ─── Subprocess call ────────────────────────────────────────────────

struct CallResult {
    int                          exitCode = 0;
    std::vector<DataEvent>       dataEvents;
    std::optional<ErrorEvent>    error;
    std::string                  resultJson;
};

struct EventHandler {
    virtual ~EventHandler() = default;
    virtual void on_progress(const ProgressEvent&) {}
    virtual void on_log     (const LogEvent&)     {}
    virtual void on_data    (const DataEvent&)    {}
    virtual void on_error   (const ErrorEvent&)   {}
    virtual void on_result  (const ResultEvent&)  {}
};

std::expected<CallResult, std::string>
call(const Env& env, std::string_view capability,
     std::string_view argsJson, EventHandler* handler = nullptr);

// ─── Bootstrap progress types ───────────────────────────────────────

struct BootstrapFile {
    std::string  name;             // xim package id, e.g. "xim:patchelf@0.18.0"
    double       downloadedBytes = 0;
    double       totalBytes      = 0;
    bool         started         = false;
    bool         finished        = false;
};

struct BootstrapProgress {
    std::vector<BootstrapFile>  files;
    double                      elapsedSec = 0;
};

using BootstrapProgressCallback = std::function<void(const BootstrapProgress&)>;

// Run xlings install with progress callback (used by bootstrap functions).
// When not `quiet` and stderr is a TTY, an elapsed-time spinner is shown
// during the (otherwise silent) direct install so first-run doesn't look
// frozen.
int install_with_progress(const Env& env, std::string_view target,
                          const BootstrapProgressCallback& cb,
                          bool quiet = false);

// Run direct `xlings install <target> -y`.
// Used as a fallback when the NDJSON interface install path fails.
int install_direct(const Env& env, std::string_view target, bool quiet = false);

// ─── Sandbox lifecycle ──────────────────────────────────────────────

// Write .xlings.json seed file.
//
// The `mirror` default is "auto": xlings' own adaptive mirror module
// (xlings.core.mirror.adaptive — latency-probed with per-download failover and
// failure penalisation) then picks the best reachable host per download. This
// replaces the historic hardcoded "CN", which FORCED the CN mirror and disabled
// that mechanism — stranding overseas users and GitHub-hosted CI on a
// slow/unreachable gitcode. An explicit `mcpp self config --mirror CN|GLOBAL`
// still writes that fixed value (config priority). Mirror selection is xlings'
// responsibility; mcpp just declines to override it by default.
// The project's build-environment payload (L-1), materialized 1:1 into the
// `.xlings.json` keys xlings already understands. Plain types (no manifest
// dependency); the caller fills it from a manifest's [xlings] section.
struct ProjectEnv {
    std::vector<std::string>                          deps;       // → "deps"
    std::vector<std::pair<std::string,std::string>>   workspace;  // → "workspace"
    std::string                                       subos;      // → "subos"
    // No `envs`: the key was materialised here and read by nothing. See
    // .agents/docs/2026-09-03-xlings-workspace-as-the-one-table.md §4.
    bool empty() const {
        return deps.empty() && workspace.empty() && subos.empty();
    }
};

// One index_repos entry for seed_xlings_json. `artifact`/`source` are the
// xlings >= 0.4.68 per-repo artifact-sync fields (#269); empty means "do not
// emit the key", which keeps pre-artifact output byte-identical and matches
// xlings' "undeclared = plain git" semantics. Older xlings ignores both keys.
struct SeedRepo {
    std::string name;
    std::string url;
    std::string artifact;   // artifact source base, e.g. https://github.com/xlings-res/mcpp-index
    std::string source;     // "auto" | "artifact" | "git"
};

void seed_xlings_json(const Env& env,
                      std::span<const SeedRepo> repos,
                      std::string_view mirror = "auto",
                      const ProjectEnv& penv = {});

// Persist the xlings mirror selection in .xlings.json via xlings itself.
int config_show(const Env& env);
int config_set_mirror(const Env& env, std::string_view mirror, bool quiet = false);

// Run xlings self init.
void ensure_init(const Env& env, bool quiet);

// Ensure patchelf is installed.
void ensure_patchelf(const Env& env, bool quiet,
                     const BootstrapProgressCallback& cb);

// Ensure ninja is installed.
void ensure_ninja(const Env& env, bool quiet,
                  const BootstrapProgressCallback& cb);

// Fast, side-effect-free probe for a usable nasm (>= 2.16): PATH first (CI
// images ship one), the mcpp sandbox second. NEVER triggers an install —
// pure lookup. A build that needs to *provision* nasm goes through the
// toolchain's synchronous fetcher gate
// (mcpp::pm::Fetcher::resolve_xpkg_path("xim:nasm@<version>", autoInstall,
// ...)) from mcpp.build.prepare, the same gate the compiler toolchain uses:
// this module is a LEAF dependency and must not import mcpp.config /
// mcpp.fetcher (#232 — the old bespoke `ensure_nasm` install path skipped
// the index refresh and downgraded install failure to a warning).
std::optional<std::filesystem::path> find_usable_nasm(const Env& env);

// Locate an already-installed nasm inside the mcpp sandbox
// ($XLINGS_HOME/data/xpkgs/xim-x-nasm/<version>/...). Pure lookup: no PATH
// probe, no install. Called lazily — only when a build plan actually
// contains .asm units — after a provisioning gate has landed the package;
// the caller HARD-FAILS on nullopt, never silently skips assembly sources.
std::optional<std::filesystem::path> find_sandbox_nasm(const Env& env);

// ─── Index freshness ────────────────────────────────────────────────

// How long a just-completed index sync suppresses the next one.
//
// Re-running a multi-repo sync because a SECOND package is also missing cannot
// help: the first sync already fetched everything upstream had, so a package
// still absent afterwards is absent upstream. Lives here, in the leaf module,
// because both users need it and the policy layer (mcpp.pm.index_refresh)
// imports this module — the reverse would be a cycle.
inline constexpr std::int64_t kIndexRefreshDebounceSeconds = 120;

// Check whether the default mcpplibs index data exists and is fresh
// (within ttlSeconds).
// Returns true if index is present and fresh, false otherwise.
bool is_index_fresh(const Env& env, std::int64_t ttlSeconds);

// Check whether xlings' official xim index data exists and is fresh.
// This is separate from mcpp's default mcpplibs index because xlings
// toolchains live in xim-pkgindex, while modular libraries live in mcpplibs.
bool is_official_index_fresh(const Env& env, std::int64_t ttlSeconds);

// Check whether a specific package file exists in xlings' official xim index
// and the index is fresh. This catches restored CI caches that have an index
// directory and marker but predate a package added later.
bool is_official_package_index_fresh(const Env& env,
                                     std::string_view packageName,
                                     std::int64_t ttlSeconds);

// Run `xlings update` to refresh all index repos. Streams output to stdout.
// Returns the xlings exit code.
int update_index(const Env& env, bool quiet = false);

// Ensure the local index is present and fresh. Runs `xlings update` if
// the index is missing or older than ttlSeconds. Idempotent and quiet
// when no update is needed.
void ensure_index_fresh(const Env& env, std::int64_t ttlSeconds, bool quiet = false);

// Ensure xlings' official xim index is present and fresh.
void ensure_official_index_fresh(const Env& env, std::int64_t ttlSeconds, bool quiet = false);

// Ensure a specific package file exists in xlings' official xim index.
void ensure_official_package_index_fresh(const Env& env,
                                         std::string_view packageName,
                                         std::int64_t ttlSeconds,
                                         bool quiet = false);

// ─── Index status (read-only, offline) ──────────────────────────────
// Snapshot of a local index directory — computed without touching the
// network, for `mcpp index status`.
struct IndexStatus {
    std::filesystem::path      dir;        // on-disk index directory
    bool                       present;    // pkgs/ tree exists locally
    bool                       fresh;      // refreshed within ttlSeconds
    std::int64_t               ageSeconds; // since last refresh marker, -1 if unknown
    std::optional<std::string> rev;        // index CONTENT identity, nullopt if absent
};
IndexStatus default_index_status(const Env& env, std::int64_t ttlSeconds);
IndexStatus official_index_status(const Env& env, std::int64_t ttlSeconds);

// The index's own content identity, as written by xlings into
// `<indexDir>/.xlings-index-version` when it materializes the tree.
//
// OPAQUE BY CONTRACT. Observed values are a 7-char short sha for the artifact-
// distributed indexes (`mcpp-index-8d67478.tar.gz` → `8d67478`) but a DATE
// VERSION for the sub-indexes (`xim-index-awesome-2026.7.30.1.tar.gz` →
// `2026.7.30.1`). Never parse it, never assume a length — only compare it for
// equality and print it. Returns nullopt when the file is missing (a local
// `path` index has none) or blank; callers must degrade, never hard-fail.
std::optional<std::string> index_revision(const std::filesystem::path& indexDir);

// ─── run_capture utility ────────────────────────────────────────────

std::expected<std::string, std::string> run_capture(const std::string& cmd);

} // namespace mcpp::xlings

// ═══════════════════════════════════════════════════════════════════════
// Implementation
// ═══════════════════════════════════════════════════════════════════════

namespace mcpp::xlings {

namespace {

// Right-pad a verb to 12 columns for bootstrap status lines.
void print_status(std::string_view verb, std::string_view msg) {
    constexpr std::size_t W = 12;
    if (verb.size() >= W) {
        std::println("{} {}", verb, msg);
    } else {
        std::println("{}{} {}", std::string(W - verb.size(), ' '), verb, msg);
    }
}

std::filesystem::path default_index_dir(const Env& env) {
    return paths::index_data(env) / "mcpplibs";
}

std::filesystem::path official_index_dir(const Env& env) {
    return paths::index_data(env) / "xim-pkgindex";
}

std::filesystem::path index_pkgs_dir(const std::filesystem::path& indexDir) {
    return indexDir / "pkgs";
}

std::filesystem::path index_refresh_marker(const std::filesystem::path& indexDir) {
    return indexDir / ".mcpp-index-updated";
}

std::filesystem::path index_version_file(const std::filesystem::path& indexDir) {
    return indexDir / ".xlings-index-version";
}

std::filesystem::path official_package_file(const Env& env, std::string_view packageName) {
    if (packageName.empty()) return {};
    std::string name(packageName);
    return official_index_dir(env) / "pkgs" / std::string(1, name[0]) / (name + ".lua");
}

std::string json_escaped_path_probe(std::filesystem::path path) {
    auto value = path.string();
    std::string escaped;
    escaped.reserve(value.size() * 2);
    for (char c : value) {
        if (c == '\\') escaped += "\\\\";
        else escaped.push_back(c);
    }
    return escaped;
}

bool official_index_cache_matches_package_file(const Env& env,
                                               std::string_view packageName) {
    auto cache = official_index_dir(env) / ".xlings-index-cache.json";
    if (!std::filesystem::exists(cache)) return true;

    auto pkg = official_package_file(env, packageName);
    if (pkg.empty()) return false;

    std::ifstream is(cache);
    if (!is) return false;
    std::string body((std::istreambuf_iterator<char>(is)), {});
    auto rawPath = pkg.string();
    return body.find(rawPath) != std::string::npos
        || body.find(json_escaped_path_probe(pkg)) != std::string::npos;
}

void mark_index_refreshed(const std::filesystem::path& indexDir) {
    if (!std::filesystem::exists(index_pkgs_dir(indexDir))) return;
    std::error_code ec;
    std::filesystem::create_directories(indexDir, ec);
    auto marker = index_refresh_marker(indexDir);
    {
        std::ofstream os(marker, std::ios::trunc);
        if (!os) return;
        os << "ok\n";
    }
    std::filesystem::last_write_time(
        marker, std::filesystem::file_time_type::clock::now(), ec);
}

void mark_known_indexes_refreshed(const Env& env) {
    // Project-scoped envs used to return early here, which left the global
    // indexes unmarked whenever a project with custom `[indices]` triggered the
    // sync — so `mcpp index status` reported "unknown" forever on exactly the
    // machines that refresh most. The marker is advisory (it debounces and it
    // dates the status line; it is NOT what decides whether a refresh is
    // needed), so marking it from either env is both safe and more accurate.
    mark_index_refreshed(default_index_dir(env));
    mark_index_refreshed(official_index_dir(env));
}

bool is_index_dir_fresh(const std::filesystem::path& indexDir, std::int64_t ttlSeconds) {
    std::error_code ec;
    if (!std::filesystem::exists(index_pkgs_dir(indexDir))) return false;

    auto marker = index_refresh_marker(indexDir);
    if (!std::filesystem::exists(marker)) return false;

    auto newest = std::filesystem::last_write_time(marker, ec);
    if (ec) return false;

    auto now = std::filesystem::file_time_type::clock::now();
    auto age = std::chrono::duration_cast<std::chrono::seconds>(now - newest);
    // A marker stamped in the FUTURE yields a negative age, which the plain
    // `age < ttl` test read as "fresh" — and stayed fresh until the wall clock
    // caught up, potentially for years. Future timestamps are routine: clock
    // skew in containers/VMs, a tar that preserved mtimes, a restored CI cache.
    // An unusable timestamp means "unknown", and unknown must mean stale.
    if (age.count() < 0) return false;
    return age.count() < ttlSeconds;
}

// Seconds since the index's refresh marker was last touched, or -1 if the
// marker is missing/unreadable. Read-only — no network, no side effects.
std::int64_t index_age_seconds(const std::filesystem::path& indexDir) {
    std::error_code ec;
    auto marker = index_refresh_marker(indexDir);
    auto newest = std::filesystem::last_write_time(marker, ec);
    if (ec) return -1;
    auto now = std::filesystem::file_time_type::clock::now();
    auto age = std::chrono::duration_cast<std::chrono::seconds>(now - newest).count();
    return age < 0 ? -1 : age;   // future stamp → "unknown", same rule as above
}

// Defined inside the anonymous namespace so `index_status_for` (also here) can
// use it; the exported `index_revision` below forwards to it.
std::optional<std::string> read_index_revision(const std::filesystem::path& indexDir) {
    std::ifstream is(index_version_file(indexDir), std::ios::binary);
    if (!is) return std::nullopt;
    std::string body((std::istreambuf_iterator<char>(is)), {});
    // The observed files carry no trailing newline, but trim anyway: this value
    // is compared for equality and printed, and a stray \r from a Windows-side
    // writer would otherwise turn "same rev" into "changed rev" every run.
    auto isSpace = [](unsigned char c) { return std::isspace(c) != 0; };
    while (!body.empty() && isSpace(static_cast<unsigned char>(body.back())))
        body.pop_back();
    std::size_t b = 0;
    while (b < body.size() && isSpace(static_cast<unsigned char>(body[b]))) ++b;
    body.erase(0, b);
    if (body.empty()) return std::nullopt;
    return body;
}

IndexStatus index_status_for(const std::filesystem::path& indexDir,
                             std::int64_t ttlSeconds) {
    std::error_code ec;
    bool present = std::filesystem::exists(index_pkgs_dir(indexDir), ec) && !ec;
    return IndexStatus{
        .dir        = indexDir,
        .present    = present,
        .fresh      = is_index_dir_fresh(indexDir, ttlSeconds),
        .ageSeconds = index_age_seconds(indexDir),
        .rev        = read_index_revision(indexDir),
    };
}

void write_file(const std::filesystem::path& p, std::string_view content) {
    std::error_code ec;
    std::filesystem::create_directories(p.parent_path(), ec);
    std::ofstream os(p);
    os << content;
}

std::string json_escape(std::string_view value) {
    std::string out;
    out.reserve(value.size());
    for (unsigned char ch : value) {
        switch (ch) {
            case '"':  out += "\\\""; break;
            case '\\': out += "\\\\"; break;
            case '\b': out += "\\b";  break;
            case '\f': out += "\\f";  break;
            case '\n': out += "\\n";  break;
            case '\r': out += "\\r";  break;
            case '\t': out += "\\t";  break;
            default:
                if (ch < 0x20) {
                    out += std::format("\\u{:04x}", static_cast<unsigned>(ch));
                } else {
                    out.push_back(static_cast<char>(ch));
                }
        }
    }
    return out;
}

// LineScan: cheap field extraction for bootstrap install progress lines.
// Handles flat JSON; no nested array/object — the keys we extract are
// all leaves.
struct LineScan {
    std::string_view s;
    std::string find_str(std::string_view key) const {
        std::string n = std::format("\"{}\":\"", key);
        auto p = s.find(n);
        if (p == std::string_view::npos) return "";
        p += n.size();
        std::string out;
        while (p < s.size() && s[p] != '"') {
            if (s[p] == '\\' && p + 1 < s.size()) {
                out.push_back(s[p+1]); p += 2; continue;
            }
            out.push_back(s[p++]);
        }
        return out;
    }
    double find_num(std::string_view key) const {
        std::string n = std::format("\"{}\":", key);
        auto p = s.find(n);
        if (p == std::string_view::npos) return 0;
        p += n.size();
        auto e = p;
        while (e < s.size()
            && (std::isdigit(static_cast<unsigned char>(s[e]))
                || s[e] == '.' || s[e] == '-' || s[e] == '+'
                || s[e] == 'e' || s[e] == 'E')) ++e;
        try { return std::stod(std::string(s.substr(p, e - p))); }
        catch (...) { return 0; }
    }
    bool find_bool(std::string_view key) const {
        std::string n = std::format("\"{}\":", key);
        auto p = s.find(n);
        if (p == std::string_view::npos) return false;
        p += n.size();
        return s.size() - p >= 4 && s.substr(p, 4) == "true";
    }
};

} // anonymous namespace

// ─── Index identity ─────────────────────────────────────────────────

std::optional<std::string> index_revision(const std::filesystem::path& indexDir) {
    return read_index_revision(indexDir);
}

// ─── run_capture ────────────────────────────────────────────────────

std::expected<std::string, std::string> run_capture(const std::string& cmd) {
    auto r = mcpp::platform::process::capture(cmd);
    if (r.exit_code != 0 && r.output.empty())
        return std::unexpected("command failed: " + cmd);
    return r.output;
}

// ─── Shell quoting ──────────────────────────────────────────────────

std::string shq(std::string_view s) {
    return mcpp::platform::shell::quote(s);
}

// ─── Path helpers ───────────────────────────────────────────────────

namespace paths {

std::filesystem::path xpkgs_base(const Env& env) {
    return env.home / "data" / "xpkgs";
}

std::filesystem::path sandbox_bin(const Env& env) {
    return env.home / "subos" / "default" / "bin";
}

std::filesystem::path sysroot(const Env& env) {
    return env.home / "subos" / "default";
}

std::filesystem::path xim_tool_root(const Env& env, std::string_view tool) {
    return xpkgs_base(env) / std::format("xim-x-{}", tool);
}

std::filesystem::path xim_tool(const Env& env, std::string_view tool,
                               std::string_view version) {
    return xpkgs_base(env) / std::format("xim-x-{}", tool) / std::string(version);
}

// Parse `[<ns>:]<name>[@<version>]` exactly as a manifest writes it.
XpkgRef parse_xpkg_ref(std::string_view spec) {
    XpkgRef r;
    if (auto colon = spec.find(':'); colon != std::string_view::npos) {
        r.ns = std::string(spec.substr(0, colon));
        spec = spec.substr(colon + 1);
    } else {
        // The manifest's own default, spelled once here rather than at each
        // call site: `deps = ["ninja"]` and `deps = ["xim:ninja"]` name the
        // same package.
        r.ns = "xim";
    }
    if (auto at = spec.find('@'); at != std::string_view::npos) {
        r.name    = std::string(spec.substr(0, at));
        r.version = std::string(spec.substr(at + 1));
    } else {
        r.name = std::string(spec);
    }
    return r;
}

// Where that package's payload is, or nullopt if it is not installed.
//
// A PINNED ref resolves to exactly its version and to nothing else. A build
// that asked for 1.8.12 and silently got 1.9.0 is the kind of answer that is
// only discovered later, in the artifact. An unpinned ref takes the highest
// version present — compared by numeric segments, because a plain string sort
// puts "0.4.11" before "0.4.9" and picking the wrong payload is silent.
std::optional<std::filesystem::path>
xpkg_payload(const Env& env, const XpkgRef& ref) {
    return xpkg_payload_at(xpkgs_base(env), ref);
}

std::optional<std::filesystem::path>
xpkg_payload_at(const std::filesystem::path& xpkgsBase, const XpkgRef& ref) {
    if (ref.name.empty()) return std::nullopt;
    const auto root = xpkgsBase / std::format("{}-x-{}", ref.ns, ref.name);
    std::error_code ec;
    if (!ref.version.empty()) {
        auto p = root / ref.version;
        if (std::filesystem::is_directory(p, ec)) return p;
        return std::nullopt;   // pinned and absent: NOT "some other version"
    }
    if (!std::filesystem::is_directory(root, ec)) return std::nullopt;
    auto key_of = [](const std::string& s) {
        std::vector<long long> k;
        long long cur = 0; bool any = false;
        for (char c : s) {
            if (c >= '0' && c <= '9') { cur = cur * 10 + (c - '0'); any = true; }
            else { if (any) k.push_back(cur); cur = 0; any = false; }
        }
        if (any) k.push_back(cur);
        return k;
    };
    std::optional<std::filesystem::path> best;
    std::vector<long long> bestKey;
    for (auto const& e : std::filesystem::directory_iterator(root, ec)) {
        if (!e.is_directory(ec)) continue;
        auto k = key_of(e.path().filename().string());
        if (!best || k > bestKey) { best = e.path(); bestKey = k; }
    }
    return best;
}


std::optional<std::filesystem::path>
xpkgs_from_compiler(const std::filesystem::path& compilerBin) {
    for (auto p = compilerBin.parent_path();
         p.has_parent_path() && p != p.root_path();
         p = p.parent_path()) {
        if (p.filename() == "xpkgs") return p;
    }
    return std::nullopt;
}

std::optional<std::filesystem::path>
subos_dir_of(const std::filesystem::path& compilerBin) {
    auto xpkgs = xpkgs_from_compiler(compilerBin);
    if (!xpkgs) return std::nullopt;
    // <home>/data/xpkgs → <home>/subos/default. Spelled from the xpkgs dir
    // rather than from Env so a toolchain inherited from ANOTHER home resolves
    // to that home's subos, which is the one whose payloads the binary was
    // actually linked against.
    auto home = xpkgs->parent_path().parent_path();
    if (home.empty()) return std::nullopt;
    return home / "subos" / "default";
}

std::optional<std::filesystem::path>
find_sibling_tool(const std::filesystem::path& compilerBin,
                  std::string_view tool) {
    auto xpkgs = xpkgs_from_compiler(compilerBin);
    if (!xpkgs) return std::nullopt;

    auto root = *xpkgs / std::format("xim-x-{}", tool);
    std::error_code ec;
    if (!std::filesystem::exists(root, ec)) return std::nullopt;

    // The first version dir readdir yields. ORDER IS UNDEFINED -- this does
    // NOT return the highest, and the comment that said so was wrong for as
    // long as it stood. With two versions installed the answer varies by
    // filesystem, so a caller that needs a SPECIFIC version must name it;
    // see probe.cppm, where the version comes from the resolved runtime
    // binding rather than from this scan.
    //
    // A test asserting the old "highest" claim was attempted and removed: it
    // passed or failed by directory order, which makes both outcomes
    // uninformative.
    for (auto& v : std::filesystem::directory_iterator(root, ec)) {
        if (v.is_directory(ec)) return v.path();
    }
    return std::nullopt;
}

std::optional<std::filesystem::path> active_home_xpkgs() {
    // `mcpp::home::root()`, NOT A FOURTH DERIVATION OF IT.
    //
    // This function used to resolve the home itself — `$MCPP_HOME`, else
    // `$HOME/.mcpp` — which is two of the three answers `mcpp.home` gives. The
    // one it left out is SELF-CONTAINED MODE: a release tarball or
    // `xlings install mcpp` puts the binary at `<root>/bin/mcpp` and the
    // unpacked tree IS the home. On such an install this function answered
    // `$HOME/.mcpp`, so payload discovery reached a DIFFERENT home than
    // everything else in the process — and what payload discovery produces is
    // `-isystem` rows on every compile command.
    //
    // `mcpp.home`'s own header opens with this: "Every path under the mcpp
    // home must be derived from here. Before #311 this logic existed in three
    // places … the copies drifted." This was the fourth copy, and it drifted
    // the same way.
    auto xpkgs = mcpp::home::root() / "registry" / "data" / "xpkgs";
    std::error_code ec;
    if (!std::filesystem::exists(xpkgs, ec)) return std::nullopt;
    return xpkgs;
}

namespace {

// A version dir qualifies as a payload only if it has real content —
// dot-prefixed entries (.xim-installed, .xpkg.lua) are install metadata,
// and a dir holding nothing else is the husk a delegating index package
// leaves behind (the payload lives under another prefix; issue #120).
// When requiredRelPath is given, the dir must also contain that path.
bool payload_dir_qualifies(const std::filesystem::path& versionDir,
                           std::string_view requiredRelPath) {
    std::error_code ec;
    bool hasContent = false;
    for (auto& f : std::filesystem::directory_iterator(versionDir, ec)) {
        if (!f.path().filename().string().starts_with(".")) {
            hasContent = true;
            break;
        }
    }
    if (!hasContent) return false;
    if (!requiredRelPath.empty()
        && !std::filesystem::exists(versionDir / requiredRelPath, ec))
        return false;
    return true;
}

// Scan an xpkgs root across index prefixes (xim-x-, scode-x-, compat-x-, …)
// for the first qualifying version dir of `packageName`.
std::optional<std::filesystem::path>
find_package_in_xpkgs(const std::filesystem::path& xpkgs,
                      std::string_view packageName,
                      std::string_view requiredRelPath) {
    std::error_code ec;
    std::string suffix = std::format("-x-{}", packageName);
    for (auto& entry : std::filesystem::directory_iterator(xpkgs, ec)) {
        if (!entry.is_directory(ec)) continue;
        auto name = entry.path().filename().string();
        if (!name.ends_with(suffix)) continue;
        for (auto& v : std::filesystem::directory_iterator(entry.path(), ec)) {
            if (!v.is_directory(ec)) continue;
            if (payload_dir_qualifies(v.path(), requiredRelPath))
                return v.path();
        }
    }
    return std::nullopt;
}

} // namespace

std::optional<std::filesystem::path>
find_home_tool(std::string_view tool, std::string_view requiredRelPath) {
    auto xpkgs = active_home_xpkgs();
    if (!xpkgs) return std::nullopt;
    return find_package_in_xpkgs(*xpkgs, tool, requiredRelPath);
}

std::optional<std::filesystem::path>
find_sibling_binary(const std::filesystem::path& compilerBin,
                    std::string_view tool,
                    std::string_view binaryRelPath) {
    auto xpkgs = xpkgs_from_compiler(compilerBin);
    if (!xpkgs) return std::nullopt;

    auto root = *xpkgs / std::format("xim-x-{}", tool);
    std::error_code ec;
    if (!std::filesystem::exists(root, ec)) return std::nullopt;

    for (auto& v : std::filesystem::directory_iterator(root, ec)) {
        auto candidate = v.path() / std::string(binaryRelPath);
        if (std::filesystem::exists(candidate, ec))
            return candidate;
    }
    return std::nullopt;
}

std::optional<std::filesystem::path>
find_sibling_package(const std::filesystem::path& compilerBin,
                     std::string_view packageName,
                     std::string_view requiredRelPath) {
    auto xpkgs = xpkgs_from_compiler(compilerBin);
    if (!xpkgs) return std::nullopt;

    // Search across index prefixes: xim-x-, scode-x-, compat-x-, etc.
    if (auto found = find_package_in_xpkgs(*xpkgs, packageName, requiredRelPath))
        return found;

    // THE `~/.xlings` FALLBACK IS GONE, AND ITS REMOVAL IS THE POINT.
    //
    // It used to read: "Also check ~/.xlings/data/xpkgs/ (xlings global home)
    // as fallback." That was written when one machine had one home. It means
    // that a build whose `MCPP_HOME` names one tree can take a payload out of
    // ANOTHER, and what this function's callers do with the result is put it on
    // every compile command:
    //
    //     probe.cppm:448   linux-headers  →  -isystem <other home>/…/include
    //
    // ⇒ a hermetic build reaching outside its own sandbox for headers, with no
    // diagnostic, and with the resulting objects looking exactly like objects
    // built from the payload that was actually pinned. Reported as the second
    // half of mcpp#514, where a project's dependency units carried `-isystem`
    // rows naming a home the build was not using.
    //
    // THE DIRECTION IS THE SAFE ONE. Not finding a payload is reported —
    // `probe.cppm` already has the verbose branch for it, and a glibc build
    // that then fails at `<linux/limits.h>` says so at the first compile.
    // Finding the WRONG one says nothing at all, and this codebase has paid
    // for that shape before (`e2e-inherit-toolchain-corrupts-real-payloads`,
    // `dev-overlay-poisons-a-released-version`).
    return std::nullopt;
}

std::optional<std::filesystem::path>
payload_dir_for_version(const std::filesystem::path& packageRoot,
                        std::string_view version) {
    // AN EMPTY REQUEST IS NOT A REQUEST FOR EVERYTHING. `packageRoot / ""`
    // is `packageRoot` itself, which IS a directory — so without this the
    // exact-match branch below would hand back the package root and every
    // caller would treat that container as a payload. Both callers today
    // reject an empty version before arriving here; this is the invariant
    // stated where it holds rather than at each of them.
    if (version.empty()) return std::nullopt;

    std::error_code ec;
    auto exact = packageRoot / std::string(version);
    if (std::filesystem::is_directory(exact, ec)) return exact;

    auto components = [](std::string_view v) {
        std::vector<std::string> parts;
        std::size_t start = 0;
        while (start <= v.size()) {
            auto dot = v.find('.', start);
            if (dot == std::string_view::npos) {
                parts.emplace_back(v.substr(start));
                break;
            }
            parts.emplace_back(v.substr(start, dot - start));
            start = dot + 1;
        }
        return parts;
    };
    const auto wanted = components(version);

    std::optional<std::filesystem::path> only;
    std::error_code dec;
    for (auto it = std::filesystem::directory_iterator(packageRoot, dec);
         !dec && it != std::filesystem::directory_iterator{};
         it.increment(dec)) {
        if (!it->is_directory(dec)) continue;
        const auto have = components(it->path().filename().string());
        if (have.size() <= wanted.size()) continue;
        if (!std::equal(wanted.begin(), wanted.end(), have.begin())) continue;
        if (only) return std::nullopt;   // two refinements are not an answer
        only = it->path();
    }
    return only;
}

std::filesystem::path index_data(const Env& env) {
    return env.home / "data";
}

std::filesystem::path sandbox_init_marker(const Env& env) {
    return env.home / "subos" / "default" / ".xlings.json";
}

} // namespace paths

// ─── Shell command builders ─────────────────────────────────────────

std::string build_command_prefix(const Env& env) {
    auto xvmBin = paths::sandbox_bin(env).string();
    if constexpr (mcpp::platform::is_windows) {
        mcpp::platform::env::set("XLINGS_HOME", env.home.string());
        mcpp::platform::env::set("XLINGS_PROJECT_DIR",
                  env.projectDir.empty() ? "" : env.projectDir.string());
        mcpp::platform::windows::prepend_path(xvmBin);
        return env.binary.string();
    } else {
        if (env.projectDir.empty()) {
            // Global mode: unset XLINGS_PROJECT_DIR (existing behavior).
            return std::format(
                "cd {} && env -u XLINGS_PROJECT_DIR PATH={}:\"$PATH\" XLINGS_HOME={} {}",
                shq(env.home.string()),
                shq(xvmBin),
                shq(env.home.string()),
                shq(env.binary.string()));
        }
        // Project-level mode: set XLINGS_PROJECT_DIR so xlings uses
        // additive project repos alongside global repos.
        return std::format(
            "cd {} && env PATH={}:\"$PATH\" XLINGS_HOME={} XLINGS_PROJECT_DIR={} {}",
            shq(env.home.string()),
            shq(xvmBin),
            shq(env.home.string()),
            shq(env.projectDir.string()),
            shq(env.binary.string()));
    }
}

std::string build_interface_command(const Env& env,
                                    std::string_view capability,
                                    std::string_view argsJson) {
    return std::format("{} interface {} --args {} {}",
        build_command_prefix(env), capability, shq(argsJson),
        mcpp::platform::null_redirect);
}

// ─── JSON extraction helpers ────────────────────────────────────────

std::string extract_string(std::string_view text, std::string_view key) {
    auto needle = std::string{"\""} + std::string(key) + "\":\"";
    auto p = text.find(needle);
    if (p == std::string_view::npos) return "";
    p += needle.size();
    std::string out;
    while (p < text.size()) {
        char c = text[p++];
        if (c == '\\' && p < text.size()) {
            char nc = text[p++];
            switch (nc) {
                case 'n': out.push_back('\n'); break;
                case 't': out.push_back('\t'); break;
                case 'r': out.push_back('\r'); break;
                case '"': out.push_back('"');  break;
                case '\\': out.push_back('\\'); break;
                default: out.push_back(nc);
            }
        } else if (c == '"') {
            return out;
        } else {
            out.push_back(c);
        }
    }
    return out;
}

std::optional<long long> extract_int(std::string_view text, std::string_view key) {
    auto needle = std::string{"\""} + std::string(key) + "\":";
    auto p = text.find(needle);
    if (p == std::string_view::npos) return std::nullopt;
    p += needle.size();
    while (p < text.size() && text[p] == ' ') ++p;
    bool neg = false;
    if (p < text.size() && text[p] == '-') { neg = true; ++p; }
    long long n = 0;
    bool any = false;
    while (p < text.size() && std::isdigit(static_cast<unsigned char>(text[p]))) {
        n = n * 10 + (text[p++] - '0');
        any = true;
    }
    if (!any) return std::nullopt;
    return neg ? -n : n;
}

std::optional<bool> extract_bool(std::string_view text, std::string_view key) {
    auto needle = std::string{"\""} + std::string(key) + "\":";
    auto p = text.find(needle);
    if (p == std::string_view::npos) return std::nullopt;
    p += needle.size();
    while (p < text.size() && text[p] == ' ') ++p;
    if (text.substr(p, 4) == "true")  return true;
    if (text.substr(p, 5) == "false") return false;
    return std::nullopt;
}

std::string extract_object(std::string_view text, std::string_view key) {
    auto needle = std::string{"\""} + std::string(key) + "\":";
    auto p = text.find(needle);
    if (p == std::string_view::npos) return "";
    p += needle.size();
    while (p < text.size() && text[p] == ' ') ++p;
    if (p >= text.size() || (text[p] != '{' && text[p] != '[')) return "";
    char open  = text[p];
    char close = (open == '{') ? '}' : ']';
    int depth = 0;
    std::size_t start = p;
    bool in_string = false;
    while (p < text.size()) {
        char c = text[p];
        if (in_string) {
            if (c == '\\' && p + 1 < text.size()) { p += 2; continue; }
            if (c == '"') in_string = false;
            ++p; continue;
        }
        if (c == '"') { in_string = true; ++p; continue; }
        if (c == open)  { ++depth; }
        else if (c == close) {
            --depth;
            if (depth == 0) return std::string(text.substr(start, p - start + 1));
        }
        ++p;
    }
    return "";
}

// ─── NDJSON event parser ────────────────────────────────────────────

std::optional<Event> parse_event_line(std::string_view line) {
    auto kind = extract_string(line, "kind");
    if (kind == "progress") {
        ProgressEvent e;
        e.phase   = extract_string(line, "phase");
        e.percent = static_cast<int>(extract_int(line, "percent").value_or(0));
        e.message = extract_string(line, "message");
        return e;
    }
    if (kind == "log") {
        LogEvent e;
        e.level   = extract_string(line, "level");
        e.message = extract_string(line, "message");
        return e;
    }
    if (kind == "data") {
        DataEvent e;
        e.dataKind   = extract_string(line, "dataKind");
        e.payloadJson= extract_object(line, "payload");
        return e;
    }
    if (kind == "error") {
        ErrorEvent e;
        e.code        = extract_string(line, "code");
        e.message     = extract_string(line, "message");
        e.hint        = extract_string(line, "hint");
        e.recoverable = extract_bool(line, "recoverable").value_or(false);
        return e;
    }
    if (kind == "result") {
        ResultEvent e;
        e.exitCode = static_cast<int>(extract_int(line, "exitCode").value_or(0));
        return e;
    }
    // heartbeat and unknown kinds
    return std::nullopt;
}

// ─── Subprocess call ────────────────────────────────────────────────

std::expected<CallResult, std::string>
call(const Env& env, std::string_view capability,
     std::string_view argsJson, EventHandler* handler)
{
    auto cmd = build_interface_command(env, capability, argsJson);

    // #238: under MCPP_VERBOSE=1 surface the exact xlings invocation so a
    // failing install_packages can be reproduced/inspected by hand. The
    // NDJSON child's own error/warn lines are surfaced by the caller's
    // EventHandler (e.g. InstallProgressHandler).
    mcpp::log::verbose("xlings",
        std::format("interface {} exec: {}", capability, cmd));

    CallResult result;
    int rc = mcpp::platform::process::run_streaming(cmd,
        [&](std::string_view line) {
            if (line.empty()) return;

            auto ev = parse_event_line(line);
            if (!ev) return;

            std::visit([&](auto&& e) {
                using T = std::decay_t<decltype(e)>;
                if constexpr (std::is_same_v<T, ProgressEvent>) {
                    if (handler) handler->on_progress(e);
                } else if constexpr (std::is_same_v<T, LogEvent>) {
                    if (handler) handler->on_log(e);
                } else if constexpr (std::is_same_v<T, DataEvent>) {
                    result.dataEvents.push_back(e);
                    if (handler) handler->on_data(e);
                } else if constexpr (std::is_same_v<T, ErrorEvent>) {
                    result.error = e;
                    if (handler) handler->on_error(e);
                } else if constexpr (std::is_same_v<T, ResultEvent>) {
                    result.exitCode = e.exitCode;
                    result.resultJson = e.dataJson;
                    if (handler) handler->on_result(e);
                }
            }, *ev);
        });
    if (rc != 0 && result.exitCode == 0) result.exitCode = rc;
    return result;
}

// ─── install_with_progress ──────────────────────────────────────────

int install_with_progress(const Env& env, std::string_view target,
                          const BootstrapProgressCallback& cb,
                          bool quiet)
{
    auto argsJson = std::format(
        R"({{"targets":["{}"],"yes":true}})", target);

    // All platforms: try direct `xlings install ... -y` first.
    // The direct command is more reliable for large packages (e.g. LLVM
    // ~800MB) because:
    //   - it doesn't pipe through NDJSON interface (simpler subprocess chain)
    //   - xlings manages its own stdin/stdout/stderr
    //   - extraction subprocess coordination works normally
    // The NDJSON interface path is kept as a fallback for progress reporting.
    {
        auto directCmd = build_command_prefix(env) +
            std::format(" install {} -y {}", target, mcpp::platform::shell::silent_redirect);
        // Seal stdin so xlings and any grandchildren (curl, git, 7z, xcode-select
        // / brew prompts, etc.) cannot block on a terminal read. Without it,
        // first-run toolchain install pauses waiting for the user to press Enter
        // — first seen on Windows, now also reproduced on macOS (the "需要回车
        // 才能继续" first-run report). The old "POSIX must keep stdin open for
        // subprocess coordination" claim never held in practice; `-y` already
        // makes the install non-interactive, so the redirect only removes the
        // spurious terminal blocking. Windows uses <NUL, POSIX </dev/null.
        if constexpr (mcpp::platform::is_windows) {
            directCmd += " <NUL";
        } else {
            directCmd += " </dev/null";
        }

        // The direct install redirects all output to the null device, so it
        // produces zero feedback — on a slow/network-bound first run this
        // looks frozen. Run the blocking std::system() on a worker thread and
        // paint an in-place elapsed-time spinner on stderr while it runs.
        // Only when interactive (not quiet, stderr/stdout is a TTY).
        const bool showSpinner = !quiet && mcpp::platform::terminal::is_tty();

        std::atomic<bool> done{false};
        int directRaw = 0;
        std::thread worker([&] {
            directRaw = std::system(directCmd.c_str());
            done.store(true, std::memory_order_release);
        });

        if (showSpinner) {
            constexpr std::string_view frames = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏";
            // Each braille frame is 3 bytes in UTF-8.
            constexpr std::size_t kFrameBytes = 3;
            const std::size_t nFrames = frames.size() / kFrameBytes;
            const auto start = std::chrono::steady_clock::now();
            std::size_t i = 0;
            while (!done.load(std::memory_order_acquire)) {
                auto elapsed = std::chrono::duration_cast<std::chrono::seconds>(
                    std::chrono::steady_clock::now() - start).count();
                std::print(stderr, "\r  {} installing {}  ({}s)\x1b[K",
                    frames.substr((i % nFrames) * kFrameBytes, kFrameBytes),
                    target, elapsed);
                std::fflush(stderr);
                ++i;
                std::this_thread::sleep_for(std::chrono::milliseconds(200));
            }
            // Clear the spinner line.
            std::print(stderr, "\r\x1b[K");
            std::fflush(stderr);
        }

        worker.join();
        int directRc = mcpp::platform::process::extract_exit_code(directRaw);
        if (directRc == 0) return 0;
    }

    // Fallback: NDJSON interface path (provides progress callbacks).
    // Seal stdin (same rationale as the direct path above) so the install can't
    // block on a terminal read. The protocol is NDJSON-over-stdout + "yes":true,
    // so nothing here needs the terminal.
    auto cmd = [&]() -> std::string {
        if constexpr (mcpp::platform::is_windows) {
            return std::format("{} interface install_packages --args {} {} <NUL",
                build_command_prefix(env),
                shq(argsJson),
                mcpp::platform::null_redirect);
        } else {
            return std::format(
                "cd {} && env -u XLINGS_PROJECT_DIR XLINGS_HOME={} {} interface install_packages --args {} {} </dev/null",
                shq(env.home.string()),
                shq(env.home.string()),
                shq(env.binary.string()),
                shq(argsJson),
                mcpp::platform::null_redirect);
        }
    }();

    int resultExitCode = -1;

    auto handle_line = [&](std::string_view line) {
        LineScan ls{line};
        auto kind = ls.find_str("kind");
        if (kind == "result") {
            resultExitCode = static_cast<int>(ls.find_num("exitCode"));
            return;
        }
        if (kind != "data") return;
        if (ls.find_str("dataKind") != "download_progress") return;
        if (!cb) return;

        auto p = line.find("\"files\":[");
        if (p == std::string_view::npos) return;
        p += 9;

        BootstrapProgress prog;
        prog.elapsedSec = ls.find_num("elapsedSec");

        while (p < line.size()) {
            while (p < line.size() && (line[p] == ' ' || line[p] == '\n'
                                       || line[p] == ',')) ++p;
            if (p >= line.size() || line[p] == ']') break;
            if (line[p] != '{') break;
            int depth = 0;
            auto start = p;
            bool in_string = false;
            for (; p < line.size(); ++p) {
                char c = line[p];
                if (in_string) {
                    if (c == '\\' && p + 1 < line.size()) { ++p; continue; }
                    if (c == '"') in_string = false;
                    continue;
                }
                if (c == '"')      in_string = true;
                else if (c == '{') ++depth;
                else if (c == '}') { if (--depth == 0) { ++p; break; } }
            }
            LineScan fl{line.substr(start, p - start)};
            BootstrapFile f;
            f.name            = fl.find_str("name");
            f.downloadedBytes = fl.find_num("downloadedBytes");
            f.totalBytes      = fl.find_num("totalBytes");
            f.started         = fl.find_bool("started");
            f.finished        = fl.find_bool("finished");
            if (!f.name.empty()) prog.files.push_back(std::move(f));
        }
        if (!prog.files.empty()) cb(prog);
    };

    int closeRc = mcpp::platform::process::run_streaming(cmd, handle_line);
    return (resultExitCode != -1) ? resultExitCode : closeRc;
}

int install_direct(const Env& env, std::string_view target, bool quiet) {
    auto cmd = build_command_prefix(env)
        + std::format(" install {} -y", shq(target));
    if (quiet) {
        cmd += " ";
        cmd += std::string(mcpp::platform::shell::silent_redirect);
    }
    if constexpr (mcpp::platform::is_windows) {
        cmd += " <NUL";
    } else {
        cmd += " </dev/null";
    }
    return mcpp::platform::process::extract_exit_code(std::system(cmd.c_str()));
}

// ─── Sandbox lifecycle ──────────────────────────────────────────────

void seed_xlings_json(const Env& env,
                      std::span<const SeedRepo> repos,
                      std::string_view mirror,
                      const ProjectEnv& penv)
{
    auto path = env.home / ".xlings.json";
    std::string json = "{\n";
    json += "  \"index_repos\": [\n";
    for (std::size_t i = 0; i < repos.size(); ++i) {
        json += std::format("    {{ \"name\": \"{}\", \"url\": \"{}\"",
                            json_escape(repos[i].name),
                            json_escape(repos[i].url));
        if (!repos[i].artifact.empty())
            json += std::format(", \"artifact\": \"{}\"",
                                json_escape(repos[i].artifact));
        if (!repos[i].source.empty())
            json += std::format(", \"source\": \"{}\"",
                                json_escape(repos[i].source));
        json += std::format(" }}{}\n", i + 1 == repos.size() ? "" : ",");
    }
    json += "  ],\n";
    // [xlings] build environment (L-1): materialize deps/workspace/subos/envs
    // verbatim into the keys xlings reads. Each is emitted only when non-empty.
    auto emit_obj = [&](std::string_view key,
                        std::span<const std::pair<std::string,std::string>> kv) {
        json += std::format("  \"{}\": {{\n", key);
        for (std::size_t i = 0; i < kv.size(); ++i)
            json += std::format("    \"{}\": \"{}\"{}\n",
                                json_escape(kv[i].first), json_escape(kv[i].second),
                                i + 1 == kv.size() ? "" : ",");
        json += "  },\n";
    };
    if (!penv.deps.empty()) {
        json += "  \"deps\": [";
        for (std::size_t i = 0; i < penv.deps.size(); ++i)
            json += std::format("{}\"{}\"", i ? ", " : "", json_escape(penv.deps[i]));
        json += "],\n";
    }
    if (!penv.workspace.empty()) emit_obj("workspace", penv.workspace);
    if (!penv.subos.empty())
        json += std::format("  \"subos\": \"{}\",\n", json_escape(penv.subos));
    json += "  \"lang\": \"en\",\n";
    json += std::format("  \"mirror\": \"{}\"\n", json_escape(mirror));
    json += "}\n";
    write_file(path, json);
}

int config_show(const Env& env) {
    auto cmd = std::format("{} config", build_command_prefix(env));
    return mcpp::platform::process::run_silent(cmd);
}

int config_set_mirror(const Env& env, std::string_view mirror, bool quiet) {
    if (mirror.empty()) return 0;
    auto cmd = std::format(
        "{} config --mirror {} {}",
        build_command_prefix(env),
        shq(mirror),
        quiet ? mcpp::platform::shell::silent_redirect : "");
    return mcpp::platform::process::run_silent(cmd);
}

void ensure_init(const Env& env, bool quiet) {
    auto marker = paths::sandbox_init_marker(env);
    if (std::filesystem::exists(marker)) return;

    // Ensure the home directory exists before cd'ing into it.
    std::error_code ec;
    std::filesystem::create_directories(env.home, ec);

    if (!quiet)
        print_status("Initialize", "mcpp sandbox layout (one-time)");
    mcpp::log::ScopedTimer _t_init("init", "sandbox layout (xlings self init)");
    std::string cmd;
    if constexpr (mcpp::platform::is_windows) {
        mcpp::platform::env::set("XLINGS_HOME", env.home.string());
        mcpp::platform::env::set("XLINGS_PROJECT_DIR", "");
        cmd = env.binary.string() + " self init "
            + std::string(mcpp::platform::shell::silent_redirect);
    } else {
        cmd = std::format(
            "cd {} && env -u XLINGS_PROJECT_DIR XLINGS_HOME={} {} self init {}",
            shq(env.home.string()),
            shq(env.home.string()),
            shq(env.binary.string()),
            mcpp::platform::shell::silent_redirect);
    }
    int rc = mcpp::platform::process::run_silent(cmd);
    if (rc != 0 && !quiet) {
        std::println(stderr,
            "warning: `xlings self init` failed for sandbox at '{}'",
            env.home.string());
    }

    // The first real `xlings install` (the next bootstrap step) triggers
    // xlings to fetch its package index — a one-time, network-bound step
    // with no output of its own. Announce it so the user knows the silent
    // wait that follows is expected. This runs once: ensure_init is gated
    // by the sandbox-init marker above.
    if (!quiet)
        print_status("Fetching", "package index (one-time)");
}

void ensure_patchelf(const Env& env, bool quiet,
                     const BootstrapProgressCallback& cb)
{
    auto toolDir = paths::xim_tool(env, "patchelf", pinned::kPatchelfVersion);
    auto binary  = toolDir / "bin" / "patchelf";
    if (std::filesystem::exists(binary)) return;

    // Clean up incomplete installation residue (e.g. from Ctrl+C interrupt).
    if (std::filesystem::exists(toolDir)) {
        if (!quiet)
            print_status("Repairing", "patchelf (incomplete installation, cleaning up)");
        std::error_code ec;
        std::filesystem::remove_all(toolDir, ec);
    }

    if (!quiet)
        print_status("Bootstrap", "patchelf into mcpp sandbox (one-time)");
    mcpp::log::ScopedTimer _t_pe("init", std::format("bootstrap patchelf@{}", pinned::kPatchelfVersion));
    int rc = install_with_progress(env,
        std::format("xim:patchelf@{}", pinned::kPatchelfVersion), cb, quiet);
    if (rc != 0 && !quiet) {
        std::println(stderr,
            "warning: failed to bootstrap patchelf into mcpp sandbox; "
            "subsequent xim installs may skip ELF rewriting");
    }
}

void ensure_ninja(const Env& env, bool quiet,
                  const BootstrapProgressCallback& cb)
{
    auto root = paths::xim_tool_root(env, "ninja");
    auto ninja_name = std::string("ninja") + std::string(mcpp::platform::exe_suffix);
    if (std::filesystem::exists(root)) {
        std::error_code ec;
        for (auto& v : std::filesystem::directory_iterator(root, ec)) {
            if (std::filesystem::exists(v.path() / ninja_name)) return;
        }
        // Directory exists but no version has a working binary — residue.
        if (!quiet)
            print_status("Repairing", "ninja (incomplete installation, cleaning up)");
        std::filesystem::remove_all(root, ec);
    }
    if (!quiet)
        print_status("Bootstrap", "ninja into mcpp sandbox (one-time)");
    mcpp::log::ScopedTimer _t_ninja("init", std::format("bootstrap ninja@{}", pinned::kNinjaVersion));
    int rc = install_with_progress(env,
        std::format("xim:ninja@{}", pinned::kNinjaVersion), cb, quiet);
    if (rc != 0 && !quiet) {
        std::println(stderr,
            "warning: failed to bootstrap ninja into mcpp sandbox (exit {})",
            rc);
    }
}

namespace {

// "NASM version 2.16.03 compiled on ..." → true iff ≥ 2.16. A binary that
// fails to run or reports something unparseable is unusable — false.
bool nasm_version_ok(const std::filesystem::path& bin) {
    auto r = mcpp::platform::process::capture_exec({bin.string(), "-v"});
    if (r.exit_code != 0) return false;
    auto pos = r.output.find("version ");
    if (pos == std::string::npos) return false;
    int major = 0, minor = 0;
    const char* p = r.output.c_str() + pos + 8;
    while (*p >= '0' && *p <= '9') major = major * 10 + (*p++ - '0');
    if (*p++ != '.') return false;
    while (*p >= '0' && *p <= '9') minor = minor * 10 + (*p++ - '0');
    return major > 2 || (major == 2 && minor >= 16);
}

} // namespace

std::optional<std::filesystem::path> find_sandbox_nasm(const Env& env) {
    auto root = paths::xim_tool_root(env, "nasm");
    auto nasm_name = std::string("nasm") + std::string(mcpp::platform::exe_suffix);
    std::error_code ec;
    if (!std::filesystem::exists(root, ec)) return std::nullopt;
    for (auto& v : std::filesystem::directory_iterator(root, ec)) {
        for (auto cand : { v.path() / nasm_name, v.path() / "bin" / nasm_name }) {
            if (std::filesystem::exists(cand, ec) && nasm_version_ok(cand))
                return cand;
        }
    }
    return std::nullopt;
}

std::optional<std::filesystem::path> find_usable_nasm(const Env& env) {
    auto nasm_name = std::string("nasm") + std::string(mcpp::platform::exe_suffix);
    if (auto sys = mcpp::platform::fs::which(nasm_name);
        sys && nasm_version_ok(*sys)) {
        return sys;
    }
    return find_sandbox_nasm(env);
}

// ─── Index freshness ────────────────────────────────────────────────

bool is_index_fresh(const Env& env, std::int64_t ttlSeconds) {
    return is_index_dir_fresh(default_index_dir(env), ttlSeconds);
}

bool is_official_index_fresh(const Env& env, std::int64_t ttlSeconds) {
    return is_index_dir_fresh(official_index_dir(env), ttlSeconds);
}

IndexStatus default_index_status(const Env& env, std::int64_t ttlSeconds) {
    return index_status_for(default_index_dir(env), ttlSeconds);
}

IndexStatus official_index_status(const Env& env, std::int64_t ttlSeconds) {
    return index_status_for(official_index_dir(env), ttlSeconds);
}

bool is_official_package_index_fresh(const Env& env,
                                     std::string_view packageName,
                                     std::int64_t ttlSeconds) {
    if (!is_official_index_fresh(env, ttlSeconds)) return false;
    auto pkg = official_package_file(env, packageName);
    return !pkg.empty()
        && std::filesystem::exists(pkg)
        && official_index_cache_matches_package_file(env, packageName);
}

namespace {
// The raw sync. Everything that makes a refresh SAFE lives in the wrapper
// below; this function's only job is to run `xlings update` and report.
int update_index_unguarded(const Env& env, bool quiet);
} // namespace

// Guarded entry point — the ONE place every refresh in this process passes
// through, which is why the monotonicity guarantee is installed here rather
// than at the seven call sites.
//
//   an index-side change must never take mcpp from "works" to "does not work"
//
// A published index can raise its client-version floor (index.toml min_mcpp).
// `xlings update` rewrites the tree in place, so before this guard existed a
// floor bump replaced a readable index with an unreadable one and left no way
// back — the refresh itself was the thing that broke the machine. See
// mcpp.pm.index_snapshot for why the shape is archive/judge/restore rather
// than the stage-and-swap the original design assumed.
int update_index(const Env& env, bool quiet) {
    namespace snap = mcpp::pm::index_snapshot;
    const auto dataRoot = paths::index_data(env);

    snap::GuardOutcome out;
    int rc = snap::guarded_refresh(dataRoot,
        [&] { return update_index_unguarded(env, quiet); }, out);

    // Report ONLY when the guard had to act. The common path — refresh keeps
    // the index readable — must stay silent, or the notice becomes noise that
    // users learn to skip past, which is the same as not printing it.
    for (auto& dir : out.rolledBack) {
        print_status("Kept", std::format(
            "previous index for `{}` — the refreshed one requires a newer mcpp",
            dir.filename().string()));
        if (!quiet) {
            std::println("      Your build continues to work with the packages "
                         "it already describes.");
            std::println("      Upgrade to pick up newer packages:  xlings update mcpp");
        }
    }
    for (auto& dir : out.recovered) {
        print_status("Restored", std::format(
            "index `{}` from a local snapshot this mcpp can read",
            dir.filename().string()));
    }
    for (auto& dir : out.stillUnusable) {
        mcpp::log::verbose("index", std::format(
            "index `{}` requires a newer mcpp and no local snapshot is usable",
            dir.filename().string()));
    }
    return rc;
}

namespace {
int update_index_unguarded(const Env& env, bool quiet) {
    // Offline is absolute: no caller gets to reach the network by going around
    // the decision layer. Reported as success so a build that can still resolve
    // everything locally proceeds — the caller that genuinely needed the data
    // fails on its own missing answer, with a message that says so.
    if (mcpp::platform::env::offline_mode()) {
        mcpp::log::verbose("index", "offline mode: skipping index update");
        return 0;
    }

    // Cross-process mutex. The sync rewrites a tree several concurrent mcpp
    // processes read (parallel CI jobs on one MCPP_HOME, two terminals, a
    // workspace fan-out), and it also writes the refresh markers. The BMI cache
    // has had this guard for a while; the index never did.
    //
    // NON-BLOCKING BY DESIGN: whoever holds the lock is already doing the exact
    // work we wanted, so waiting buys nothing and a queue of stalled builds is
    // precisely the symptom this whole change exists to remove. Skipping is
    // also why this must not be reported as failure.
    std::error_code lockEc;
    std::filesystem::create_directories(paths::index_data(env), lockEc);
    auto lock = mcpp::platform::fs::FileLock::try_acquire(paths::index_data(env));
    if (!lock) {
        mcpp::log::verbose("index",
            "another process is refreshing the index — skipping this one");
        return 0;
    }

    std::string cmd = build_command_prefix(env) + " update 2>&1";
    // The index sync is a network git operation; a single transient blip (DNS,
    // TLS reset, a mirror hiccup) otherwise fails a cold `mcpp self env` /
    // first-run init outright (e.g. CI's index/sandbox bootstrap). Retry with
    // linear backoff. The success path returns on the FIRST attempt — zero
    // added latency in steady state; only a genuine failure pays the backoff.
    constexpr int kMaxAttempts = 3;
    int rc = 0;
    for (int attempt = 1; attempt <= kMaxAttempts; ++attempt) {
        rc = mcpp::platform::process::run_streaming(cmd,
            [quiet](std::string_view line) {
                if (!quiet) std::println("{}", line);
            });
        if (rc == 0) { mark_known_indexes_refreshed(env); return 0; }
        if (attempt < kMaxAttempts) {
            int delay = attempt * 2;  // 2s, then 4s
            mcpp::log::verbose("index", std::format(
                "index update attempt {}/{} failed (rc {}); retrying in {}s",
                attempt, kMaxAttempts, rc, delay));
            std::this_thread::sleep_for(std::chrono::seconds(delay));
        }
    }
    mcpp::log::verbose("index", std::format(
        "index update failed after {} attempts (rc {})", kMaxAttempts, rc));
    return rc;
}
} // namespace

void ensure_index_fresh(const Env& env, std::int64_t ttlSeconds, bool quiet) {
    if (is_index_fresh(env, ttlSeconds)) return;
    if (!quiet)
        print_status("Updating", "package index (auto-refresh)");
    update_index(env, /*quiet=*/true);
}

void ensure_official_index_fresh(const Env& env, std::int64_t ttlSeconds, bool quiet) {
    if (is_official_index_fresh(env, ttlSeconds)) return;
    if (!quiet)
        print_status("Updating", "package index (auto-refresh)");
    update_index(env, /*quiet=*/true);
}

void ensure_official_package_index_fresh(const Env& env,
                                         std::string_view packageName,
                                         [[maybe_unused]] std::int64_t ttlSeconds,
                                         bool quiet) {
    // Offline-first, miss-triggered. We do NOT auto-update just because a TTL
    // expired — that runs a network `xlings update` (git-syncs several index
    // repos) that stalls for minutes on slow/blocked networks (the Termux
    // first-run / build hang). But fully offline is too strict: if a requested
    // dependency is NOT in the local index, we DO refresh once to discover it.
    //
    //   present locally  → use as-is, zero network (the common build case).
    //   missing locally  → refresh once to try to fetch it.
    //
    // Routine, deps-already-present refresh stays the user's explicit
    // `mcpp index update` / `xlings update`.
    auto pkg = official_package_file(env, packageName);
    if (!pkg.empty() && std::filesystem::exists(pkg)) return;

    // The package is missing locally. Refresh once — but guard against a build
    // that resolves several genuinely-absent packages re-running the heavy
    // `xlings update` per package: if the index was refreshed moments ago and
    // the package is STILL missing, upstream simply lacks it; re-pulling won't
    // help. (A package added upstream before this run lands in that one pull.)
    if (is_official_index_fresh(env, kIndexRefreshDebounceSeconds)) return;

    if (!quiet)
        print_status("Refreshing",
            std::format("package index — `{}` not found locally (one-time)",
                        packageName));
    update_index(env, /*quiet=*/quiet);
}

} // namespace mcpp::xlings