fix(config): offline mode skips the first-use sandbox bootstrap

--offline promises never to touch the network. In a home that had never
been used, load_or_init cloned the package index through `xlings self
init` and installed ninja and patchelf through `xlings install` before any
command ran: measured, 26 s and 126 MB under MCPP_OFFLINE=1.

The three network-bound steps are now skipped under offline mode, the skip
is announced once per process, and the completion markers are still
written from what is on disk, so a bootstrapped home loses nothing. The
commands that need the tools report their absence through check_base_init.
e2e 604 asserts the fresh-home behaviour and, as its control, that a
bootstrapped home announces nothing.

Author: speak-agent

.agents/docs/2026-09-05-multi-device-implementation-plan.md

@@ -133,3 +133,6 @@
 | 2026-09-05 | T2.4 完成 | `exclusive` 是列表不是布尔:一个包可提供多项能力而只有部分独占。schema 警告而非报错,因为绑定期那一处才是执行者 |
 | 2026-09-05 | ⚠️ 本机 shim 被 #582 剪掉一次 | 25 次 `xlings install` 后 `mcpp` 等 7 个裸名 shim 消失,store 完好。重装即恢复 —— 又一次受控复现,补进 issue |
 | 2026-09-05 | `libcublas` 暂不拆 static | 上游一个归档同时含 shared 与 static,拆分需要重打包并 re-host,与「不 re-host」冲突;先按上游形态发,拆分单列 |
+| 2026-09-05 | e2e 317 的等待窗从 2s 放宽到 5s | 到达「五次短失败」下界最少要 1.25s(4×250ms 重启延迟 + 5×50ms 轮询),2s 窗只给每次 spawn 留 150ms;main 上 macOS **连续两次**在此失败而本分支同码两次通过 —— 判据由 runner 负载决定。5s 窗留 750ms |
+| 2026-09-05 | e2e 602 声明 `requires: unix-shell`,并以 `MCPP_OFFLINE=1` 运行 | doctor 在 Windows 上整段不产出(载荷只有 linux 构建;Windows 工具包的上界是 `_MSC_VER` 区间,报告尚未读它);隔离 home 下 doctor 会把整套引导 + 工具链装进临时目录:实测 229s / 1.4 GB |
+| 2026-09-05 | ⚠️ 核心改动:`--offline` 下跳过首次沙箱引导 | `load_or_init` 在空 home 里克隆索引、经 `xlings install` 装 ninja/patchelf,全部走网络,违反 `--offline`「绝不碰网络」的承诺。实测 offline 空 home 26s / 126 MB → 0.3s;e2e 604 带对照(已引导的 home 不提示);文档中英各补一句 |

docs/00-getting-started.md

@@ -196,4 +196,4 @@ For the differences between the four modes and their artifact layouts, see [02 
   default/sole template, or run `mcpp new --list-templates ocornut.imgui@1.92.8`).
 - Explaining default decisions: `mcpp why [toolchain|runtime|deps]`; host capability checkup: `mcpp self doctor`;
   machine-readable resolution manifest: the build artifact `target/<triple>/<fp>/resolution.json`.
-- Offline operation: `mcpp --offline` or `MCPP_OFFLINE=1` prevents index refreshes, downloads, and toolchain installation.
+- Offline operation: `mcpp --offline` or `MCPP_OFFLINE=1` prevents index refreshes, downloads, and toolchain installation. In a home that has never been used it also skips the first-use sandbox bootstrap (index clone, ninja, patchelf), announces the skip once, and leaves the home un-bootstrapped; commands that need those tools report it.

docs/zh/00-getting-started.md

@@ -183,4 +183,4 @@ mcpp pack --mode self-contained    # 打包 loader、libc 与依赖
   `mcpp new --list-templates ocornut.imgui@1.92.8`)。
 - 解释默认决策:`mcpp why [toolchain|runtime|deps]`;主机能力体检:`mcpp self doctor`;
   机器可读解析清单:构建产物 `target/<triple>/<fp>/resolution.json`。
-- 离线运行:`mcpp --offline` 或 `MCPP_OFFLINE=1` 可阻止索引刷新、下载和工具链安装。
+- 离线运行:`mcpp --offline` 或 `MCPP_OFFLINE=1` 可阻止索引刷新、下载和工具链安装。在从未使用过的 home 中,它同时跳过首次使用时的沙箱引导(索引克隆、ninja、patchelf),只提示一次,并让该 home 保持未引导状态;需要这些工具的命令会自行报告。

src/config.cppm

@@ -625,13 +625,40 @@ std::expected<GlobalConfig, ConfigError> load_or_init(
     //    TODO(xlings-upstream): collapse into a single
     //    `xlings sandbox bootstrap --home <X>` once that command exists
     //    upstream (see docs/short-term-vs-long-track plan).
+    //
+    //    NOT UNDER --offline. Each of the three steps below reaches the
+    //    network when the sandbox is fresh: `xlings self init` clones the
+    //    package index, and patchelf and ninja arrive through `xlings
+    //    install`. `--offline` promises never to touch the network, and an
+    //    empty home is exactly where that promise was being broken --
+    //    measured: `MCPP_OFFLINE=1 mcpp self doctor` in a fresh home fetched
+    //    the index and 126 MB of tools before running its first check.
+    //
+    //    A bootstrapped home loses nothing: every step is a no-op once its
+    //    artefact exists, and the completion markers below are still written
+    //    from what is on disk. A fresh home stays un-bootstrapped, and the
+    //    commands that need the tools say so through check_base_init().
+    const bool bootstrapAllowed = !mcpp::platform::env::offline_mode();
     ensure_sandbox_xlings_binary(cfg, quiet);
-    ensure_sandbox_init(cfg, quiet);
+    if (bootstrapAllowed) {
+        ensure_sandbox_init(cfg, quiet);
+    } else if (!quiet) {
+        // Once per process: the doctor loads the configuration more than once,
+        // and the same sentence twice reads as two events.
+        static bool announced = false;
+        auto marker = mcpp::xlings::paths::sandbox_init_marker(make_xlings_env(cfg));
+        if (!announced && !std::filesystem::exists(marker)) {
+            announced = true;
+            print_status("Skipping",
+                "sandbox bootstrap (offline mode; run without --offline to bootstrap)");
+        }
+    }
     {
         auto bsEnv = make_xlings_env(cfg);
 #if !defined(__APPLE__) && !defined(_WIN32)
         // patchelf is ELF-only; macOS uses Mach-O and Windows uses PE.
-        ensure_sandbox_patchelf(cfg, quiet, onBootstrapProgress);
+        if (bootstrapAllowed)
+            ensure_sandbox_patchelf(cfg, quiet, onBootstrapProgress);
         // Only mark complete if the actual binary exists (not just the dir).
         {
             auto pBin = mcpp::xlings::paths::xim_tool(bsEnv, "patchelf",
@@ -640,7 +667,8 @@ std::expected<GlobalConfig, ConfigError> load_or_init(
                 mcpp::fallback::mark_install_complete(pBin.parent_path().parent_path());
         }
 #endif
-        ensure_sandbox_ninja(cfg, quiet, onBootstrapProgress);
+        if (bootstrapAllowed)
+            ensure_sandbox_ninja(cfg, quiet, onBootstrapProgress);
         {
             auto nRoot = mcpp::xlings::paths::xim_tool_root(bsEnv, "ninja");
             auto ninja_name = std::string("ninja") + std::string(mcpp::platform::exe_suffix);

tests/e2e/604_offline_skips_sandbox_bootstrap.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# `--offline` promises never to touch the network, and a fresh home is where
+# that promise was being broken: the sandbox bootstrap that `load_or_init` runs
+# on first use clones the package index and installs ninja and patchelf through
+# `xlings install`. Measured before the gate, `MCPP_OFFLINE=1 mcpp self doctor`
+# in an empty home spent 26 seconds and wrote 126 MB before its first check.
+#
+# Under offline mode the three network-bound steps are skipped, once, visibly,
+# and the command goes on to its remaining checks. A home that is already
+# bootstrapped says nothing, because there is nothing to skip.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+
+# ── A fresh home under offline mode is left un-bootstrapped ─────────────
+out="$TMP/fresh.log"
+MCPP_HOME="$TMP/home" MCPP_OFFLINE=1 "$MCPP" self doctor > "$out" 2>&1 || true
+
+n=$(grep -c "Skipping sandbox bootstrap (offline mode" "$out" || true)
+[[ "$n" -eq 1 ]] || {
+    cat "$out"; echo "FAIL: expected the skip to be announced once, saw $n"; exit 1; }
+
+# The index clone is the first network step and the largest; its absence is
+# the structural evidence that nothing was fetched.
+[[ ! -e "$TMP/home/registry/data/xim-pkgindex" ]] || {
+    echo "FAIL: the package index was cloned under offline mode"; exit 1; }
+[[ ! -e "$TMP/home/registry/subos/default/.xlings.json" ]] || {
+    echo "FAIL: the sandbox was initialised under offline mode"; exit 1; }
+
+# Skipping the bootstrap must not end the command: the checks after the
+# registry one still run.
+grep -q "Checking build policy" "$out" || {
+    cat "$out"; echo "FAIL: the doctor stopped at the registry check"; exit 1; }
+echo "PASS: a fresh home under offline mode is left un-bootstrapped, audibly"
+
+# ── Control: a bootstrapped home has nothing to skip and says nothing ───
+#
+# Without this, a doctor that printed the sentence on every offline run would
+# pass the count above. The e2e runner's own home is bootstrapped by the time
+# this script runs.
+out2="$TMP/warm.log"
+MCPP_OFFLINE=1 "$MCPP" self doctor > "$out2" 2>&1 || true
+if grep -q "Skipping sandbox bootstrap" "$out2"; then
+    cat "$out2"; echo "FAIL: a bootstrapped home announced a skip"; exit 1
+fi
+echo "PASS: a bootstrapped home under offline mode announces nothing"
+
+echo "PASS: offline skips the sandbox bootstrap"