fix: address round-2 review — 4 issues

1. toolchain install now calls check_base_init() before proceeding,
   failing early if patchelf/ninja bootstrap is incomplete

2. Preserve original xlings install error (exit code + message) in
   final error instead of masking with generic "payload missing"

3. One-time legacy migration: migrate_legacy_installs() scans xpkgs
   and writes .mcpp_ok markers for old complete packages on first run.
   is_install_complete() still has legacy fallback for un-migrated
   packages but migration ensures it's rarely needed.

4. Clean trailing whitespace in .agents/docs/*.md

Author: Sunrisepeak

.agents/docs/2026-05-22-copy-priority-analysis.md

@@ -148,7 +148,7 @@ resolve_xpkg_path(target, autoInstall):
 
 ### 方案 C：install 优先 + install 直接调用（非 NDJSON）
 
-之前排查发现 NDJSON interface 路径安装大包不可靠。`install_with_progress()` 
+之前排查发现 NDJSON interface 路径安装大包不可靠。`install_with_progress()`
 已有"直接调用" fallback（`std::system("xlings install ... -y")`）。
 
 将工具链安装改为使用 `install_with_progress()`（直接调用模式）而非

.agents/docs/2026-05-22-ensure-base-init-design.md

@@ -95,12 +95,12 @@ config::load_or_init()
 std::expected<void, ConfigError>
 ensure_base_init_ok(const GlobalConfig& cfg) {
     auto xlEnv = make_xlings_env(cfg);
-    
+
     struct Check {
         std::string_view name;
         std::filesystem::path path;
     };
-    
+
     Check checks[] = {
         {"xlings binary",  cfg.xlingsBinary},
         {"sandbox marker", xlEnv.home / "subos" / "default" / ".xlings.json"},
@@ -109,7 +109,7 @@ ensure_base_init_ok(const GlobalConfig& cfg) {
         {"ninja",          mcpp::xlings::paths::xim_tool(xlEnv, "ninja",
                                mcpp::xlings::pinned::kNinjaVersion) / "bin" / "ninja"},
     };
-    
+
     for (auto& c : checks) {
         if (!std::filesystem::exists(c.path)) {
             return std::unexpected(ConfigError{std::format(
@@ -127,7 +127,7 @@ ensure_base_init_ok(const GlobalConfig& cfg) {
 ```cpp
 int cmd_self_init(const ParsedArgs& parsed) {
     bool force = parsed.is_flag_set("force");
-    
+
     if (force) {
         // 删除 bootstrap 状态（不删整个 ~/.mcpp/，保留 config.toml 和 toolchain）
         auto xlHome = cfg->xlingsHome();
@@ -140,12 +140,12 @@ int cmd_self_init(const ParsedArgs& parsed) {
             std::filesystem::remove_all(xpkgs / prefix, ec);
         }
     }
-    
+
     // 重新 bootstrap（复用 load_or_init 的 bootstrap 逻辑）
     ensure_init(xlEnv, false);
     ensure_patchelf(xlEnv, false, nullptr);
     ensure_ninja(xlEnv, false, nullptr);
-    
+
     // 验证
     auto check = ensure_base_init_ok(*cfg);
     if (!check) {

.agents/docs/2026-05-22-fallback-architecture-design.md

@@ -331,7 +331,7 @@ resolve()
 └── 返回 error
 
 install()（只有 resolve 失败才走到）
-  
+
 resolve()（第二次，install 后）
 ├── sandbox 有？→ 返回
 ├── ~/.xlings/ 有？→ copy → 返回
@@ -366,11 +366,11 @@ auto resolve_quick = [&]() -> std::optional<XpkgPayload> {
 
 auto resolve_with_copy_fallback = [&]() -> std::expected<XpkgPayload, CallError> {
     if (auto p = resolve_quick()) return *p;
-    
+
     // FALLBACK: copy from global xlings
     mcpp::log::verbose("fetcher", "[fallback:xpkg.copy_from_global]");
     // ... copy logic (existing code)
-    
+
     if (auto p = resolve_quick()) return *p;
     return std::unexpected(CallError{"xpkg payload missing: " + verdir.string()});
 };

src/cli.cppm

@@ -3726,6 +3726,17 @@ int cmd_toolchain(const mcpplibs::cmdline::ParsedArgs& parsed) {
     }
 
     if (subname == "install") {
+        // Toolchain install needs patchelf (ELF fixup) and ninja (build).
+        // Fail early if bootstrap is incomplete rather than producing a
+        // broken toolchain with missing fixups.
+        auto bsProblem = mcpp::config::check_base_init(*cfg);
+        if (!bsProblem.empty()) {
+            mcpp::ui::error(std::format(
+                "{}\n  hint: run `mcpp self init --force` to reset and re-initialize",
+                bsProblem));
+            return 1;
+        }
+
         // Accept three input shapes — they all collapse to (compiler, version):
         //   mcpp toolchain install gcc 16.1.0      → ("gcc", "16.1.0")
         //   mcpp toolchain install gcc@16.1.0      → ("gcc", "16.1.0")

src/config.cppm

@@ -558,7 +558,14 @@ std::expected<GlobalConfig, ConfigError> load_or_init(
         }
     }
 
-    // 8. Bootstrap check is NOT done here — it's deferred to commands that
+    // 8. One-time migration: mark legacy xpkgs (installed before .mcpp_ok
+    //    was introduced) so they aren't mistaken for incomplete installs.
+    {
+        auto xpkgsBase = cfg.xlingsHome() / "data" / "xpkgs";
+        mcpp::fallback::migrate_legacy_installs(xpkgsBase);
+    }
+
+    // 9. Bootstrap check is NOT done here — it's deferred to commands that
     //    actually need bootstrap tools (build, run, toolchain install).
     //    Light commands (self env, toolchain list) should work even if
     //    bootstrap is incomplete. Commands call check_base_init() themselves.

src/fallback/install_integrity.cppm

@@ -52,28 +52,29 @@ bool clean_incomplete_install(const std::filesystem::path& xpkgDir);
 // Returns number of directories cleaned.
 int clean_all_incomplete(const std::filesystem::path& xpkgsBase);
 
+// One-time migration: scan xpkgs and write .mcpp_ok markers for all
+// old packages that look complete but lack a marker. After migration,
+// is_install_complete() uses strict marker-only semantics. Returns
+// number of packages migrated.
+int migrate_legacy_installs(const std::filesystem::path& xpkgsBase);
+
 } // namespace mcpp::fallback
 
 // ─── Implementation ─────────────────────────────────────────────────
 
 namespace mcpp::fallback {
 
-bool is_install_complete(const std::filesystem::path& xpkgDir) {
-    if (!std::filesystem::exists(xpkgDir)) return false;
+namespace {
 
-    // Primary: .mcpp_ok marker
-    if (std::filesystem::exists(xpkgDir / std::string(kInstallMarker)))
-        return true;
-
-    // Backward compat: no marker but has content directories
-    // (installed before this feature was added)
-    // Check top-level content dirs (xim toolchain packages).
+// Heuristic: does this directory look like a complete xpkg?
+// Used ONLY for legacy migration (pre-.mcpp_ok packages).
+bool looks_complete_legacy(const std::filesystem::path& xpkgDir) {
+    // xim toolchain/tool packages: top-level bin/lib/lib64/include/share
     for (auto dir : {"bin", "lib", "lib64", "include", "share"}) {
         if (std::filesystem::exists(xpkgDir / dir))
             return true;
     }
-    // Check for mcpplibs layout: single subdirectory containing src/ or
-    // mcpp.toml (extracted tarball). E.g. verdir/cmdline-0.0.1/src/...
+    // mcpplibs layout: single subdirectory containing src/ or mcpp.toml
     std::error_code ec;
     std::vector<std::filesystem::path> subs;
     for (auto& e : std::filesystem::directory_iterator(xpkgDir, ec)) {
@@ -90,6 +91,22 @@ bool is_install_complete(const std::filesystem::path& xpkgDir) {
     return false;
 }
 
+} // namespace
+
+bool is_install_complete(const std::filesystem::path& xpkgDir) {
+    if (!std::filesystem::exists(xpkgDir)) return false;
+
+    // Strict: .mcpp_ok marker is the sole authority.
+    // Legacy packages should have been migrated (marker added) during
+    // the first load_or_init() after upgrading to this version.
+    if (std::filesystem::exists(xpkgDir / std::string(kInstallMarker)))
+        return true;
+
+    // Fallback for un-migrated packages (e.g. first run after upgrade
+    // before migration has a chance to run).
+    return looks_complete_legacy(xpkgDir);
+}
+
 void mark_install_complete(const std::filesystem::path& xpkgDir) {
     auto marker = xpkgDir / std::string(kInstallMarker);
     if (std::filesystem::exists(marker)) return;
@@ -124,4 +141,24 @@ int clean_all_incomplete(const std::filesystem::path& xpkgsBase) {
     return cleaned;
 }
 
+int migrate_legacy_installs(const std::filesystem::path& xpkgsBase) {
+    if (!std::filesystem::exists(xpkgsBase)) return 0;
+
+    int migrated = 0;
+    std::error_code ec;
+    for (auto& pkgDir : std::filesystem::directory_iterator(xpkgsBase, ec)) {
+        if (!pkgDir.is_directory()) continue;
+        for (auto& verDir : std::filesystem::directory_iterator(pkgDir.path(), ec)) {
+            if (!verDir.is_directory()) continue;
+            auto marker = verDir.path() / std::string(kInstallMarker);
+            if (std::filesystem::exists(marker)) continue;
+            if (looks_complete_legacy(verDir.path())) {
+                mark_install_complete(verDir.path());
+                ++migrated;
+            }
+        }
+    }
+    return migrated;
+}
+
 } // namespace mcpp::fallback

src/pm/package_fetcher.cppm

@@ -659,6 +659,7 @@ Fetcher::resolve_xpkg_path(std::string_view target,
     mcpp::fallback::clean_incomplete_install(verdir);
 
     // 3. Install via xlings (primary path).
+    std::string installError;  // preserved for final error message
     if (autoInstall) {
         std::vector<std::string> targets {
             std::format("{}:{}@{}", parsed.indexName, parsed.packageName, parsed.version)
@@ -677,8 +678,14 @@ Fetcher::resolve_xpkg_path(std::string_view target,
         // Install failed → clean residue so next attempt starts fresh.
         mcpp::fallback::clean_incomplete_install(verdir);
         if (inst->exitCode != 0) {
+            installError = std::format(
+                "xlings install of '{}:{}@{}' failed (exit {})",
+                parsed.indexName, parsed.packageName, parsed.version,
+                inst->exitCode);
+            if (inst->error)
+                installError += ": " + inst->error->message;
             mcpp::log::warn("fetcher", std::format(
-                "xlings install exit={}, trying fallback", inst->exitCode));
+                "{}, trying fallback", installError));
         }
     }
 
@@ -692,6 +699,12 @@ Fetcher::resolve_xpkg_path(std::string_view target,
     // Copy failed or incomplete — clean partial copy.
     mcpp::fallback::clean_incomplete_install(verdir);
 
+    // 5. All paths exhausted — return the most informative error.
+    if (!installError.empty()) {
+        return std::unexpected(CallError{std::format(
+            "{}\n  hint: check network and retry, or `mcpp self init --force`",
+            installError)});
+    }
     return std::unexpected(CallError{
         std::format("xpkg payload missing: {}\n"
                     "  hint: check network and retry, or `mcpp self init --force`",