feat(observability+resilience): MCPP_VERBOSE env + cold index-update retry

Two changes prompted by an opaque, repeatedly-reproducing CI failure in
75_index_status_offline.sh (a cold `mcpp self env` in a fresh MCPP_HOME whose
index/sandbox bootstrap fails fast — root cause swallowed in non-verbose logs;
verified NOT related to the feature/capability work, it fails identically on
main):

1. MCPP_VERBOSE env override (src/cli.cppm): MCPP_VERBOSE=<non-empty,!=0> turns
   on verbose logging for EVERY mcpp invocation, including those nested inside
   e2e test scripts that call $MCPP without flags. An explicit --quiet still
   wins. Set MCPP_VERBOSE: "1" in all CI workflows (ci-linux, ci-linux-e2e,
   ci-macos, ci-windows, cross-build-test, ci-fresh-install,
   ci-aarch64-fresh-install) so failures carry full diagnostics. Complements the
   existing MCPP_LOG_LEVEL (which only sets the FILE log level, not stderr).

2. update_index retry (src/xlings.cppm): the index sync is a network git op;
   a single transient blip otherwise fails cold init outright. Bounded retry
   with linear backoff (3 attempts, 2s/4s). Success returns on the first
   attempt — zero added latency in steady state; only a real failure pays the
   backoff. Retry notices go through mcpp::log::verbose (file always, stderr
   under MCPP_VERBOSE).

This PR's own e2e CI run carries MCPP_VERBOSE=1, so it surfaces the real cause
of the 75 bootstrap failure for a targeted follow-up.

Author: Sunrisepeak

.github/workflows/ci-aarch64-fresh-install.yml

@@ -30,6 +30,9 @@ jobs:
     name: fresh install + native build (aarch64 / glibc)
     runs-on: ubuntu-24.04-arm
     timeout-minutes: 60
+    env:
+      # Verbose every mcpp invocation — cold bootstrap path (src/cli.cppm).
+      MCPP_VERBOSE: "1"
     steps:
       - name: System info
         run: |

.github/workflows/ci-fresh-install.yml

@@ -30,6 +30,10 @@ jobs:
     name: Linux fresh install
     runs-on: ubuntu-24.04
     timeout-minutes: 60
+    env:
+      # Verbose every mcpp invocation — fresh-install is the cold index/sandbox
+      # bootstrap path, exactly where extra diagnostics matter (src/cli.cppm).
+      MCPP_VERBOSE: "1"
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/ci-linux-e2e.yml

@@ -28,6 +28,10 @@ jobs:
     timeout-minutes: 45
     env:
       MCPP_HOME: /home/runner/.mcpp
+      # Verbose every mcpp invocation (incl. those nested in e2e scripts) so CI
+      # logs carry full diagnostics for failures like a cold index/sandbox
+      # bootstrap. Honoured via the MCPP_VERBOSE override in src/cli.cppm.
+      MCPP_VERBOSE: "1"
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/ci-linux.yml

@@ -32,6 +32,8 @@ jobs:
       # MCPP_HOME pinned so the cache key below restores into the
       # same path mcpp resolves at runtime.
       MCPP_HOME: /home/runner/.mcpp
+      # Verbose every mcpp invocation for richer CI diagnostics (src/cli.cppm).
+      MCPP_VERBOSE: "1"
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/ci-macos.yml

@@ -19,6 +19,9 @@ jobs:
     name: macOS ARM64 — xlings LLVM end-to-end
     runs-on: macos-15
     timeout-minutes: 30
+    env:
+      # Verbose every mcpp invocation for richer CI diagnostics (src/cli.cppm).
+      MCPP_VERBOSE: "1"
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/ci-windows.yml

@@ -21,6 +21,8 @@ jobs:
     timeout-minutes: 45
     env:
       MCPP_HOME: C:\Users\runneradmin\.mcpp
+      # Verbose every mcpp invocation for richer CI diagnostics (src/cli.cppm).
+      MCPP_VERBOSE: "1"
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/cross-build-test.yml

@@ -57,6 +57,8 @@ jobs:
             qemu_bin: qemu-aarch64-static
     env:
       MCPP_HOME: /home/runner/.mcpp
+      # Verbose every mcpp invocation for richer CI diagnostics (src/cli.cppm).
+      MCPP_VERBOSE: "1"
     steps:
       - uses: actions/checkout@v4
 

src/cli.cppm

@@ -101,6 +101,14 @@ int run(int argc, char** argv) {
         else if (a == "--no-color")           mcpp::ui::disable_color();
         else if (a == "--verbose" || a == "-v") mcpp::log::set_verbose(true);
     }
+    // Env override (observability, esp. CI): MCPP_VERBOSE=<non-empty, not "0">
+    // turns on verbose logging for EVERY mcpp invocation — including the ones
+    // nested inside e2e test scripts that call $MCPP without flags. Lets a
+    // workflow flip on diagnostics globally with one env var. An explicit
+    // --quiet still wins (it is processed above and gates the verbose sinks).
+    if (const char* v = std::getenv("MCPP_VERBOSE");
+        v && *v && std::string_view(v) != "0")
+        mcpp::log::set_verbose(true);
 
     // ─── top-level --help / -h / --version intercept ────────────────────
     // cmdline auto-handles these but its formatter doesn't match the

src/xlings.cppm

@@ -1232,11 +1232,29 @@ bool is_official_package_index_fresh(const Env& env,
 
 int update_index(const Env& env, bool quiet) {
     std::string cmd = build_command_prefix(env) + " update 2>&1";
-    int 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);
+    // 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;
 }