feat(index): miss-triggered refresh — fetch once when a dep isn't local

Refine the offline-first gate per review: fully offline is too strict. Keep
the common case zero-network (dependency present in the local index), but
when a requested dependency is NOT in the local index, refresh once to fetch
it — instead of failing offline.

- Announce it: the build path now calls with quiet=false, printing
  'Refreshing package index — `<pkg>` not found locally (one-time)' so a
  rare one-time network pause doesn't look like a silent hang. Steady-state
  builds (deps present) still print nothing.
- Guard against thrash: if the index was refreshed <120s ago and the package
  is still missing, upstream genuinely lacks it — don't re-run the heavy
  `xlings update` per missing package in one build.

src/xlings.cppm: rework ensure_official_package_index_fresh.
src/pm/package_fetcher.cppm: quiet=false at the call site.
docs: correct the '稳态不再联网' wording to 'present→offline, missing→refresh once'.

Author: Sunrisepeak

.agents/docs/2026-06-24-offline-first-index-and-mcpp-index-publish.md

@@ -114,9 +114,15 @@ mcpp 第一次跑 / 沙盒初始化时(当前日志:`Initialize mcpp sandbox lay
 
 ### 4.1 实现进度(WS3)
 
-- **✅ P0②(build 离线优先)**:`ensure_official_package_index_fresh`(`src/xlings.cppm`)
-  不再因 TTL 过期就跑联网 `xlings update`;**只在本地索引项缺失(首次 / 没见过的包)时拉一次**。
-  稳态 `mcpp build` 不再联网 —— 直接消除 Termux 首跑/构建卡几分钟的根因(commit `f0f57ae`)。
+- **✅ P0②(build 离线优先 + 缺包触发刷新)**:`ensure_official_package_index_fresh`(`src/xlings.cppm`)
+  不再因 TTL 过期就跑联网 `xlings update`。改为 **miss-triggered**:
+  - **依赖在本地索引里 → 直接用,零网络**(常态 build,消除 Termux 首跑/构建卡几分钟的根因);
+  - **依赖在本地索引里查不到 → 自动刷新一次**去拉它(`mcpp build` 路径以 `quiet=false` 调用,
+    打印一行 `Refreshing package index — \`<pkg>\` not found locally`,让一次性网络停顿不像卡死)。
+  - **防重**:刚刷过(<120s)且包仍缺失 → 不再重复跑 `xlings update`(上游确实没有,重拉无益),
+    避免一个 build 里多个缺包各跑一遍全量 git 同步。
+  commit `f0f57ae`(初版纯离线)→ 增补 miss-triggered + 防重 + 可见提示。
+  > 即"完全不联网"过严;稳态(依赖齐全)不联网,**缺包则联网刷一次**,二者兼得。
 - **✅ P0③(`mcpp index status`)**:新增只读、**全程不联网**的 `mcpp index status`,显示
   xim/mcpplibs 两索引的 present/fresh/age/path;缺索引时提示显式 `mcpp index update`,否则确认本地可离线用。
   `src/xlings.cppm` 导出 `IndexStatus` + `{default,official}_index_status`;`src/pm/index_management.cppm`

src/pm/package_fetcher.cppm

@@ -725,8 +725,13 @@ Fetcher::resolve_xpkg_path(std::string_view target,
     if (autoInstall) {
         if (parsed.indexName == "xim") {
             mcpp::xlings::Env xlEnv{ cfg_.xlingsBinary, cfg_.xlingsHome() };
+            // quiet=false: this only ever prints when a dependency is missing
+            // from the local index and we refresh once to fetch it — a rare,
+            // intentional event worth surfacing so a one-time network pause
+            // doesn't look like a silent hang. Steady-state builds (deps
+            // present) return early without a word.
             mcpp::xlings::ensure_official_package_index_fresh(
-                xlEnv, parsed.packageName, cfg_.searchTtlSeconds, /*quiet=*/true);
+                xlEnv, parsed.packageName, cfg_.searchTtlSeconds, /*quiet=*/false);
         }
 
         std::vector<std::string> targets {

src/xlings.cppm

@@ -1248,19 +1248,33 @@ void ensure_official_package_index_fresh(const Env& env,
                                          std::string_view packageName,
                                          [[maybe_unused]] std::int64_t ttlSeconds,
                                          bool quiet) {
-    // Offline-first: an existing local index entry is used as-is. 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). Fetch ONLY when
-    // the entry is MISSING (first run / never-seen package), so the index is
-    // guaranteed to exist; routine refresh is the user's explicit
+    // 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.)
+    constexpr std::int64_t kJustRefreshedSeconds = 120;
+    if (is_official_index_fresh(env, kJustRefreshedSeconds)) return;
+
     if (!quiet)
-        print_status("Fetching",
-            std::format("index entry for {} (one-time)", packageName));
-    update_index(env, /*quiet=*/true);
+        print_status("Refreshing",
+            std::format("package index — `{}` not found locally (one-time)",
+                        packageName));
+    update_index(env, /*quiet=*/quiet);
 }
 
 } // namespace mcpp::xlings