Merge branch 'feat/m221-adoptcore-existing-versions-read-on'

crates/cli/src/cli/help.rs

@@ -17,6 +17,10 @@ pub const fn general() -> &'static str {
   instances launch-args <instance> [--jvm T] [--game T] [--memory MB] [--java P]
                      [--backend default|opengl|vulkan] [--clear]
                                       读/写实例级启动参数（不带选项 = 只读；--clear = 全部回跟随全局）
+  instances scan                      列出 versions/ 里已铺好的版本（含别的启动器装的）：能不能登记 + 原因
+  instances adopt <version-id> [--name N] [--isolation shared|isolated|custom] [--game-dir DIR]
+                [--dry-run]           把已铺好的版本登记成实例（只读外部、不搬文件；缺省运行目录
+                                      落 ULL 数据区的独立目录；--dry-run 只检查不写盘）
   install <version> [--loader X] [--loader-version V] [--name N] [--dry-run]
                                       下载并安装版本本体（--loader fabric|quilt|neoforge|forge
                                       时再叠一层加载器）→ 登记实例；--dry-run 只出计划
@@ -91,7 +95,43 @@ pub fn topic(name: &str) -> Option<&'static str> {
  每一项都是「实例 → 全局 → 默认」的独立回落，只填一项不会顶掉别的项。
  值以 `--` 开头时（多数游戏参数都是）写成 `--game=--fullscreen`：单独一个 `--fullscreen`
  会被当成下一个选项（缺少取值），这是全项目 CLI 的既有解析口径。
- --json 输出 {\"data\":{\"launch\":{…实例层…},\"effective\":{…回落后的生效值…}, …}}",
+ --json 输出 {\"data\":{\"launch\":{…实例层…},\"effective\":{…回落后的生效值…}, …}}
+
+%prog% instances scan
+
+列出当前游戏根 versions/ 里已经铺好的版本（可能是别的启动器装的），逐项给结论：
+ ✓ 可登记 / 已登记（附父链）；✗ 不可登记 + 每条原因（带稳定 code：manifest_missing /
+ manifest_invalid_json / missing_parent / circular_inheritance / outside_game_root …）。
+只读：不写文件、不改 mtime。versions/ 不存在 = 空结果；versions/ 读不了 = 报错（不当空列表）。
+ --json 输出 {\"data\":{\"game_root\":…,\"versions_dir\":…,\"counts\":{…},\"candidates\":[…]}}
+ 每个 candidate 带 {\"version_id\",\"jar_present\",\"inherits\",\"registered\",\"adoptable\",\"problems\"}。
+
+%prog% instances adopt <version-id> [--name N] [--isolation shared|isolated|custom]
+                       [--game-dir DIR] [--dry-run]
+
+把 versions/<id>/ 登记成实例：只读外部、只写自己的配置——不搬文件、不补清单、不改任何
+外部文件的 mtime（versions/ libraries/ assets/ 一个字节都不写）。不读任何启动器的账户凭据。
+ 运行目录（--gameDir）三档，缺省不沿用全局 isolated（那会把 mods/saves/config 造进
+ 别人的 versions/<id>/，那是别的启动器的版本目录）：
+   不给 --isolation     → <数据根>/.ULL/data/instances/<实例目录名>（新建空目录，隔离档写 custom）
+   --isolation shared   → 别人的游戏根（共用其 mods/saves/config；明确选择后才生效）
+   --isolation isolated → versions/<version-id>/（第一次启动会在这里新增玩家数据目录）
+   --isolation custom --game-dir DIR → 指定目录（DIR 必须是绝对路径；不新建、不改动其中内容）
+ 拒绝（退出码 1，原因逐条进 error.detail.problems）：
+   · 清单坏了 / 读不出来 / 缺 id / id 与目录名不一致
+   · 缺父版本 / 父链成环（说清缺哪个、环是什么）
+   · 条目解析到游戏根之外（符号链接/目录联接/祖先链接）；versions 入口存在但读不出来（断链）
+   · 配置写面被链到 .ULL 之外（config/、config/instances/、profiles.json 的真实落点）
+   · 写盘面与游戏树重叠（.ULL / data / 缺省运行目录解析后落进别人的 .minecraft）⇒ 换不重叠的数据目录；
+     整体迁移到游戏树之外仍允许
+   · 展示名已被别的实例占用；这个版本已经同名登记过（重复执行 = 无副作用失败）
+   · 缺省运行目录已存在且非空（空目录可复用；不猜「合并进已有实例」）
+   · 缺省目录会撞上别的实例（slug 同名 / 大小写不敏感）⇒ 自动顺延 -2/-3… 并点出撞的是谁；
+     撞满 32 个后缀才报错（不会让两个实例共用一个运行目录）
+--dry-run：只检查并打印将要用的隔离档/运行目录，不写任何文件、不建目录。
+ --json 输出 {\"data\":{\"dry_run\":…,\"instance\":{\"id\",\"name\",\"isolation\",\"run_dir\",
+ \"run_dir_source\",\"config_path\",\"created\"},\"notes\":[…]}}。
+",
         ),
         "pack" => Some(
             "\

crates/cli/src/cli/model.rs

@@ -2,6 +2,8 @@
 
 use std::path::PathBuf;
 
+use unlucky_core::game::AdoptTarget;
+
 /// 全局选项（所有命令共享）。
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct Globals {
@@ -26,6 +28,10 @@ pub enum Command {
     Help(Option<String>),
     /// `instances list`。
     InstancesList,
+    /// `instances scan`：列出当前游戏根里可登记 / 不可登记的外部版本（只读，M221）。
+    InstancesScan,
+    /// `instances adopt <version-id> [--name N] [--isolation ...] [--game-dir DIR] [--dry-run]`。
+    InstancesAdopt(InstancesAdoptArgs),
     /// `instances launch-args <instance> [--jvm …] [--game …] [--memory …] [--java …] [--backend …] [--clear]`。
     InstancesLaunchArgs(InstanceLaunchArgs),
     /// `install <version> [--loader X] [--name N]`。
@@ -203,6 +209,20 @@ pub struct DiagArgs {
     pub tail: usize,
 }
 
+/// `instances adopt` 的参数（M221：把盘上已有的版本登记成实例，只读外部、只写自己的配置）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InstancesAdoptArgs {
+    /// 要接入的版本 id（= `versions/<id>/`）。
+    pub version_id: String,
+    /// 展示名（缺省 = 版本 id）。
+    pub name: Option<String>,
+    /// 运行目录选择：缺省 [`AdoptTarget::InstanceDir`]（ULL 数据区新目录），
+    /// `shared` / `isolated` / `custom` 都必须显式给。
+    pub target: AdoptTarget,
+    /// 只检查、不写任何文件（`--dry-run`）。
+    pub dry_run: bool,
+}
+
 /// `instances launch-args` 的参数（M157：实例级启动参数）。
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct InstanceLaunchArgs {

crates/cli/src/cli/parse/instances.rs

@@ -1,9 +1,13 @@
-//! `instances` 的两个子命令解析（`list` / `launch-args`）。
+//! `instances` 的子命令解析（`list` / `launch-args` / `scan` / `adopt`）。
 //!
 //! 从 `parse.rs` 拆出来只为守 400 行硬线（M157 的 `launch-args` 让那边到 415 行）；
-//! 纯搬移，语义未变。
+//! 纯搬移，语义未变。M221 在这里加了 `scan` 与 `adopt` 两个只读/登记入口。
 
-use super::super::model::InstanceLaunchArgs;
+use std::path::PathBuf;
+
+use unlucky_core::game::AdoptTarget;
+
+use super::super::model::{InstanceLaunchArgs, InstancesAdoptArgs};
 use super::*;
 
 pub(super) fn parse_instances(tail: &[String]) -> Result<Command, CliError> {
@@ -12,10 +16,16 @@ pub(super) fn parse_instances(tail: &[String]) -> Result<Command, CliError> {
         Some("launch-args") => {
             return parse_instances_launch_args(tail.get(1..).unwrap_or_default())
         }
+        Some("scan") => {
+            let parsed = parse_flags(tail.get(1..).unwrap_or_default(), &[], &[])?;
+            ensure_no_positionals(&parsed, "instances scan")?;
+            return Ok(Command::InstancesScan);
+        }
+        Some("adopt") => return parse_instances_adopt(tail.get(1..).unwrap_or_default()),
         Some(other) => {
             return Err(CliError::usage(format!(
-                "instances 的子命令只有 list / launch-args，收到 `{other}`"
+                "instances 的子命令只有 list / launch-args / scan / adopt，收到 `{other}`"
-            )));
+            )))
         }
     };
     let parsed = parse_flags(args, &[], &[])?;
@@ -43,3 +53,62 @@ fn parse_instances_launch_args(tail: &[String]) -> Result<Command, CliError> {
         clear: parsed.has("clear"),
     }))
 }
+
+/// `instances adopt <version-id> [--name N] [--isolation shared|isolated|custom] [--game-dir DIR] [--dry-run]`。
+///
+/// 运行目录的词表只在这里翻译一次（[`AdoptTarget::parse`] 是唯一判据）：
+/// - 什么都不给 ⇒ [`AdoptTarget::InstanceDir`]（ULL 数据区新目录，**不沿用全局 `isolated`**）；
+/// - `--isolation custom` 必须配 `--game-dir`；
+/// - `--isolation shared|isolated` 不许再配 `--game-dir`（那两个档的运行目录是派生的）。
+fn parse_instances_adopt(tail: &[String]) -> Result<Command, CliError> {
+    let parsed = parse_flags(tail, &["name", "isolation", "game-dir"], &["dry-run"])?;
+    let version_id = require_single_positional(&parsed, "instances adopt <version-id>")?;
+    let isolation = parsed.value("isolation");
+    let game_dir = match parsed.value("game-dir") {
+        Some(raw) => {
+            let dir = PathBuf::from(&raw);
+            // 用法错误在解析期就报（和 `--data-dir` 同一口径），别把「参数写错」拖成命令期失败。
+            if !dir.is_absolute() {
+                return Err(CliError::usage(format!(
+                    "--game-dir 需要绝对路径，收到 `{raw}`"
+                )));
+            }
+            Some(dir)
+        }
+        None => None,
+    };
+    let target = match isolation.as_deref() {
+        None => match game_dir {
+            // `--game-dir` 单独给 = 就是 custom（少写一个选项，不制造第二种说法）。
+            Some(dir) => AdoptTarget::Custom(dir),
+            // 缺省**只能**来自 core 的 `AdoptTarget::default()`：这里再写一遍 `InstanceDir`
+            // 就等于有了第二处真相源，改缺省时会漏一处。
+            None => AdoptTarget::default(),
+        },
+        Some("custom") => {
+            let dir = game_dir.ok_or_else(|| {
+                CliError::usage("--isolation custom 需要配 --game-dir <dir>（绝对路径）")
+            })?;
+            AdoptTarget::Custom(dir)
+        }
+        Some(other) => {
+            if game_dir.is_some() {
+                return Err(CliError::usage(
+                    "--game-dir 只配 --isolation custom（shared / isolated 的运行目录是派生的）",
+                ));
+            }
+            AdoptTarget::parse(other, None).ok_or_else(|| {
+                CliError::usage(format!(
+                    "--isolation 只有 shared|isolated|custom，收到 `{other}`"
+                ))
+                .with_hint("不给 --isolation = 落 ULL 数据区的独立运行目录（推荐）")
+            })?
+        }
+    };
+    Ok(Command::InstancesAdopt(InstancesAdoptArgs {
+        version_id,
+        name: parsed.value("name"),
+        target,
+        dry_run: parsed.has("dry-run"),
+    }))
+}

crates/cli/src/commands/instances.rs

@@ -144,6 +144,10 @@ fn loader_json(version_id: &str) -> Value {
     })
 }
 
+pub mod adopt;
+mod adopt_shared;
+pub mod scan;
+
 #[cfg(test)]
 mod tests;
 

crates/cli/src/commands/instances/adopt.rs

@@ -0,0 +1,118 @@
+//! `ull instances adopt`：把盘上已有的版本登记成实例（M221）。
+//!
+//! **只读外部、只写自己**：写盘面只有 `<数据根>/.ULL/config/` 下的两份配置（+ 选中缺省运行目录时
+//! 建那个空目录），`versions/` `libraries/` `assets/` 一个字节都不写。判据、落点与话术全在
+//! [`unlucky_core::game::adopt`]；本模块只做「参数 → core 调用 → 人读/JSON 两条输出」。
+//!
+//! `--dry-run` 走 `adopt::plan`（零写盘），所以「先看一眼」不会改任何东西，也不会建目录。
+
+use serde_json::{json, Value};
+use unlucky_core::game::adopt::{self, AdoptRequest};
+use unlucky_core::game::GameLayout;
+use unlucky_core::launch::time::{format_rfc3339_millis, now};
+use unlucky_core::platform::layout::LauncherLayout;
+
+use crate::cli::model::InstancesAdoptArgs;
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::Report;
+
+use super::adopt_shared::{candidate_json, map_error};
+
+/// `ull instances adopt <version-id> [--name N] [--isolation …] [--game-dir DIR] [--dry-run]`。
+///
+/// # Errors
+///
+/// 版本不在盘上 / 候选不合格 / 名字冲突 / 运行目录不可用 / 读配置失败，全部由
+/// [`unlucky_core::game::adopt::AdoptError`] 映射成稳定错误码（`adopt_*`）。
+pub fn run(ctx: &Ctx, args: &InstancesAdoptArgs) -> Result<Report, CliError> {
+    let request = AdoptRequest {
+        version_id: args.version_id.clone(),
+        name: args.name.clone(),
+        target: args.target.clone(),
+        created_at: Some(format_rfc3339_millis(now())),
+    };
+    let (game, launcher) = (ctx.game(), ctx.layout());
+    if args.dry_run {
+        return dry_run(&game, &launcher, &request);
+    }
+    let outcome = adopt::adopt(&game, &launcher, &request).map_err(map_error)?;
+    // 人读行先拼（只借用），再把字段移进 JSON（两条出口的内容同源、顺序不影响事实）。
+    let mut human = vec![format!(
+        "已登记实例 `{}`（id {}）→ 版本 {}",
+        outcome.name, outcome.instance_id, outcome.version_id
+    )];
+    human.push(format!(
+        "  隔离档 {}（运行目录来源 {}），运行目录 {}",
+        outcome.isolation.as_str(),
+        outcome.target.as_str(),
+        outcome.run_dir.display()
+    ));
+    human.push(format!("  实例设置 {}", outcome.config_path.display()));
+    if outcome.dir_created {
+        human.push("  已新建该运行目录（空目录；玩家数据由游戏自己往里写）".to_string());
+    }
+    human.push(
+        "  只写了本启动器的配置：versions/ libraries/ assets/ 一个字节都没动（不搬文件）"
+            .to_string(),
+    );
+    human.extend(outcome.notes.iter().map(|note| format!("  提示：{note}")));
+    let version_id = outcome.version_id.clone();
+    let data = json!({
+        "dry_run": false,
+        "version_id": version_id,
+        "instance": json!({
+            "id": outcome.instance_id,
+            "name": outcome.name,
+            "version_id": version_id,
+            "isolation": outcome.isolation.as_str(),
+            "run_dir": outcome.run_dir.display().to_string(),
+            "run_dir_source": outcome.target.as_str(),
+            "config_path": outcome.config_path.display().to_string(),
+            "created": outcome.created,
+            "dir_created": outcome.dir_created,
+        }),
+        "notes": outcome.notes,
+    });
+    Ok(Report::new(data, human))
+}
+
+/// `--dry-run`：只算落点与判据，不写盘（连缺省运行目录都不建）。
+fn dry_run(
+    game: &GameLayout,
+    launcher: &LauncherLayout,
+    request: &AdoptRequest,
+) -> Result<Report, CliError> {
+    let plan = adopt::plan(game, launcher, request).map_err(map_error)?;
+    let mut human = vec![format!(
+        "检查通过：版本 {} 可登记（--dry-run：没有写任何文件）",
+        plan.candidate.version_id
+    )];
+    human.push(format!(
+        "  实例名 {}，隔离档 {}（运行目录来源 {}）",
+        plan.name,
+        plan.isolation.as_str(),
+        plan.target.as_str()
+    ));
+    human.push(format!("  运行目录 {}", plan.run_dir.display()));
+    human.extend(plan.notes.iter().map(|note| format!("  提示：{note}")));
+    let version_id = plan.candidate.version_id.clone();
+    let data = json!({
+        "dry_run": true,
+        "version_id": version_id,
+        "candidate": candidate_json(&plan.candidate),
+        "instance": json!({
+            "id": Value::Null,
+            "name": plan.name,
+            "version_id": version_id,
+            "isolation": plan.isolation.as_str(),
+            "run_dir": plan.run_dir.display().to_string(),
+            "run_dir_source": plan.target.as_str(),
+            "config_path": Value::Null,
+            "created": false,
+            "dir_created": false,
+        }),
+        "notes": plan.notes,
+    });
+    Ok(Report::new(data, human))
+}

crates/cli/src/commands/instances/adopt_shared.rs

@@ -0,0 +1,84 @@
+//! `instances scan` / `instances adopt` 共用的 JSON 与错误投影。
+//!
+//! 两条命令输出同一种候选形状（`candidate` 对象），错误也走同一份映射——分两份写迟早漂。
+
+use serde_json::{json, Value};
+use unlucky_core::game::adopt::{AdoptCandidate, AdoptError, AdoptProblem};
+
+use crate::error::CliError;
+
+/// 候选 → `--json` 里的 `candidate` 对象。
+pub(super) fn candidate_json(candidate: &AdoptCandidate) -> Value {
+    json!({
+        "version_id": candidate.version_id,
+        "version_dir": candidate.version_dir.display().to_string(),
+        "manifest_path": candidate.manifest_path.display().to_string(),
+        "jar_present": candidate.jar_present,
+        "manifest_id": candidate.manifest_id,
+        "inherits": candidate.inherits,
+        "registered": candidate.registered.iter().map(|item| json!({
+            "id": item.id,
+            "name": item.name,
+        })).collect::<Vec<Value>>(),
+        "adoptable": candidate.adoptable(),
+        "problems": problems_json(&candidate.problems),
+    })
+}
+
+/// 问题清单 → 结构化数组（`code` 稳定、`message` 人读）。
+pub(super) fn problems_json(problems: &[AdoptProblem]) -> Value {
+    Value::Array(
+        problems
+            .iter()
+            .map(|problem| {
+                json!({
+                    "code": problem.code(),
+                    "message": problem.to_string(),
+                })
+            })
+            .collect(),
+    )
+}
+
+/// `AdoptError` → CLI 错误：稳定 code + 逐条问题进 `detail`（脚本不必解析散文）。
+pub(super) fn map_error(error: AdoptError) -> CliError {
+    let code = error.code();
+    let message = error.to_string();
+    let cli = CliError::user(code, message);
+    let hint = match &error {
+        AdoptError::DuplicateName { .. } => {
+            Some("换个展示名：%prog% instances adopt <version-id> --name <新名字>")
+        }
+        AdoptError::NotAdoptable { .. } => Some(
+            "这些版本要么清单坏了、要么缺父版本、要么越界：先在原来的启动器里把它修好，\
+             或 `%prog% install <version>` 让本启动器自己装一份",
+        ),
+        AdoptError::AlreadyRegistered { .. } => {
+            Some("用 `%prog% instances list` 看已有实例；要第二个实例请换 --name")
+        }
+        AdoptError::TargetNotEmpty { .. } => {
+            Some("换一个名字（缺省目录按名字派生），或用 --isolation custom --game-dir <空目录>")
+        }
+        AdoptError::UnknownVersion { .. } => Some("先看有哪些可用：%prog% instances scan"),
+        AdoptError::NoFreeRunDir { .. } => Some(
+            "换一个 --name（缺省目录按名字派生），或用 --isolation custom --game-dir <空目录>",
+        ),
+        AdoptError::WriteSurfaceInGameTree { .. } => Some(
+            "数据目录（.ULL / --data-dir）和游戏树重叠了：把它指到游戏树之外的目录再登记             （整体迁移到别处是允许的，默认登记不会把实例数据写进别人的 .minecraft）",
+        ),
+        AdoptError::ConfigSurfaceUnsafe { .. } => Some(
+            "数据根里的 config/ 或 config/instances/ 被链到别处了：先把它恢复成真实目录再登记             （整体迁移请把整个 .ULL 目录一起搬走，别只链其中一层）",
+        ),
+        AdoptError::VersionsDirUnreadable { .. } => Some(
+            "游戏根/versions 入口存在但读不出来：检查它是不是断链的符号链接/目录联接，             或把它指回真实目录后再扫",
+        ),
+        _ => None,
+    };
+    let cli = match hint {
+        Some(hint) => cli.with_hint(hint),
+        None => cli,
+    };
+    cli.with_detail(json!({
+        "problems": problems_json(error.problems()),
+    }))
+}

crates/cli/src/commands/instances/scan.rs

@@ -0,0 +1,91 @@
+//! `ull instances scan`：列出当前游戏根 `versions/` 里**已经铺好**的版本，逐项说清能不能登记（M221）。
+//!
+//! 只读：不写任何文件、不改任何 mtime。用途是「我盘上已经有别的启动器装好的版本，看看 ULL 认不认」，
+//! 以及 `instances adopt` 的前置检查（同一套判据，见 [`unlucky_core::game::adopt::scan`]）。
+
+use serde_json::json;
+use unlucky_core::game::adopt;
+
+use crate::context::Ctx;
+use crate::error::CliError;
+use crate::output::Report;
+
+use super::adopt_shared::candidate_json;
+
+/// `ull instances scan`。
+///
+/// # Errors
+///
+/// `versions/` 或 `profiles.json` 读不了时返回用户错误（**不降级成空列表**）。
+pub fn run(ctx: &Ctx) -> Result<Report, CliError> {
+    let scan = adopt::scan(&ctx.game(), &ctx.layout()).map_err(super::adopt_shared::map_error)?;
+    let ready = scan
+        .candidates
+        .iter()
+        .filter(|candidate| candidate.adoptable())
+        .count();
+    let registered = scan
+        .candidates
+        .iter()
+        .filter(|candidate| candidate.is_registered())
+        .count();
+
+    let candidates: Vec<serde_json::Value> = scan.candidates.iter().map(candidate_json).collect();
+    let data = json!({
+        "game_root": ctx.data.game_home.display().to_string(),
+        "versions_dir": scan.versions_dir.display().to_string(),
+        "counts": {
+            "total": scan.candidates.len(),
+            "adoptable": ready,
+            "registered": registered,
+        },
+        "candidates": candidates,
+    });
+
+    let mut human = vec![format!(
+        "游戏根 {}：versions/ 里 {} 个版本，{} 个可登记",
+        scan.versions_dir.display(),
+        scan.candidates.len(),
+        ready
+    )];
+    if scan.candidates.is_empty() {
+        human.push(
+            "  （空）这个游戏根下还没有任何版本；`%prog% install <version>` 可以自己装一份"
+                .to_string(),
+        );
+    }
+    for candidate in &scan.candidates {
+        if candidate.adoptable() {
+            let state = if candidate.is_registered() {
+                "已登记"
+            } else {
+                "可登记"
+            };
+            human.push(format!(
+                "  ✓ {}  [{state}]{}",
+                candidate.version_id,
+                chain_suffix(candidate)
+            ));
+        } else {
+            human.push(format!("  ✗ {}", candidate.version_id));
+            for problem in &candidate.problems {
+                human.push(format!("      原因[{0}] {problem}", problem.code()));
+            }
+        }
+    }
+    if ready > 0 {
+        human.push(
+            "登记一个：%prog% instances adopt <version-id>（缺省落 ULL 数据区的独立运行目录）"
+                .to_string(),
+        );
+    }
+    Ok(Report::new(data, human))
+}
+
+/// 人读行尾的父链提示（`1.12.2-forge-…` 后面标出它继承的是谁）。
+fn chain_suffix(candidate: &unlucky_core::game::AdoptCandidate) -> String {
+    match candidate.inherits.len() {
+        0 | 1 => String::new(),
+        _ => format!("  继承 {}", candidate.inherits[1..].join(" -> ")),
+    }
+}

crates/cli/src/commands/mod.rs

@@ -37,6 +37,10 @@ pub fn run(invocation: &Invocation) -> Result<Outcome, CliError> {
         Command::InstancesLaunchArgs(args) => {
             with_ctx(&invocation.globals, |ctx| instance_launch::run(ctx, args))
         }
+        Command::InstancesScan => with_ctx(&invocation.globals, instances::scan::run),
+        Command::InstancesAdopt(args) => {
+            with_ctx(&invocation.globals, |ctx| instances::adopt::run(ctx, args))
+        }
         Command::Install(args) => with_ctx(&invocation.globals, |ctx| install::run(ctx, args)),
         Command::PackImport(args) => {
             with_ctx_outcome(&invocation.globals, |ctx| pack::run(ctx, args))

crates/cli/tests/adopt_test.rs

@@ -0,0 +1,332 @@
+//! M221 CLI 端到端：`ull instances scan` / `ull instances adopt` 的真实入口（解析 → 执行 → 两条输出）。
+//!
+//! 用的都是**真磁盘**数据根（`support::TempDir`）+ 一份「别的启动器铺好的」`.minecraft`。
+//! 每条用例都断言外部文件哈希/mtime 不变（`fixture::assert_unchanged`），
+//! 因为「只登记不搬文件」是本 mission 的核心承诺。
+
+#[path = "adopt_test/cli_surface.rs"]
+mod cli_surface;
+#[path = "adopt_test/collision_cases.rs"]
+mod collision_cases;
+#[path = "adopt_test/fixture.rs"]
+mod fixture;
+#[path = "support/mod.rs"]
+mod support;
+
+use std::path::Path;
+
+use support::{parse_json, run_cli, TempDir};
+
+use crate::fixture::{assert_unchanged, foreign_data_root, snapshot, snapshot_opt, Node};
+
+/// 缺省登记：落 ULL 数据区的独立目录，隔离档 `custom`，**不沿用全局 `isolated`**。
+///
+/// 抓得住：
+/// - 缺省沿用全局 `isolated`（运行目录会变成 `versions/1.20.1`，第二条断言会红）——
+///   这是本 mission 点名的最容易漏的一条；
+/// - 命令只登记不输出（`--json` 缺 `instance`）；
+/// - 登记过程写了外部 `.minecraft`（哈希断言）。
+///
+/// 抓不住：GUI 是否也能触发同一条路（GUI 接线是后续 mission）。
+#[test]
+fn adopt_without_isolation_uses_a_separate_run_dir_and_keeps_global_isolated_out_of_it() {
+    let dir = TempDir::new("adopt-default");
+    let root = dir.path();
+    foreign_data_root(root);
+    // 全局档显式写成 isolated（D20 的缺省）：登记**不许**继承它去踩别人的版本目录。
+    set_global_isolated(&dir);
+    let minecraft = root.join(".minecraft");
+    let before = snapshot(&minecraft);
+
+    let (code, stdout, stderr) = run_cli(&[
+        "instances",
+        "adopt",
+        "1.20.1",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0, "stdout={stdout}\nstderr={stderr}");
+    let after = snapshot(&minecraft);
+    assert_unchanged(&before, &after, "adopt 之后");
+
+    let value = parse_json(&stdout);
+    let instance = &value["data"]["instance"];
+    assert_eq!(instance["isolation"], "custom");
+    assert_eq!(instance["run_dir_source"], "instance_dir");
+    let run_dir = instance["run_dir"].as_str().expect("run_dir");
+    assert!(
+        run_dir.contains("instances"),
+        "缺省运行目录应落 ULL 数据区：{run_dir}"
+    );
+    assert!(
+        !Path::new(run_dir).starts_with(&minecraft),
+        "缺省运行目录不许落进别人的 .minecraft：{run_dir}"
+    );
+    assert!(
+        !run_dir.ends_with("versions/1.20.1") && !run_dir.ends_with("versions\\1.20.1"),
+        "不许沿用全局 isolated 的 versions/<id>：{run_dir}"
+    );
+    assert_eq!(instance["created"], true);
+
+    // 再走一次 `instances list`：档案真的进去了（不是只写了实例文件）。
+    let (code, stdout, _) = run_cli(&["instances", "list", "--json", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 0);
+    let listed = parse_json(&stdout);
+    assert_eq!(listed["data"]["instances"][0]["version_id"], "1.20.1");
+    assert_eq!(listed["data"]["instances"][0]["version_present"], true);
+}
+
+/// 登记之后 `launch --dry-run` 的 `--gameDir` 就是选定的运行目录（本 mission 的功能落点）。
+///
+/// 抓得住：登记把隔离档写错（`inherit`）⇒ 启动派生坚持全局 `isolated`，`game_dir` 变成
+/// `versions/1.20.1`（第二条断言会红）；`gameDir` 没进启动计划。
+/// 抓不住：真进程是否真的用这个 CWD（要真跑游戏，本 mission 不跑）。
+#[test]
+fn the_launch_plan_points_game_dir_at_the_chosen_run_dir() {
+    let dir = TempDir::new("adopt-launch");
+    let root = dir.path();
+    foreign_data_root(root);
+    set_global_isolated(&dir);
+
+    let (code, stdout, stderr) = run_cli(&[
+        "instances",
+        "adopt",
+        "1.20.1",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0, "stdout={stdout}\nstderr={stderr}");
+    let adopted = parse_json(&stdout);
+    let run_dir = adopted["data"]["instance"]["run_dir"]
+        .as_str()
+        .expect("run_dir")
+        .to_string();
+    let instance_id = adopted["data"]["instance"]["id"]
+        .as_str()
+        .expect("instance id")
+        .to_string();
+
+    let dir_arg = dir.arg();
+    let args = [
+        "launch",
+        instance_id.as_str(),
+        "--dry-run",
+        "--json",
+        "--data-dir",
+        dir_arg.as_str(),
+    ];
+    let (code, stdout, stderr) = run_cli(&args);
+    assert_eq!(code, 0, "stdout={stdout}\nstderr={stderr}");
+    let plan = parse_json(&stdout);
+    assert_eq!(plan["data"]["game_dir"], run_dir.as_str());
+    assert_eq!(plan["data"]["isolation"], "custom");
+    assert_eq!(plan["data"]["isolation_source"], "instance");
+    let command = plan["data"]["argv"]
+        .as_array()
+        .expect("启动计划里应有 argv");
+    let game_dir_flag = command
+        .windows(2)
+        .find(|pair| pair[0].as_str() == Some("--gameDir"))
+        .map(|pair| pair[1].as_str().unwrap_or_default().to_string())
+        .expect("命令行里应有 --gameDir");
+    // `argv` 是**脱敏后**的（主目录 → `<home>`，见 `core::launch::redact`），所以比尾段而不是全等；
+    // 全等的那条断言在 `data.game_dir` 上（那是未脱敏的权威值）。
+    let tail = format!(
+        "instances/{}",
+        Path::new(&run_dir)
+            .file_name()
+            .expect("运行目录名")
+            .to_string_lossy()
+    );
+    assert!(
+        game_dir_flag.ends_with(&tail) || game_dir_flag.ends_with(&tail.replace('/', "\\")),
+        "--gameDir 必须指向选定的运行目录：{game_dir_flag} 应以 {tail} 结尾"
+    );
+}
+
+/// `--isolation shared`：明确选共享 ⇒ 运行目录 = 别人的游戏根，**人读输出必须说出后果**。
+///
+/// 抓得住：shared 档没有告知（stdout 里没有「共用」）、shared 被写成 custom + 自己的目录、
+/// 登记往游戏根写文件（哈希断言）。
+/// 抓不住：用户是否真的看见这句（UI 验收另说）。
+#[test]
+fn shared_isolation_states_the_consequence_in_human_output() {
+    let dir = TempDir::new("adopt-shared");
+    let root = dir.path();
+    foreign_data_root(root);
+    let minecraft = root.join(".minecraft");
+    let before = snapshot(&minecraft);
+
+    let (code, stdout, stderr) = run_cli(&[
+        "instances",
+        "adopt",
+        "1.20.1",
+        "--isolation",
+        "shared",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0, "stdout={stdout}\nstderr={stderr}");
+    let after = snapshot(&minecraft);
+    assert_unchanged(&before, &after, "shared 登记之后");
+    assert!(
+        stdout.contains("共用"),
+        "必须说出「共用别人的 .minecraft」：{stdout}"
+    );
+    assert!(stdout.contains("一个字节都没动"), "{stdout}");
+}
+
+/// `--dry-run`：只检查不写盘（连配置目录都不建）。
+///
+/// 抓得住：`--dry-run` 真的写了档案或建了运行目录（快照会红）。
+/// 抓不住：`--dry-run` 有没有顺带读了不该读的东西。
+#[test]
+fn dry_run_writes_nothing() {
+    let dir = TempDir::new("adopt-dry");
+    let root = dir.path();
+    foreign_data_root(root);
+    let before = snapshot(root);
+    // 判据强度自检（R5）：快照必须含**目录**节点，否则「凭空建个空目录」看不出来。
+    assert!(
+        matches!(before.get(".minecraft"), Some(Node::Dir { .. })),
+        "快照缺少目录节点：{:?}",
+        before.get(".minecraft")
+    );
+    assert!(
+        before.contains_key(".minecraft/versions"),
+        "快照缺少 versions 目录节点"
+    );
+
+    let (code, stdout, stderr) = run_cli(&[
+        "instances",
+        "adopt",
+        "1.20.1",
+        "--dry-run",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 0, "stdout={stdout}\nstderr={stderr}");
+    let after = snapshot(root);
+    assert_unchanged(&before, &after, "--dry-run 之后");
+    // `--dry-run` 连 `.ULL` 这个**空目录**都不许建（存在性判据用 `snapshot_opt`）。
+    assert!(
+        snapshot_opt(&root.join(".ULL")).is_none(),
+        "--dry-run 不该建配置目录"
+    );
+    assert!(stdout.contains("检查通过"), "{stdout}");
+    assert!(stdout.contains("没有写任何文件"), "{stdout}");
+}
+
+/// 坏的版本（缺父）⇒ 退出码 1，`--json` 里带**逐条**问题码。
+///
+/// 抓得住：不合格版本被登记成功（退出码变 0）、问题码被折叠成一句散文（`detail.problems` 缺项）。
+/// 抓不住：用户在原来的启动器里修好之后重试（自然覆盖）。
+#[test]
+fn not_adoptable_version_exits_one_with_structured_problems() {
+    let dir = TempDir::new("adopt-refuse");
+    let root = dir.path();
+    foreign_data_root(root);
+    let before = snapshot(root);
+
+    let (code, stdout, _) = run_cli(&[
+        "instances",
+        "adopt",
+        "1.20.1-orphan",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 1, "{stdout}");
+    let value = parse_json(&stdout);
+    assert_eq!(value["ok"], false);
+    assert_eq!(value["error"]["code"], "adopt_not_adoptable");
+    assert_eq!(
+        value["error"]["detail"]["problems"][0]["code"],
+        "missing_parent"
+    );
+    let after = snapshot(root);
+    assert_unchanged(&before, &after, "失败之后");
+}
+
+/// 重复登记 ⇒ 退出码 1 + 无副作用（档案逐字节不变）。
+///
+/// 抓得住：重复登记当成功（退出码 0）或失败时改了档案。
+/// 抓不住：并发两次登记（没有锁；这不是并发入口）。
+#[test]
+fn repeating_the_same_adopt_exits_one_without_side_effects() {
+    let dir = TempDir::new("adopt-repeat");
+    let root = dir.path();
+    foreign_data_root(root);
+    let (code, _, stderr) = run_cli(&["instances", "adopt", "1.20.1", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 0, "{stderr}");
+    let config = root.join(".ULL/config");
+    let before = snapshot(&config);
+
+    let (code, stdout, _) = run_cli(&[
+        "instances",
+        "adopt",
+        "1.20.1",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 1, "{stdout}");
+    assert_eq!(
+        parse_json(&stdout)["error"]["code"],
+        "adopt_already_registered"
+    );
+    let after = snapshot(&config);
+    assert_unchanged(&before, &after, "重复登记失败之后");
+}
+
+/// `instances scan`：只读列出候选，坏版本逐条给原因。
+///
+/// 抓得住：扫描变成空列表（那是本 mission 点名不许的行为）、坏版本被静默跳过、
+/// 扫描写了文件。
+/// 抓不住：真实 `.minecraft` 里那些平台特有的怪目录（夹具只覆盖已知形状）。
+#[test]
+fn scan_lists_candidates_and_reasons_without_writing() {
+    let dir = TempDir::new("adopt-scan");
+    let root = dir.path();
+    foreign_data_root(root);
+    let before = snapshot(root);
+
+    let (code, stdout, stderr) =
+        run_cli(&["instances", "scan", "--json", "--data-dir", &dir.arg()]);
+    assert_eq!(code, 0, "stdout={stdout}\nstderr={stderr}");
+    let after = snapshot(root);
+    assert_unchanged(&before, &after, "scan 之后");
+
+    let value = parse_json(&stdout);
+    assert_eq!(value["data"]["counts"]["total"], 2);
+    assert_eq!(value["data"]["counts"]["adoptable"], 1);
+    let candidates = value["data"]["candidates"].as_array().expect("candidates");
+    let ok = candidates
+        .iter()
+        .find(|item| item["version_id"] == "1.20.1")
+        .expect("有 1.20.1");
+    assert_eq!(ok["adoptable"], true);
+    assert_eq!(ok["jar_present"], true);
+    let orphan = candidates
+        .iter()
+        .find(|item| item["version_id"] == "1.20.1-orphan")
+        .expect("有 1.20.1-orphan");
+    assert_eq!(orphan["adoptable"], false);
+    assert_eq!(orphan["problems"][0]["code"], "missing_parent");
+}
+
+/// 把全局隔离档设成 `isolated`（走 schema 校验的正式入口，不手写 launcher.json）。
+fn set_global_isolated(dir: &TempDir) {
+    let dir_arg = dir.arg();
+    let (code, _, stderr) = run_cli(&[
+        "config",
+        "set",
+        "instances.mode",
+        "isolated",
+        "--data-dir",
+        dir_arg.as_str(),
+    ]);
+    assert_eq!(code, 0, "设置全局隔离档失败：{stderr}");
+}

crates/cli/tests/adopt_test/cli_surface.rs

@@ -0,0 +1,156 @@
+//! 命令面：help 文案、用法错误、错误码——不碰数据或者只碰「拒绝」那条路。
+//!
+//! 从 `tests/adopt_test.rs` 拆出来只为守 400 行硬线；搬动是纯搬，断言未变。
+
+use crate::support::{parse_json, run_cli, TempDir};
+
+use crate::fixture::foreign_data_root;
+
+/// 运行目录选项的用法错误：一律退出码 1 + `code=usage`（不是内部错误）。
+///
+/// 抓得住：`--isolation custom` 少 `--game-dir` 被默默当成缺省、`shared` 同时给 `--game-dir`
+/// 被静默忽略、未知词被当缺省。
+/// 抓不住：提示文案的措辞（只断言 code 与关键字）。
+#[test]
+fn isolation_option_misuse_is_a_usage_error() {
+    let dir = TempDir::new("adopt-usage");
+    foreign_data_root(dir.path());
+    let cases: Vec<Vec<&str>> = vec![
+        vec!["--isolation", "custom"],
+        vec!["--isolation", "shared", "--game-dir", "C:/tmp/x"],
+        vec!["--isolation", "nope"],
+        vec!["--game-dir", "relative/dir"],
+    ];
+    for extra in cases {
+        let mut args = vec!["instances", "adopt", "1.20.1", "--json", "--data-dir"];
+        let dir_arg = dir.arg();
+        args.push(&dir_arg);
+        args.extend(extra.iter().copied());
+        let (code, stdout, stderr) = run_cli(&args);
+        assert_eq!(code, 1, "args={args:?}\nstdout={stdout}\nstderr={stderr}");
+        let value = parse_json(&stdout);
+        assert_eq!(
+            value["error"]["code"], "usage",
+            "args={args:?} 应是用法错误：{stdout}"
+        );
+    }
+}
+
+/// 不存在的版本 ⇒ `adopt_version_not_found`（不联网、不偷偷装一个）。
+///
+/// 抓得住：不存在的 id 被登记成功。
+/// 抓不住：`versions/` 整个不存在时 `scan` 的空结果（core 侧用例覆盖）。
+#[test]
+fn unknown_version_reports_not_found() {
+    let dir = TempDir::new("adopt-unknown");
+    foreign_data_root(dir.path());
+    let (code, stdout, _) = run_cli(&[
+        "instances",
+        "adopt",
+        "9.9.9",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 1, "{stdout}");
+    assert_eq!(
+        parse_json(&stdout)["error"]["code"],
+        "adopt_version_not_found"
+    );
+}
+
+/// help 里必须有这两条命令（新命令不留「有实现没文档」的状态），且旧命令仍在。
+///
+/// 抓得住：help 漏列 `instances scan` / `instances adopt`（子串断言），或把旧的
+/// `instances launch-args` / `pack import` 弄丢。
+/// 抓不住：帮助文案与真实行为是否一致（那要靠上面的行为用例 + 人读）。
+#[test]
+fn help_lists_the_new_subcommands_next_to_the_old_ones() {
+    let general = unlucky_cli::cli::help::general();
+    for needle in [
+        "instances scan",
+        "instances adopt",
+        "instances list",
+        "install <version>",
+    ] {
+        assert!(general.contains(needle), "总帮助缺 `{needle}`：\n{general}");
+    }
+    let topic = unlucky_cli::cli::help::topic("instances").expect("help instances 存在");
+    for needle in [
+        "instances scan",
+        "instances adopt",
+        "缺省不沿用全局 isolated",
+        "一个字节都不写",
+    ] {
+        assert!(topic.contains(needle), "help instances 缺 `{needle}`");
+    }
+    // 旧的 `per_version` 字面量只在 core 的 `Isolation::parse` 里被兼容，CLI 词表不接受它。
+    let bogus = std::env::temp_dir().join("ull-adopt-help-nonexistent");
+    let bogus = bogus.display().to_string();
+    let args = [
+        "instances",
+        "adopt",
+        "1.20.1",
+        "--isolation",
+        "per_version",
+        "--json",
+        "--data-dir",
+        bogus.as_str(),
+    ];
+    let (code, stdout, _) = run_cli(&args);
+    assert_eq!(code, 1, "`per_version` 不是 CLI 词表：{stdout}");
+}
+
+/// **更高祖先断链**（r2 R2.3 的 CLI 面）：`--data-dir` 指到迁移联接下面的 nested 目录，
+/// 联接目标被搬走后 `instances scan` 必须非零 + 结构化错误，不能 `ok:true / total:0`。
+///
+/// 抓得住：只判 `versions`/游戏根两层（更高层断链会漏，这里会看到 exit0 与 total 0）。
+///
+/// 抓不住：真正的权限不足（EACCES）那一支。
+#[cfg(windows)]
+#[test]
+fn a_dangling_ancestor_is_a_structured_scan_error() {
+    let dir = TempDir::new("scan-ancestor-dangling");
+    let outer = TempDir::new("scan-ancestor-target");
+    let real = outer.path();
+    let game = real.join("nested").join(".minecraft");
+    std::fs::create_dir_all(game.join("versions").join("1.20.1")).expect("建完整版本树");
+    std::fs::write(
+        game.join("versions/1.20.1/1.20.1.json"),
+        br#"{"id":"1.20.1","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写清单");
+    let link = dir.path().join("game-parent-link");
+    let ok = std::process::Command::new("cmd")
+        .args(["/c", "mklink", "/J"])
+        .arg(&link)
+        .arg(real)
+        .output()
+        .is_ok_and(|out| out.status.success());
+    if !ok {
+        eprintln!("[link-guard] 建不出目录联接，跳过祖先断链 CLI 用例");
+        return;
+    }
+    let data_arg = link.join("nested").display().to_string();
+
+    // 断开之前：能扫到 1 个候选。
+    let (code, stdout, stderr) = run_cli(&["instances", "scan", "--json", "--data-dir", &data_arg]);
+    assert_eq!(code, 0, "stdout={stdout} stderr={stderr}");
+    assert_eq!(parse_json(&stdout)["data"]["counts"]["total"], 1);
+
+    // 断开：联接目标改名（入口还在，versions 与游戏根都 NotFound）。
+    let moved = dir.path().join("moved-target");
+    std::fs::rename(real, &moved).expect("移走联接目标");
+
+    let (code, stdout, stderr) = run_cli(&["instances", "scan", "--json", "--data-dir", &data_arg]);
+    assert_eq!(
+        code, 1,
+        "祖先断链必须非零退出：stdout={stdout} stderr={stderr}"
+    );
+    let value = parse_json(&stdout);
+    assert_eq!(value["ok"], false, "{stdout}");
+    assert_eq!(
+        value["error"]["code"], "adopt_versions_unreadable",
+        "{stdout}"
+    );
+}

crates/cli/tests/adopt_test/collision_cases.rs

@@ -0,0 +1,195 @@
+//! 运行目录**碰撞**的 CLI 面：slug 同名 / 大小写不敏感不许让两个实例共用一个目录（复审 r1 的 R1）。
+//!
+//! 从 `tests/adopt_test.rs` 拆出来只为守 400 行硬线；用例体未改。
+
+use std::path::Path;
+
+use crate::support::{parse_json, run_cli, TempDir};
+
+use crate::fixture::foreign_data_root;
+
+/// **slug 碰撞的两个展示名不能绑定同一个物理运行目录**（R1 的 CLI 面）。
+///
+/// 复审 r1 的实跑：`Better MC` 与 `Better-MC` 都成功、两个 UUID、却指向同一个目录，
+/// 随后 `launch --dry-run` 的 `--gameDir` 也是同一个。这条把它钉住。
+///
+/// 抓得住：
+/// - 登记侧不查已有实例占用的目录（两个 `run_dir` 相同，第一条断言红）；
+/// - `launch` 的 `game_dir` 与登记的目录不一致（第三条断言红）。
+///
+/// 抓不住：`pack_dir` 的 slug 规则本身（既有行为，本 mission 不改）。
+#[test]
+fn colliding_slug_names_get_separate_run_dirs() {
+    let dir = TempDir::new("adopt-slug");
+    let root = dir.path();
+    foreign_data_root(root);
+    let dir_arg = dir.arg();
+
+    let first = run_cli(&[
+        "instances",
+        "adopt",
+        "1.20.1",
+        "--name",
+        "Better MC",
+        "--json",
+        "--data-dir",
+        dir_arg.as_str(),
+    ]);
+    assert_eq!(
+        first.0, 0,
+        "第一次登记应成功：stdout={} stderr={}",
+        first.1, first.2
+    );
+    let first = parse_json(&first.1);
+    let second = run_cli(&[
+        "instances",
+        "adopt",
+        "1.20.1",
+        "--name",
+        "Better-MC",
+        "--json",
+        "--data-dir",
+        dir_arg.as_str(),
+    ]);
+    assert_eq!(
+        second.0, 0,
+        "第二次登记应成功：stdout={} stderr={}",
+        second.1, second.2
+    );
+    let second = parse_json(&second.1);
+
+    let first_dir = first["data"]["instance"]["run_dir"]
+        .as_str()
+        .expect("run_dir A")
+        .to_string();
+    let second_dir = second["data"]["instance"]["run_dir"]
+        .as_str()
+        .expect("run_dir B")
+        .to_string();
+    assert_ne!(first_dir, second_dir, "两个实例不许共用运行目录");
+    assert!(
+        Path::new(&first_dir).is_dir() && Path::new(&second_dir).is_dir(),
+        "两个运行目录都要真实存在"
+    );
+
+    // 真启动计划（dry-run）也要分开：两条实例各自的 game_dir 不同。
+    for (value, expect) in [(&first, &first_dir), (&second, &second_dir)] {
+        let id = value["data"]["instance"]["id"]
+            .as_str()
+            .expect("instance id");
+        let args = [
+            "launch",
+            id,
+            "--dry-run",
+            "--json",
+            "--data-dir",
+            dir_arg.as_str(),
+        ];
+        let (code, stdout, stderr) = run_cli(&args);
+        assert_eq!(
+            code, 0,
+            "stdout={stdout}
+stderr={stderr}"
+        );
+        assert_eq!(
+            parse_json(&stdout)["data"]["game_dir"]
+                .as_str()
+                .expect("game_dir"),
+            expect.as_str()
+        );
+    }
+}
+
+/// **Win32 尾点/尾空格**（r2 R2.1 的 CLI 面）：两次登记 + 两条 `launch --dry-run` 不许落到同一物理目录。
+///
+/// 抓得住：认领目录的尾点/尾空格不归一（第二次默认登记仍拿到 `Foo`，`run_dir` 相同断言红）。
+///
+/// 抓不住：`\?\` verbatim 写法（那本来就不折叠，是另一个目录）。
+#[cfg(windows)]
+#[test]
+fn win32_trailing_dot_or_space_claims_do_not_share_a_run_dir() {
+    for suffix in [".", " "] {
+        let dir = TempDir::new("adopt-win32-alias");
+        let root = dir.path();
+        foreign_data_root(root);
+        let dir_arg = dir.arg();
+        let claimed = root
+            .join(".ULL/data/instances")
+            .join(format!("Foo{suffix}"));
+        let claimed_arg = claimed.display().to_string();
+
+        let first = run_cli(&[
+            "instances",
+            "adopt",
+            "1.20.1",
+            "--name",
+            "First",
+            "--isolation",
+            "custom",
+            "--game-dir",
+            claimed_arg.as_str(),
+            "--json",
+            "--data-dir",
+            dir_arg.as_str(),
+        ]);
+        assert_eq!(
+            first.0, 0,
+            "custom 登记应成功：stdout={} stderr={}",
+            first.1, first.2
+        );
+        let first = parse_json(&first.1);
+
+        let second = run_cli(&[
+            "instances",
+            "adopt",
+            "1.20.1",
+            "--name",
+            "Foo",
+            "--json",
+            "--data-dir",
+            dir_arg.as_str(),
+        ]);
+        assert_eq!(
+            second.0, 0,
+            "默认登记应成功：stdout={} stderr={}",
+            second.1, second.2
+        );
+        let second = parse_json(&second.1);
+
+        let first_dir = first["data"]["instance"]["run_dir"]
+            .as_str()
+            .expect("run_dir A")
+            .to_string();
+        let second_dir = second["data"]["instance"]["run_dir"]
+            .as_str()
+            .expect("run_dir B")
+            .to_string();
+        assert_ne!(
+            first_dir, second_dir,
+            "尾点/尾空格别名不许共用运行目录（suffix={suffix:?}）"
+        );
+
+        // 两条启动计划的 --gameDir 也必须分开（argv 已脱敏，比尾段）。
+        for (value, expect) in [(&first, &first_dir), (&second, &second_dir)] {
+            let id = value["data"]["instance"]["id"]
+                .as_str()
+                .expect("instance id");
+            let args = [
+                "launch",
+                id,
+                "--dry-run",
+                "--json",
+                "--data-dir",
+                dir_arg.as_str(),
+            ];
+            let (code, stdout, stderr) = run_cli(&args);
+            assert_eq!(code, 0, "stdout={stdout} stderr={stderr}");
+            let plan = parse_json(&stdout);
+            assert_eq!(
+                plan["data"]["game_dir"].as_str().expect("game_dir"),
+                expect.as_str(),
+                "启动计划必须落在自己的运行目录（suffix={suffix:?}）"
+            );
+        }
+    }
+}

crates/cli/tests/adopt_test/fixture.rs

@@ -0,0 +1,81 @@
+//! CLI 侧夹具：一个「别的启动器铺好了 `.minecraft`」的数据根。
+//!
+//! 快照工具**复用 core 测试那一份**（`crates/core/tests/adopt/snapshot.rs`，全节点：目录/文件/链接
+//! 各记形状与 mtime）。以前 CLI 自己抄了一份 walk，两份都漏了目录节点——复审 r1 的 R5 正是这个洞，
+//! 所以这里直接 `#[path]` 引用同一份源码：判据只有一处，不会再漂。
+
+#[path = "../../../core/tests/adopt/snapshot.rs"]
+mod snapshot;
+
+pub use snapshot::{assert_unchanged, snapshot, snapshot_opt, Node};
+
+use std::path::Path;
+
+/// 造一份「别的启动器已经铺好的」数据根（`<root>/.minecraft` + `<root>/.ULL`）：
+///
+/// | 路径 | 用意 |
+/// | --- | --- |
+/// | `versions/1.20.1/` | 正常版本（清单 + jar），可登记、可 `launch --dry-run` |
+/// | `versions/1.20.1-orphan/` | 缺父版本 ⇒ 不可登记 |
+/// | `libraries/` `assets/` | 恒共享层（登记不该碰） |
+/// | `mods/` `saves/` | 玩家数据（登记不该碰） |
+/// | `launcher_profiles.json` | 别的启动器的元数据（连读都不该读，更不该写） |
+pub fn foreign_data_root(root: &Path) {
+    let minecraft = root.join(".minecraft");
+    let versions = minecraft.join("versions");
+    write_version(&versions, "1.20.1", MANIFEST_OK, true);
+    write_version(&versions, "1.20.1-orphan", MANIFEST_ORPHAN, true);
+    write_file(
+        &minecraft.join("libraries/com/mojang/brigadier/1.0.18/brigadier-1.0.18.jar"),
+        b"library-bytes",
+    );
+    write_file(
+        &minecraft.join("assets/indexes/5.json"),
+        b"{\"objects\":{}}",
+    );
+    write_file(&minecraft.join("mods/jei.jar"), b"mod-bytes");
+    write_file(&minecraft.join("saves/World/level.dat"), b"save-bytes");
+    write_file(
+        &minecraft.join("launcher_profiles.json"),
+        br#"{"profiles":{"1.20.1":{"name":"1.20.1","lastVersionId":"1.20.1"}}}"#,
+    );
+}
+
+fn write_version(versions: &Path, id: &str, manifest: &str, jar: bool) {
+    let dir = versions.join(id);
+    std::fs::create_dir_all(&dir).expect("建版本目录");
+    std::fs::write(dir.join(format!("{id}.json")), manifest.as_bytes()).expect("写清单");
+    if jar {
+        std::fs::write(dir.join(format!("{id}.jar")), b"junk").expect("写 jar");
+    }
+}
+
+fn write_file(path: &Path, bytes: &[u8]) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建父目录");
+    }
+    std::fs::write(path, bytes).expect("写文件");
+}
+
+const MANIFEST_OK: &str = r#"{
+  "id": "1.20.1",
+  "type": "release",
+  "mainClass": "net.minecraft.client.main.Main",
+  "assets": "5",
+  "assetIndex": { "id": "5" },
+  "arguments": {
+    "game": ["--username", "${auth_player_name}", "--version", "${version_name}",
+             "--gameDir", "${game_directory}"],
+    "jvm": ["-Djava.library.path=${natives_directory}", "-cp", "${classpath}"]
+  },
+  "libraries": [],
+  "downloads": { "client": { "size": 4, "url": "http://example.invalid/client.jar" } }
+}"#;
+
+const MANIFEST_ORPHAN: &str = r#"{
+  "id": "1.20.1-orphan",
+  "type": "release",
+  "inheritsFrom": "1.20.1-not-on-disk",
+  "mainClass": "net.minecraft.client.main.Main",
+  "libraries": []
+}"#;

crates/core/src/game/adopt.rs

@@ -0,0 +1,59 @@
+//! 登记「已经铺在盘上的版本」（从其他启动器的 `.minecraft` 只读接入，M221）。
+//!
+//! 依据：`DevDocs/artifacts/m218/SURVEY-p4.md`（④ 从其他启动器导入数据）与
+//! `DevDocs/00-债务台账.md` §21 的第 ④ 条；模型口径仍按 D20（实例隔离只改**运行目录**，
+//! `versions/` `assets/` `libraries/` 恒共享，见 [`crate::game::isolation::SHARED_LAYERS`]）。
+//!
+//! # 一句话纪律
+//!
+//! **登记只读外部、只写自己**：本模块从不往游戏根写一个字节（不搬文件、不补清单、不改 mtime），
+//! 唯一的写盘是 `profiles.json` + `config/instances/<id>.json`（+ 缺省运行目录的准备，若选了它）。
+//! 因此「导入前后对 `versions/` `libraries/` 做全量哈希必须完全不变」是可以用测试钉死的事实。
+//!
+//! # 为什么要有它（现状的洞）
+//!
+//! [`GameLayout::installed_versions`] 早就会扫 `versions/`，但**没有任何代码把扫到的东西变成实例**。
+//! 于是「别人的 `.minecraft` 已经装好了 1.20.1」这件事在 ULL 里看不见，用户只能重装一遍
+//! （下载全部资源）。这个模块把那批版本变成实例档案，内容一个字节不搬。
+//!
+//! # 缺省隔离档**不能**沿用全局 `isolated`（本模块最要紧的一条）
+//!
+//! 全局 `instances.mode` 缺省是 `isolated`，而 `isolated` 的运行目录正是 `versions/<versionId>/`
+//! （[`crate::game::isolation::derive_game_dir`]）。若登记沿用这条缺省，第一次启动就会在
+//! **别人的版本目录**里长出 `mods/` `saves/` `config/` `logs/` —— 不覆盖任何文件，但与
+//! 「多启动器共存」的意图相反。所以 [`AdoptTarget`] 的缺省值是
+//! [`AdoptTarget::InstanceDir`]（落 ULL 数据区 `<data>/instances/<实例目录名>`），
+//! 想共用/写进对方目录必须**显式**选，并且 [`target_notes`] 会把后果说清楚。
+//!
+//! # 分层
+//!
+//! - `candidate`：候选与逐项**结构化失败**（坏 JSON / 缺父 / 环 / 不可读 / 越界 / 符号链接）；
+//! - `error`：整次调用失败（[`AdoptError`]，带稳定错误码）；
+//! - `inspect`：只读扫描与逐项检查（[`scan`] / [`inspect`]）；
+//! - `paths`：路径判据（版本 id 能不能当路径、符号链接有没有跑出游戏根）；
+//! - `fspaths`：路径语义（真实化 / Win32 尾点尾空格归一）与写盘面判据（配置在 `.ULL` 内、
+//!   默认写盘面不得与受保护游戏树重叠）；
+//! - `run_dir`：运行目录派生（含**碰撞消歧**）与「缺省目录必须落在数据区」；
+//! - `plan`：把候选 + 用户选择算成一次登记的落点（[`plan`]），真正落盘是 [`adopt`]。
+//!
+//! # 不做什么
+//!
+//! - **不读账户凭据**：`launcher_profiles.json` / `launcher_accounts.json` / HMCL 的
+//!   `accounts.json` 一个都不碰（`AGENTS.md` §6 同族纪律）；
+//! - **不做多根**（D20 未改）：扫的永远是**当前**游戏根（`core.game_home`），
+//!   「同时管多个 `.minecraft`」是另一个更贵的模型改动，见 SURVEY-p4 §4.2；
+//! - **不下载、不校验完整性**：版本 JSON 里 `libraries[].downloads.artifact.url` 指向 maven
+//!   中心是正常形态，登记不因此拒绝，但也不假装校验过（人读输出里如实写成「未校验」）。
+
+pub mod candidate;
+mod error;
+mod fspaths;
+mod inspect;
+mod paths;
+mod plan;
+mod run_dir;
+
+pub use candidate::{AdoptCandidate, AdoptProblem, AdoptTarget, RegisteredInstance};
+pub use error::AdoptError;
+pub use inspect::{inspect, scan, AdoptScan};
+pub use plan::{adopt, plan, target_notes, AdoptOutcome, AdoptPlan, AdoptRequest};

crates/core/src/game/adopt/candidate.rs

@@ -0,0 +1,276 @@
+//! 登记的**数据形状**：候选、结构化失败、运行目录选择。
+//!
+//! 三种形状刻意分开：
+//! - [`AdoptCandidate`]：盘上的一个 `versions/<id>/` 是不是能登记的版本（含逐项问题）；
+//! - [`AdoptProblem`]：一条**结构化**的不合格原因（有稳定 `code`，人读 `message`）；
+//! - [`AdoptTarget`]：登记后运行目录从哪来（隔离档由它决定）；
+//! - 整次调用的失败形状在 [`super::error::AdoptError`]。
+//!
+//! 为什么不把问题塞进 [`crate::game::GameError`]：`core::game` 的错误是「解析/路径/IO」这一层，
+//! 而这里是「这个版本对我们而言能不能登记」的业务判据（缺父、越界、同名冲突…）。
+//! 混进 `GameError` 会让所有现存 `match` 多出一批只在本模块有意义的变体。
+
+use std::fmt;
+use std::path::PathBuf;
+
+use super::super::install::instance::Isolation;
+
+/// 候选版本的**结构化**不合格原因（每一条都带稳定机读 `code`）。
+///
+/// 判据来源：`DevDocs/artifacts/m218/SURVEY-p4.md` §3 的 copy/引用/拒绝表。任一 `Err` 都意味着
+/// 「登记了也启动不了」或「越界/踩别人的目录」，因此登记前一律拒绝，并把原因原样说给用户。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AdoptProblem {
+    /// `versions/<id>/` 存在但没有同名清单（只剩 natives / 上个启动器的残留）。
+    ManifestMissing {
+        /// 版本 id（目录名）。
+        version_id: String,
+        /// 期望的清单路径 `versions/<id>/<id>.json`。
+        path: PathBuf,
+    },
+    /// 版本 id 本身不能当路径用（空 / 含分隔符 / 盘符 / NUL / 结尾点号空格）。
+    VersionIdInvalid {
+        /// 原始 id。
+        version_id: String,
+        /// 人读原因。
+        reason: &'static str,
+    },
+    /// 清单文件读不出来（权限 / 被占用 / 不是 UTF-8）。
+    ManifestUnreadable {
+        /// 清单路径。
+        path: PathBuf,
+        /// 底层错误文本（含 Win32 错误码或 serde 行列号）。
+        message: String,
+    },
+    /// 清单不是合法 JSON（**带行号列号**，别只说「坏了」）。
+    ManifestInvalidJson {
+        /// 清单路径。
+        path: PathBuf,
+        /// serde_json 的错误文本（含 `line L column C`）。
+        message: String,
+    },
+    /// 清单里没有 `id`。
+    ManifestMissingId {
+        /// 清单路径。
+        path: PathBuf,
+    },
+    /// 清单里的 `id` 与目录名不一致（启动时按清单 id 找 jar，必然找不到）。
+    ManifestIdMismatch {
+        /// 清单路径。
+        path: PathBuf,
+        /// 清单里的 id。
+        manifest_id: String,
+        /// 目录名。
+        directory_id: String,
+    },
+    /// 目录遍历/元数据读不出来（权限、坏链接）。
+    DirectoryUnreadable {
+        /// 出问题的路径。
+        path: PathBuf,
+        /// 底层错误文本。
+        message: String,
+    },
+    /// 已有条目解析到游戏根之外（符号链接 / 目录联接 / 祖先链接；不跟随）。
+    OutsideGameRoot {
+        /// 链接本身。
+        path: PathBuf,
+        /// 解析出来的真实目标。
+        target: PathBuf,
+        /// 比较基准（真实化后的游戏根）。
+        root: PathBuf,
+    },
+    /// 是符号链接但解析不出来（断链 / 权限）。
+    SymlinkUnresolvable {
+        /// 链接本身。
+        path: PathBuf,
+        /// 底层错误文本。
+        message: String,
+    },
+    /// `inheritsFrom` 指向的父版本在盘上找不到。
+    MissingParent {
+        /// 缺失的父版本 id。
+        parent: String,
+        /// 谁在要它。
+        required_by: String,
+    },
+    /// `inheritsFrom` 成环。
+    CircularInheritance {
+        /// 从根到环的 id 链（首尾同一个 id）。
+        chain: Vec<String>,
+    },
+    /// 继承链在 `core::game::resolve` 那里失败（走查通过、权威解析不通过的兜底）。
+    InheritanceInvalid {
+        /// `GameError` 的人读文本。
+        detail: String,
+    },
+}
+
+impl AdoptProblem {
+    /// 稳定机读码（`--json` 的 `problems[].code`）。
+    #[must_use]
+    pub const fn code(&self) -> &'static str {
+        match self {
+            Self::ManifestMissing { .. } => "manifest_missing",
+            Self::VersionIdInvalid { .. } => "version_id_invalid",
+            Self::ManifestUnreadable { .. } => "manifest_unreadable",
+            Self::ManifestInvalidJson { .. } => "manifest_invalid_json",
+            Self::ManifestMissingId { .. } => "manifest_missing_id",
+            Self::ManifestIdMismatch { .. } => "manifest_id_mismatch",
+            Self::DirectoryUnreadable { .. } => "directory_unreadable",
+            Self::OutsideGameRoot { .. } => "outside_game_root",
+            Self::SymlinkUnresolvable { .. } => "symlink_unresolvable",
+            Self::MissingParent { .. } => "missing_parent",
+            Self::CircularInheritance { .. } => "circular_inheritance",
+            Self::InheritanceInvalid { .. } => "inheritance_invalid",
+        }
+    }
+}
+
+impl fmt::Display for AdoptProblem {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::ManifestMissing { version_id, path } => write!(
+                f,
+                "版本 {version_id} 没有清单文件（期望 {}）",
+                path.display()
+            ),
+            Self::VersionIdInvalid { version_id, reason } => {
+                write!(f, "版本 id 不能当路径用（{reason}）：{version_id:?}")
+            }
+            Self::ManifestUnreadable { path, message } => {
+                write!(f, "清单读不出来 {}：{message}", path.display())
+            }
+            Self::ManifestInvalidJson { path, message } => {
+                write!(f, "清单不是合法 JSON {}：{message}", path.display())
+            }
+            Self::ManifestMissingId { path } => {
+                write!(f, "清单缺少 id 字段：{}", path.display())
+            }
+            Self::ManifestIdMismatch {
+                path,
+                manifest_id,
+                directory_id,
+            } => write!(
+                f,
+                "清单 id（{manifest_id}）与目录名（{directory_id}）不一致：{}——启动时会按清单 id 找 jar，必然找不到",
+                path.display()
+            ),
+            Self::DirectoryUnreadable { path, message } => {
+                write!(f, "目录读不出来 {}：{message}", path.display())
+            }
+            Self::OutsideGameRoot { path, target, root } => write!(
+                f,
+                "条目解析到游戏根之外，不跟随：{} -> {}（游戏根 {}）",
+                path.display(),
+                target.display(),
+                root.display()
+            ),
+            Self::SymlinkUnresolvable { path, message } => {
+                write!(f, "符号链接解析失败 {}：{message}", path.display())
+            }
+            Self::MissingParent { parent, required_by } => {
+                write!(f, "版本 {required_by} 继承的父版本 {parent} 不在盘上")
+            }
+            Self::CircularInheritance { chain } => {
+                write!(f, "版本继承成环：{}", chain.join(" -> "))
+            }
+            Self::InheritanceInvalid { detail } => write!(f, "继承链解析失败：{detail}"),
+        }
+    }
+}
+
+/// 已经绑定某个版本 id 的实例档案（只带展示需要的最小信息，不泄露内部结构）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RegisteredInstance {
+    /// 实例 id。
+    pub id: String,
+    /// 实例展示名。
+    pub name: String,
+}
+
+/// 盘上的一个候选版本（扫出来的一个 `versions/<id>/`）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdoptCandidate {
+    /// 版本 id（= 目录名，登记后写进 `profiles.json` 的 `version_id`）。
+    pub version_id: String,
+    /// 版本目录 `versions/<id>/`。
+    pub version_dir: PathBuf,
+    /// 清单路径 `versions/<id>/<id>.json`。
+    pub manifest_path: PathBuf,
+    /// 客户端 jar `versions/<id>/<id>.jar` 是否存在（只报事实，不校验内容）。
+    pub jar_present: bool,
+    /// 清单里声明的 id（读不出来时为 `None`）。
+    pub manifest_id: Option<String>,
+    /// `inheritsFrom` 链（自身在前、最祖先在后；读不出来时是已走通的那一段）。
+    pub inherits: Vec<String>,
+    /// 已有实例绑定这个版本（空 = 还没登记过）。
+    pub registered: Vec<RegisteredInstance>,
+    /// 问题清单（空 = 可登记）。
+    pub problems: Vec<AdoptProblem>,
+}
+
+impl AdoptCandidate {
+    /// 是否可登记（没有任何问题）。
+    #[must_use]
+    pub fn adoptable(&self) -> bool {
+        self.problems.is_empty()
+    }
+
+    /// 已登记过（至少有一个实例绑定这个版本 id）。
+    #[must_use]
+    pub fn is_registered(&self) -> bool {
+        !self.registered.is_empty()
+    }
+}
+
+/// 登记后实例的**运行目录**从哪来（隔离档由它决定，见 [`AdoptTarget::isolation`]）。
+///
+/// 缺省是 [`Self::InstanceDir`]——**不是** `isolated`：理由见模块文档。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub enum AdoptTarget {
+    /// 缺省：ULL 数据区里新建独立运行目录 `<data>/instances/<实例目录名>`（写 `custom` 档）。
+    #[default]
+    InstanceDir,
+    /// 共用当前游戏根（别人的 `.minecraft`）——必须显式选，且必须告知后果。
+    Shared,
+    /// 版本目录 `versions/<id>/`（`isolated` 档）——会在别人的版本目录里长玩家数据。
+    VersionDir,
+    /// 用户指定的目录（`custom` 档，必须绝对路径）。
+    Custom(PathBuf),
+}
+
+impl AdoptTarget {
+    /// 稳定机读 id（`--json` 的 `run_dir_source`）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::InstanceDir => "instance_dir",
+            Self::Shared => "shared",
+            Self::VersionDir => "version_dir",
+            Self::Custom(_) => "custom",
+        }
+    }
+
+    /// 生效隔离档。
+    #[must_use]
+    pub const fn isolation(&self) -> Isolation {
+        match self {
+            Self::InstanceDir | Self::Custom(_) => Isolation::Custom,
+            Self::Shared => Isolation::Shared,
+            Self::VersionDir => Isolation::Isolated,
+        }
+    }
+
+    /// 命令行/配置里的词表（`shared` / `isolated` / `custom`，与 [`Isolation`] 同一套字面量）。
+    ///
+    /// `instance_dir` 有意**不接受**输入：它是缺省值，不是一个用户可以手写选中的档位。
+    #[must_use]
+    pub fn parse(raw: &str, game_dir: Option<PathBuf>) -> Option<Self> {
+        match raw.trim() {
+            "shared" => Some(Self::Shared),
+            "isolated" | "per_version" => Some(Self::VersionDir),
+            "custom" => game_dir.map(Self::Custom),
+            _ => None,
+        }
+    }
+}

crates/core/src/game/adopt/error.rs

@@ -0,0 +1,194 @@
+//! 一次登记的失败形状（CLI 据此给稳定错误码 + 结构化 details）。
+//!
+//! 与 [`AdoptProblem`] 的分工：`AdoptProblem` 是「这个版本为什么不能登记」（可以多条、逐条列出），
+//! [`AdoptError`] 是「这次调用为什么没成功」（一条，喂给 `--json` 的 `error.code`）。
+//! 候选不合格是后者的一个变体，但问题清单原样带出来——不许把原因折叠成一句「导入失败」。
+
+use std::fmt;
+use std::path::PathBuf;
+
+use super::candidate::AdoptProblem;
+use crate::game::error::GameError;
+
+/// 一次登记失败（CLI 据此给稳定错误码 + 结构化 details）。
+#[derive(Debug)]
+pub enum AdoptError {
+    /// `core::game` 的解析/路径/IO 失败。
+    Game(GameError),
+    /// 版本 id 在盘上不存在（没有 `versions/<id>/`）。
+    UnknownVersion {
+        /// 请求的版本 id。
+        version_id: String,
+        /// 期望的目录。
+        version_dir: PathBuf,
+    },
+    /// 候选不合格（`problems` 就是全部原因，一条都不吞）。
+    NotAdoptable {
+        /// 版本 id。
+        version_id: String,
+        /// 全部原因。
+        problems: Vec<AdoptProblem>,
+    },
+    /// 展示名已被别的实例占用（**显式报错**，不静默复用一条别的版本）。
+    DuplicateName {
+        /// 冲突的展示名。
+        name: String,
+        /// 占用它的实例 id。
+        instance_id: String,
+    },
+    /// 这个版本已经以同名实例登记过了（重复执行 = 无副作用失败）。
+    AlreadyRegistered {
+        /// 版本 id。
+        version_id: String,
+        /// 已存在的实例名。
+        name: String,
+        /// 已存在的实例 id。
+        instance_id: String,
+    },
+    /// 缺省运行目录已存在且非空（不猜「合并进已有实例」，也不覆盖）。
+    TargetNotEmpty {
+        /// 那个目录。
+        path: PathBuf,
+    },
+    /// 运行目录选择本身不成立（`custom` 缺目录 / 相对路径）。
+    TargetInvalid {
+        /// 人读原因。
+        detail: String,
+    },
+    /// 缺省运行目录的后缀全被占用（`-2` … `-33` 都撞上了）——不无限顺延，直接报错。
+    NoFreeRunDir {
+        /// 派生用的基准目录。
+        base: PathBuf,
+    },
+    /// 配置写面（`config/`、`config/instances/`、`profiles.json`）的真实落点不可信：
+    /// 跑出 `<.ULL>` 或落进游戏根（符号链接 / 目录联接）。
+    ConfigSurfaceUnsafe {
+        /// 出问题的目标路径（`config/`、`config/instances/` 或 `profiles.json`）。
+        path: PathBuf,
+        /// 人读原因（含解析后的真实位置）。
+        detail: String,
+    },
+    /// 默认写盘面（`.ULL`/`data`/配置/缺省运行目录）解析后落在**受保护游戏树**之内（r2 R2.2）。
+    ///
+    /// 与 [`Self::ConfigSurfaceUnsafe`] 的分工：那条管「配置跑出 `.ULL`」，这条管「写盘面与游戏树重叠」。
+    WriteSurfaceInGameTree {
+        /// 出问题的写盘面（`.ULL`、`data/`、配置目录、缺省运行目录…）。
+        path: PathBuf,
+        /// 人读原因（含解析后的真实位置与「请换不重叠的数据目录」的指引）。
+        detail: String,
+    },
+    /// `versions` 入口存在但读不出来（断链的符号链接/目录联接、目标被移走、祖先断链）。
+    ///
+    /// 与「`versions` 真不存在」严格区分：后者才是空结果，前者必须具名报错。
+    VersionsDirUnreadable {
+        /// 出问题的路径（`versions/` 或游戏根）。
+        path: PathBuf,
+        /// 人读原因。
+        detail: String,
+    },
+}
+
+impl AdoptError {
+    /// 稳定机读码（`--json` 的 `error.code`）。
+    #[must_use]
+    pub const fn code(&self) -> &'static str {
+        match self {
+            Self::Game(_) => "adopt_io",
+            Self::UnknownVersion { .. } => "adopt_version_not_found",
+            Self::NotAdoptable { .. } => "adopt_not_adoptable",
+            Self::DuplicateName { .. } => "adopt_duplicate_name",
+            Self::AlreadyRegistered { .. } => "adopt_already_registered",
+            Self::TargetNotEmpty { .. } => "adopt_target_not_empty",
+            Self::TargetInvalid { .. } => "adopt_target_invalid",
+            Self::NoFreeRunDir { .. } => "adopt_no_free_run_dir",
+            Self::ConfigSurfaceUnsafe { .. } => "adopt_config_surface_unsafe",
+            Self::WriteSurfaceInGameTree { .. } => "adopt_write_surface_in_game_tree",
+            Self::VersionsDirUnreadable { .. } => "adopt_versions_unreadable",
+        }
+    }
+
+    /// 候选不合格时的问题清单（其它错误为空）。
+    #[must_use]
+    pub fn problems(&self) -> &[AdoptProblem] {
+        match self {
+            Self::NotAdoptable { problems, .. } => problems,
+            _ => &[],
+        }
+    }
+}
+
+impl fmt::Display for AdoptError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Game(error) => write!(f, "{error}"),
+            Self::UnknownVersion {
+                version_id,
+                version_dir,
+            } => write!(
+                f,
+                "版本 {version_id} 不在盘上（没有 {}）",
+                version_dir.display()
+            ),
+            Self::NotAdoptable {
+                version_id,
+                problems,
+            } => {
+                write!(f, "版本 {version_id} 不能登记：")?;
+                for (index, problem) in problems.iter().enumerate() {
+                    if index > 0 {
+                        f.write_str("；")?;
+                    }
+                    write!(f, "{problem}")?;
+                }
+                Ok(())
+            }
+            Self::DuplicateName { name, instance_id } => write!(
+                f,
+                "已有同名实例 `{name}`（id {instance_id}）：导入时请用 --name 换一个展示名"
+            ),
+            Self::AlreadyRegistered {
+                version_id,
+                name,
+                instance_id,
+            } => write!(
+                f,
+                "版本 {version_id} 已经登记过（实例 `{name}`，id {instance_id}）：没有改动任何文件"
+            ),
+            Self::TargetNotEmpty { path } => {
+                write!(f, "运行目录已存在且非空，不覆盖：{}", path.display())
+            }
+            Self::TargetInvalid { detail } => write!(f, "运行目录选择不成立：{detail}"),
+            Self::NoFreeRunDir { base } => write!(
+                f,
+                "为这个实例派生独立运行目录失败：{} 及其 -2…-33 后缀都被别的实例占着",
+                base.display()
+            ),
+            Self::ConfigSurfaceUnsafe { path, detail } => {
+                write!(f, "配置写面不可信：{} {detail}", path.display())
+            }
+            Self::WriteSurfaceInGameTree { path, detail } => {
+                write!(f, "写盘面与游戏树重叠：{} {detail}", path.display())
+            }
+            Self::VersionsDirUnreadable { path, detail } => write!(
+                f,
+                "versions 入口存在但读不出来 {}：{detail}",
+                path.display()
+            ),
+        }
+    }
+}
+
+impl std::error::Error for AdoptError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Game(error) => Some(error),
+            _ => None,
+        }
+    }
+}
+
+impl From<GameError> for AdoptError {
+    fn from(error: GameError) -> Self {
+        Self::Game(error)
+    }
+}

crates/core/src/game/adopt/fspaths.rs

@@ -0,0 +1,195 @@
+//! 路径语义与**写盘面**判据：真实化、Win32 别名归一、配置写面、与受保护游戏树的重叠。
+//!
+//! # 为什么单独一层
+//!
+//! 「这个路径到底是哪个物理位置」在 Windows 上不是字符串比较：普通路径的**尾点/尾空格会被 Win32
+//! 折叠**（`Foo.` 与 `Foo ` 都落到 `Foo`），而 verbatim 路径（`\\?\…`）**不**折叠。`canonicalize`
+//! 只能回答「已存在的东西在哪」，尚不存在的尾段（`custom` 档认领的目录、派生出来还没建的缺省目录）
+//! 必须自己按平台语义归一，否则「两个实例共用同一个物理目录」会从这个缝里漏过去（复审 r2 的 R2.1）。
+//!
+//! 另一件事是**写盘面**：登记承诺「只写 ULL 自己的配置、外部游戏树零写入」。判据分两条：
+//! 1. 配置落点必须在 `<.ULL>` 内（[`ensure_config_write_surface`]）；
+//! 2. 全部默认写盘面（`.ULL` 自身、`config/`、`config/instances/`、`profiles.json`、`data/`
+//!    以及缺省运行目录）**不得与受保护游戏树重叠**（[`ensure_surfaces_clear_of_game_tree`]）。
+//!    用户把整个 `.ULL`/`data` 迁到游戏树外是合法迁移，照样通过；重叠则具名拒绝——
+//!    不能写完之后再补一句 warning（复审 r2 的 R2.2）。
+//!
+//! # 已知边界
+//!
+//! 判据都是「检查那一刻」的快照（TOCTOU 看不到）；Win32 的 8.3 短名别名不在归一范围内
+//! （未就绪的短名无法可靠推导），非 junction 的重解析点也未逐个识别。
+
+use std::ffi::OsString;
+use std::path::{Path, PathBuf};
+
+use super::super::layout::GameLayout;
+use super::error::AdoptError;
+use crate::platform::layout::LauncherLayout;
+
+/// **最近**的已存在祖先/自身解析出的真实路径 + 尚不存在的尾段（`None` = 整条链都不存在）。
+///
+/// 用于**位置判据**（越界比较、写面重叠）：这里不做别名折叠——问的是「物理上在哪」。
+pub(super) fn existing_real(path: &Path) -> Option<PathBuf> {
+    resolve(path, false)
+}
+
+/// **比较键**用的路径：已存在部分真实化，尚不存在的尾段按平台语义归一（Windows 折叠尾点/尾空格，
+/// verbatim 路径除外）。两个不同写法指向同一个物理目录时，键必须相等。
+pub(super) fn comparison_real(path: &Path) -> Option<PathBuf> {
+    resolve(path, true)
+}
+
+fn resolve(path: &Path, fold_tail: bool) -> Option<PathBuf> {
+    let verbatim = is_verbatim(path);
+    let mut probe = path.to_path_buf();
+    let mut tail: Vec<OsString> = Vec::new();
+    loop {
+        if std::fs::symlink_metadata(&probe).is_ok() {
+            let real = probe.canonicalize().ok()?;
+            let mut full = real;
+            for part in tail.iter().rev() {
+                if fold_tail {
+                    full.push(platform_component(part, verbatim));
+                } else {
+                    full.push(part);
+                }
+            }
+            return Some(full);
+        }
+        let name = probe.file_name().map(OsString::from)?;
+        tail.push(name);
+        if !probe.pop() {
+            return None;
+        }
+    }
+}
+
+/// 整条路径是不是 verbatim 形式（`\\?\…` / `\\.\…`）：那种写法**不**折叠尾点/尾空格。
+fn is_verbatim(path: &Path) -> bool {
+    #[cfg(windows)]
+    {
+        let text = path.to_string_lossy();
+        text.starts_with(r"\\?\") || text.starts_with(r"\\.\")
+    }
+    #[cfg(not(windows))]
+    {
+        let _ = path;
+        false
+    }
+}
+
+/// 尚不存在的一段名字按**平台语义**归一。
+///
+/// Windows（非 verbatim）：去掉尾部的 `.` 与空格——Win32 建目录/解析路径时就这么做，所以
+/// `Foo.`、`Foo `、`Foo` 是同一个物理目录。全是点/空格的名字保持原样（那种名字本身建不出来，
+/// 折叠成空串只会制造新的歧义）。其它平台原样返回（`Foo.` 与 `Foo` 是不同目录）。
+fn platform_component(name: &std::ffi::OsStr, verbatim: bool) -> OsString {
+    #[cfg(windows)]
+    {
+        if !verbatim {
+            let text = name.to_string_lossy();
+            let trimmed = text.trim_end_matches(['.', ' ']);
+            if !trimmed.is_empty() && trimmed.len() != text.len() {
+                return OsString::from(trimmed.to_string());
+            }
+        }
+    }
+    let _ = verbatim;
+    name.to_os_string()
+}
+
+/// 路径 → 比较键（`/` 分隔 + 大小写归一；大小写只在大小写不敏感的平台折叠）。
+pub(super) fn normalize_key(path: &Path) -> String {
+    let text = path.to_string_lossy().replace('\\', "/");
+    if cfg!(any(windows, target_os = "macos")) {
+        text.to_lowercase()
+    } else {
+        text
+    }
+}
+
+/// 配置写面（`config/`、`config/instances/`、`profiles.json`）必须在 `<.ULL>` 之内。
+///
+/// 只管「在不在自己家里」；「有没有落进受保护游戏树」由
+/// [`ensure_surfaces_clear_of_game_tree`] 统一负责（两条判据各有单一职责，不再互相豁免）。
+///
+/// # Errors
+///
+/// 落点跑出 `<.ULL>`：`ConfigSurfaceUnsafe`。
+pub(super) fn ensure_config_write_surface(launcher: &LauncherLayout) -> Result<(), AdoptError> {
+    let Some(home_real) = existing_real(launcher.home()) else {
+        // `<.ULL>` 都还不存在 ⇒ 还不可能有链接可言。
+        return Ok(());
+    };
+    let targets = [
+        launcher.config(),
+        launcher.config().join("instances"),
+        launcher.profiles_config(),
+    ];
+    for target in targets {
+        let Some(real) = existing_real(&target) else {
+            continue;
+        };
+        if !real.starts_with(&home_real) {
+            return Err(AdoptError::ConfigSurfaceUnsafe {
+                path: target,
+                detail: format!(
+                    "解析到 {}，落在启动器目录 {} 之外（有指向外部的符号链接/目录联接）",
+                    real.display(),
+                    home_real.display()
+                ),
+            });
+        }
+    }
+    Ok(())
+}
+
+/// 默认写盘面**不得**与受保护游戏树重叠（`.ULL`/`data`/配置/缺省运行目录解析后都不许落进游戏根）。
+///
+/// 为什么要它：用户可能预先在数据根里放过目录联接（不是 adopt 建的）。这时「默认独立目录」写着写着
+/// 就写进了别人的 `.minecraft`，输出却还说「与别人的 .minecraft 隔离」——那是**假承诺**。
+/// 判据在**写入之前**给出具名拒绝，并让用户把数据目录挪到游戏树之外；整体迁移到游戏树**之外**照旧允许。
+///
+/// `run_dir` 只在缺省档（`InstanceDir`）传：`shared` / `version_dir` / `custom` 是用户显式选择的
+/// 运行目录，允许与游戏树重叠（那是选择的语义，不是偷偷写的）。
+///
+/// # Errors
+///
+/// 任一面解析后落进游戏根：`WriteSurfaceInGameTree`。
+pub(super) fn ensure_surfaces_clear_of_game_tree(
+    game: &GameLayout,
+    launcher: &LauncherLayout,
+    run_dir: Option<&Path>,
+) -> Result<(), AdoptError> {
+    let Some(game_real) = existing_real(game.root()) else {
+        // 游戏根还不存在 ⇒ 没有「受保护游戏树」可重叠。
+        return Ok(());
+    };
+    let mut surfaces = vec![
+        launcher.home().to_path_buf(),
+        launcher.config(),
+        launcher.config().join("instances"),
+        launcher.profiles_config(),
+        launcher.data(),
+    ];
+    if let Some(run_dir) = run_dir {
+        surfaces.push(run_dir.to_path_buf());
+    }
+    for surface in surfaces {
+        let Some(real) = existing_real(&surface) else {
+            continue;
+        };
+        if real.starts_with(&game_real) {
+            return Err(AdoptError::WriteSurfaceInGameTree {
+                path: surface,
+                detail: format!(
+                    "解析到 {}，落在受保护游戏树 {} 之内：默认登记不会把实例数据写进别人的 .minecraft；\
+                     请把 .ULL（或 --data-dir）指到游戏树之外的目录再登记（整体迁移本身是合法的）",
+                    real.display(),
+                    game_real.display()
+                ),
+            });
+        }
+    }
+    Ok(())
+}

crates/core/src/game/adopt/inspect.rs

@@ -0,0 +1,400 @@
+//! 只读扫描与逐项检查：`versions/` 下哪些版本能登记、不能登记的原因是什么。
+//!
+//! # 三条不许偷懒的判据
+//!
+//! 1. **坏东西不能当空列表**：`versions/` 读不了是错误（[`AdoptError::Game`]），一个版本的清单坏了是
+//!    一条 [`AdoptProblem`]；两条都不会变成「这里什么都没有」。
+//! 2. **继承链要走到头**：缺父、成环、父清单坏了、父的清单 id 与目录名不一致，逐条报清楚是哪个文件。
+//! 3. **不跟随越界符号链接**：`versions/<id>` 或清单是符号链接时，解析出的真实路径必须仍在游戏根内
+//!    （与导出侧「符号链接不跟随」同一政策）。
+//!
+//! 全程**只读**：不建目录、不写文件、不改 mtime。
+
+use std::path::{Path, PathBuf};
+
+use super::super::error::GameError;
+use super::super::inherit;
+use super::super::install::instance::read_profiles;
+use super::super::layout::GameLayout;
+use super::super::manifest::VersionJson;
+use super::super::profiles::ProfileList;
+use super::candidate::{AdoptCandidate, AdoptProblem, RegisteredInstance};
+use super::error::AdoptError;
+use super::paths::{ensure_inside, root_of, validate_version_id};
+use crate::platform::layout::LauncherLayout;
+
+/// 一次扫描的结果（`versions/` 里的全部条目，逐项带问题）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdoptScan {
+    /// 被扫的目录（`<游戏根>/versions`）。
+    pub versions_dir: PathBuf,
+    /// 候选版本（按版本 id 字典序）。
+    pub candidates: Vec<AdoptCandidate>,
+}
+
+/// 扫当前游戏根的 `versions/`，逐个检查。
+///
+/// `versions/` **真的不存在** ⇒ 空结果（新装的数据根，没有可登记的东西，不是错误）；
+/// `versions/` 入口**存在但读不出来**（断链的符号链接/目录联接、目标被移走、祖先断链）⇒
+/// [`AdoptError::VersionsDirUnreadable`]，绝不降级成空列表；其它读目录失败 ⇒ [`AdoptError::Game`]。
+///
+/// # Errors
+///
+/// 读目录 / 读 `profiles.json` 失败；条目元数据读不出来（权限）时也直接失败——那属于
+/// 「环境坏了」而不是「这个版本不能登记」。
+pub fn scan(game: &GameLayout, launcher: &LauncherLayout) -> Result<AdoptScan, AdoptError> {
+    let profiles = read_profiles(launcher)?;
+    let versions_dir = game.versions_dir();
+    let root = root_of(game);
+    let entries = match std::fs::read_dir(&versions_dir) {
+        Ok(entries) => entries,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            // **入口还在但读不出来**不是「新数据根」：Windows 上断链的目录联接也只会给 NotFound，
+            // 必须自己用不跟随链接的元数据分辨（复审 r1 的实测：lstat 成功而命令报「空」）。
+            //
+            // r2 R2.3：断链可能发生在**更高的祖先**上（例如 `--data-dir` 指向迁移联接下面的 nested
+            // 目录，联接目标被搬走后 `versions` 与游戏根本身都 NotFound）。所以沿祖先找**最近的
+            // 已存在入口**：它 lstat 得到但 `canonicalize` 不出来 ⇒ 具名报错；一路到盘根都不存在
+            // ⇒ 才是「真正的新数据根」，空结果是诚实的。
+            if let Some(entry) = nearest_existing_entry(&versions_dir) {
+                if entry.canonicalize().is_err() {
+                    return Err(AdoptError::VersionsDirUnreadable {
+                        path: entry,
+                        detail: "最近的已存在入口解析失败（断链的符号链接/目录联接，或目标被移走）"
+                            .to_owned(),
+                    });
+                }
+            }
+
+            return Ok(AdoptScan {
+                versions_dir,
+                candidates: Vec::new(),
+            });
+        }
+        Err(error) => return Err(GameError::io(&versions_dir, error).into()),
+    };
+    let mut candidates: Vec<AdoptCandidate> = Vec::new();
+    for entry in entries {
+        let entry = entry.map_err(|error| GameError::io(&versions_dir, error))?;
+        let path = entry.path();
+        let Some(version_id) = path.file_name().and_then(|name| name.to_str()) else {
+            // 非 UTF-8 目录名不能当版本 id（进不了 profiles.json），如实记一条问题而不是丢掉。
+            candidates.push(unreadable_id_candidate(&path, &versions_dir));
+            continue;
+        };
+        match std::fs::metadata(&path) {
+            Ok(meta) if meta.is_dir() => {}
+            Ok(_) => continue, // `versions/` 里的普通文件不是版本目录
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                // 断链符号链接：元数据跟不过去，但链接本身在。
+                if std::fs::symlink_metadata(&path).is_ok() {
+                    candidates.push(broken_link_candidate(version_id, &path));
+                }
+                continue;
+            }
+            Err(error) => return Err(GameError::io(&path, error).into()),
+        }
+        candidates.push(check(game, &root, version_id, &profiles));
+    }
+    candidates.sort_by(|a, b| a.version_id.cmp(&b.version_id));
+    Ok(AdoptScan {
+        versions_dir,
+        candidates,
+    })
+}
+
+/// 检查单个版本。
+///
+/// 与 [`scan`] 用同一套判据，但**先**校验 id 能不能当路径用（非法 id 连存在性都不该去探，
+/// 否则 `versions/../../外面的/1.20.1` 这种形状会先撞上「目录真的存在」再报出别的结论）。
+/// 候选不合格一律 [`AdoptError::NotAdoptable`] 且把问题清单原样带出，只有环境级失败才 `Err`。
+///
+/// # Errors
+///
+/// - [`AdoptError::NotAdoptable`]：id 非法，或候选有问题（坏清单 / 缺父 / 环 / 越界…）；
+/// - [`AdoptError::UnknownVersion`]：id 合法但 `versions/<id>/` 不存在；
+/// - [`AdoptError::Game`]：读 `profiles.json` 失败。
+pub fn inspect(
+    game: &GameLayout,
+    launcher: &LauncherLayout,
+    version_id: &str,
+) -> Result<AdoptCandidate, AdoptError> {
+    if let Err(problem) = validate_version_id(version_id) {
+        return Err(AdoptError::NotAdoptable {
+            version_id: version_id.to_owned(),
+            problems: vec![problem],
+        });
+    }
+    if !game.version_dir(version_id).is_dir() {
+        let version_dir = game.version_dir(version_id);
+        // 条目存在但不是可读目录（断链链接/联接、或同名的是个文件）⇒ 具名报错，别混成「没装」。
+        if std::fs::symlink_metadata(&version_dir).is_ok() {
+            return Err(AdoptError::NotAdoptable {
+                version_id: version_id.to_owned(),
+                problems: vec![AdoptProblem::DirectoryUnreadable {
+                    path: version_dir,
+                    message: "条目存在但不是可读目录（断链 / 联接目标被移走 / 同名的是文件）"
+                        .to_owned(),
+                }],
+            });
+        }
+        return Err(AdoptError::UnknownVersion {
+            version_id: version_id.to_owned(),
+            version_dir,
+        });
+    }
+    let profiles = read_profiles(launcher)?;
+    let candidate = check(game, &root_of(game), version_id, &profiles);
+    if candidate.adoptable() {
+        Ok(candidate)
+    } else {
+        Err(AdoptError::NotAdoptable {
+            version_id: candidate.version_id.clone(),
+            problems: candidate.problems.clone(),
+        })
+    }
+}
+
+/// 逐项检查一个版本目录。
+fn check(
+    game: &GameLayout,
+    root: &Path,
+    version_id: &str,
+    profiles: &ProfileList,
+) -> AdoptCandidate {
+    let version_dir = game.version_dir(version_id);
+    let manifest_path = game.version_json(version_id);
+    let registered = registered_for(profiles, version_id);
+    let mut candidate = AdoptCandidate {
+        version_id: version_id.to_owned(),
+        version_dir: version_dir.clone(),
+        manifest_path: manifest_path.clone(),
+        jar_present: false,
+        manifest_id: None,
+        inherits: Vec::new(),
+        registered,
+        problems: Vec::new(),
+    };
+
+    // ① id 能不能当路径用：不能的话后面的 join 全不可信，直接结束。
+    if let Err(problem) = validate_version_id(version_id) {
+        candidate.problems.push(problem);
+        return candidate;
+    }
+    // ② 版本目录解析到根外（符号链接 / 目录联接 / 祖先链接）⇒ 立刻停手：
+    //    **一个字节都不去读**那个目录（读它就等于读别人的启动器数据）。
+    if let Some(problem) = ensure_inside(&version_dir, root) {
+        candidate.problems.push(problem);
+        return candidate;
+    }
+    // ③ 清单必须在（`installed_versions` 的判据同源）。
+    if !manifest_path.is_file() {
+        candidate.problems.push(AdoptProblem::ManifestMissing {
+            version_id: version_id.to_owned(),
+            path: manifest_path,
+        });
+        return candidate;
+    }
+    if let Some(problem) = ensure_inside(&manifest_path, root) {
+        candidate.problems.push(problem);
+        return candidate;
+    }
+    candidate.jar_present = game.version_jar(version_id).is_file();
+
+    // ④ 清单读得出来、id 对得上。
+    let manifest = match read_manifest(&manifest_path) {
+        Ok(manifest) => manifest,
+        Err(problem) => {
+            candidate.problems.push(problem);
+            return candidate;
+        }
+    };
+    let manifest_id = manifest.id.clone();
+    candidate.manifest_id = manifest_id.clone();
+    match manifest_id.as_deref() {
+        None => {
+            candidate.problems.push(AdoptProblem::ManifestMissingId {
+                path: manifest_path.clone(),
+            });
+            return candidate;
+        }
+        Some(id) if id != version_id => {
+            candidate.problems.push(AdoptProblem::ManifestIdMismatch {
+                path: manifest_path.clone(),
+                manifest_id: id.to_owned(),
+                directory_id: version_id.to_owned(),
+            });
+        }
+        Some(_) => {}
+    }
+
+    // ⑤ 继承链走到底（缺父 / 环 / 父清单坏 / 父 id 不匹配都在这条路上报）。
+    match walk_chain(game, root, &manifest_path, manifest) {
+        Ok(chain) => {
+            candidate.inherits = chain;
+            // 走查通过后再让 `resolve` 做一次权威判定：两处判据不许漂。
+            if let Some(problem) = resolve_verdict(game, &candidate.manifest_path) {
+                candidate.problems.push(problem);
+            }
+        }
+        Err(problem) => candidate.problems.push(problem),
+    }
+    candidate
+}
+
+/// 走 `inheritsFrom` 链，返回 [自身, 父, 祖父, …]；任一层不合格就返回那条问题。
+fn walk_chain(
+    game: &GameLayout,
+    root: &Path,
+    manifest_path: &Path,
+    manifest: VersionJson,
+) -> Result<Vec<String>, AdoptProblem> {
+    let Some(self_id) = manifest.id.clone() else {
+        return Err(AdoptProblem::ManifestMissingId {
+            path: manifest_path.to_path_buf(),
+        });
+    };
+    let mut chain = vec![self_id];
+    let mut current = manifest;
+    while let Some(parent) = current.inherits_from.clone() {
+        if chain.iter().any(|id| id == &parent) {
+            let mut loop_chain = chain.clone();
+            loop_chain.push(parent);
+            return Err(AdoptProblem::CircularInheritance { chain: loop_chain });
+        }
+        validate_version_id(&parent)?;
+        let required_by = chain.last().cloned().unwrap_or_default();
+        let parent_dir = game.version_dir(&parent);
+        let parent_path = game.version_json(&parent);
+        // 父版本同样先过边界（越界就不读），再判存在。
+        if let Some(problem) = ensure_inside(&parent_dir, root) {
+            return Err(problem);
+        }
+        if !parent_path.is_file() {
+            return Err(AdoptProblem::MissingParent {
+                parent,
+                required_by,
+            });
+        }
+        if let Some(problem) = ensure_inside(&parent_path, root) {
+            return Err(problem);
+        }
+        let parent_manifest = read_manifest(&parent_path)?;
+        match parent_manifest.id.as_deref() {
+            None => return Err(AdoptProblem::ManifestMissingId { path: parent_path }),
+            Some(id) if id != parent => {
+                return Err(AdoptProblem::ManifestIdMismatch {
+                    path: parent_path,
+                    manifest_id: id.to_owned(),
+                    directory_id: parent,
+                })
+            }
+            Some(_) => {}
+        }
+        chain.push(parent);
+        current = parent_manifest;
+    }
+    Ok(chain)
+}
+
+/// 用 `core::game::resolve` 判一次继承链（权威结论；失败就如实报，不猜）。
+fn resolve_verdict(game: &GameLayout, manifest_path: &Path) -> Option<AdoptProblem> {
+    let manifest = read_manifest(manifest_path).ok()?;
+    let source = |id: &str| -> Option<VersionJson> {
+        let bytes = std::fs::read(game.version_json(id)).ok()?;
+        VersionJson::from_json_slice(&bytes).ok()
+    };
+    match inherit::resolve(&source, &manifest) {
+        Ok(_) => None,
+        Err(error) => Some(AdoptProblem::InheritanceInvalid {
+            detail: error.to_string(),
+        }),
+    }
+}
+
+/// 读一份清单（错误带路径与 serde 的行列号）。
+fn read_manifest(path: &Path) -> Result<VersionJson, AdoptProblem> {
+    let bytes = std::fs::read(path).map_err(|error| AdoptProblem::ManifestUnreadable {
+        path: path.to_path_buf(),
+        message: error.to_string(),
+    })?;
+    VersionJson::from_json_slice(&bytes).map_err(|error| match error {
+        GameError::Json { source, .. } => AdoptProblem::ManifestInvalidJson {
+            path: path.to_path_buf(),
+            message: source.to_string(),
+        },
+        other => AdoptProblem::ManifestInvalidJson {
+            path: path.to_path_buf(),
+            message: other.to_string(),
+        },
+    })
+}
+
+/// 绑定这个版本 id 的全部实例档案。
+fn registered_for(profiles: &ProfileList, version_id: &str) -> Vec<RegisteredInstance> {
+    profiles
+        .profiles
+        .iter()
+        .filter(|profile| profile.version_id == version_id)
+        .map(|profile| RegisteredInstance {
+            id: profile.id.as_str().to_owned(),
+            name: profile.name.clone(),
+        })
+        .collect()
+}
+
+/// 非 UTF-8 目录名：当成一条不可登记的候选（丢掉它就等于「静默少一行」）。
+fn unreadable_id_candidate(path: &Path, versions_dir: &Path) -> AdoptCandidate {
+    let shown = path
+        .strip_prefix(versions_dir)
+        .unwrap_or(path)
+        .to_string_lossy()
+        .into_owned();
+    AdoptCandidate {
+        version_id: shown,
+        version_dir: path.to_path_buf(),
+        manifest_path: path.to_path_buf(),
+        jar_present: false,
+        manifest_id: None,
+        inherits: Vec::new(),
+        registered: Vec::new(),
+        problems: vec![AdoptProblem::DirectoryUnreadable {
+            path: path.to_path_buf(),
+            message: "目录名不是合法 UTF-8，不能作为版本 id".to_owned(),
+        }],
+    }
+}
+
+/// 断链符号链接：`versions/` 里有这个条目，但指不到任何东西。
+fn broken_link_candidate(version_id: &str, path: &Path) -> AdoptCandidate {
+    AdoptCandidate {
+        version_id: version_id.to_owned(),
+        version_dir: path.to_path_buf(),
+        manifest_path: path.to_path_buf(),
+        jar_present: false,
+        manifest_id: None,
+        inherits: Vec::new(),
+        registered: Vec::new(),
+        problems: vec![AdoptProblem::SymlinkUnresolvable {
+            path: path.to_path_buf(),
+            message: "符号链接的目标不存在（断链）".to_owned(),
+        }],
+    }
+}
+
+/// 沿祖先找**最近的已存在入口**（自身优先；一路到盘根都没有 ⇒ `None`）。
+///
+/// 用途：`read_dir` 的 `NotFound` 不代表「这个数据根是空的」——断链可能发生在更高的祖先上
+/// （迁移联接的目标被搬走时，`versions` 和游戏根都 NotFound，但入口还在）。判据是**存在性**
+/// （`symlink_metadata`，不跟随），能不能解析由调用方另行判定。
+fn nearest_existing_entry(path: &Path) -> Option<PathBuf> {
+    let mut probe = path.to_path_buf();
+    loop {
+        if std::fs::symlink_metadata(&probe).is_ok() {
+            return Some(probe);
+        }
+        if !probe.pop() {
+            return None;
+        }
+    }
+}

crates/core/src/game/adopt/paths.rs

@@ -0,0 +1,84 @@
+//! 路径判据：版本 id 能不能当路径用、已有条目是不是跑出了游戏根（符号链接 / 目录联接 / 祖先链接）。
+//!
+//! 两条判据都与「登记只读」直接相关：id 不可信 ⇒ `versions/<id>/` 可能落到别人的目录上；
+//! 越界 ⇒ 我们以为在游戏根里的东西其实在外面（读它就等于读别的启动器的数据）。
+//! 判据写成纯函数，好在这一层单独变异。
+
+use std::path::{Path, PathBuf};
+
+use super::super::layout::GameLayout;
+use super::candidate::AdoptProblem;
+
+/// 游戏根的「真实」形式（符号链接越界判据的比较基准）。
+///
+/// 拿不到（根还不存在 / 无权限）时退回原始路径：那种情况下不会有已存在的符号链接能通过元数据检查，
+/// 越界判据仍能给出「不在根内」的结论，而不是静默放行。
+pub(super) fn root_of(game: &GameLayout) -> PathBuf {
+    game.root()
+        .canonicalize()
+        .unwrap_or_else(|_| game.root().to_path_buf())
+}
+
+/// 边界判据：**已存在**的路径，其真实（解析符号链接/目录联接之后）位置必须在游戏根内。
+///
+/// 为什么不是 `is_symlink` 一刀切：
+/// - `is_symlink` 看不到 Windows 的**目录联接（junction）**和大部分重解析点——而 junction 不需要
+///   管理员权限就能建，正是「把别人的版本目录挂进来」最容易的形态；
+/// - 祖先链接同样要算：`versions/` 本身是 junction 时，每个 `versions/<id>` 都解析到根外，
+///   单看 `<id>` 这一层还是普通目录。
+///
+/// 所以这里一律 `canonicalize` 后与**真实游戏根**做前缀比较：根内的链接照旧放行（合法的省盘做法），
+/// 根外的一律给出 [`AdoptProblem::OutsideGameRoot`]。路径不存在 ⇒ `None`（存在性由调用方的
+/// 「清单缺失」判据负责，别把「还没装」说成「越界」）。
+///
+/// **已知边界**：判据是「检查那一刻」的快照，检查与读取之间若有人把目录换成链接（TOCTOU），
+/// 本函数看不到——本模块不是并发/对抗入口，不做跨进程锁。
+pub(super) fn ensure_inside(path: &Path, root: &Path) -> Option<AdoptProblem> {
+    if std::fs::symlink_metadata(path).is_err() {
+        return None;
+    }
+    match path.canonicalize() {
+        Ok(target) if target.starts_with(root) => None,
+        Ok(target) => Some(AdoptProblem::OutsideGameRoot {
+            path: path.to_path_buf(),
+            target,
+            root: root.to_path_buf(),
+        }),
+        Err(error) => Some(AdoptProblem::SymlinkUnresolvable {
+            path: path.to_path_buf(),
+            message: error.to_string(),
+        }),
+    }
+}
+
+/// 版本 id 的路径安全判据（空 / 分隔符 / 盘符 / NUL / 结尾点号空格都拒绝）。
+///
+/// 结尾的点号与空格必须拒绝：Win32 会在建目录时把它们**静默剥掉**，于是
+/// `versions/1.20.1.` 与 `versions/1.20.1` 会落到同一个目录上——两个「不同 id」指向一份文件。
+pub(super) fn validate_version_id(version_id: &str) -> Result<(), AdoptProblem> {
+    let invalid = |reason: &'static str| {
+        Err(AdoptProblem::VersionIdInvalid {
+            version_id: version_id.to_owned(),
+            reason,
+        })
+    };
+    if version_id.trim().is_empty() {
+        return invalid("为空");
+    }
+    if version_id.contains('/') || version_id.contains('\\') {
+        return invalid("含路径分隔符");
+    }
+    if version_id.contains(':') {
+        return invalid("含冒号（盘符 / NTFS 数据流）");
+    }
+    if version_id.contains('\0') || version_id.chars().any(|ch| ch.is_control()) {
+        return invalid("含控制字符");
+    }
+    if version_id == "." || version_id == ".." {
+        return invalid("是相对路径标记");
+    }
+    if version_id.ends_with('.') || version_id.ends_with(' ') {
+        return invalid("以点号或空格结尾（Win32 会剥掉，落到别的目录上）");
+    }
+    Ok(())
+}

crates/core/src/game/adopt/plan.rs

@@ -0,0 +1,287 @@
+//! 落点计算与真正的登记：`plan`（纯算 + 零写盘）与 `adopt`（plan + 只写自己的两份配置）。
+//!
+//! # 写盘面（全部在 ULL 数据根下，游戏根一个字节都不动）
+//!
+//! 1. `config/instances/<id>.json`（实例设置：隔离档 + 运行目录）；
+//! 2. `config/profiles.json`（档案列表）；
+//! 3. 选了缺省运行目录时，`<data>/instances/<实例目录名>` 这个空目录（已存在且非空 ⇒ 拒绝；
+//!    路径上的已有祖先若解析到**数据根之外**（符号链接/目录联接）⇒ 拒绝，不沿它写盘；
+//!    已被**别的实例**占着 ⇒ 顺延 `-2`/`-3` 后缀，绝不让两个实例共用同一个运行目录）。
+//!
+//! 写配置**之前**还要核一遍真实写面（`config/`、`config/instances/`、`profiles.json` 必须在
+//! 写盘面判据见 [`fspaths`]（配置必须在 `<.ULL>` 内、默认写盘面不得与游戏树重叠）。
+//!
+//! `versions/` `libraries/` `assets/` **一个字节都不写**：登记只填 `version_id`，内容靠 D20 的
+//! 「恒共享层」被启动/下载链路复用（[`crate::game::isolation::SHARED_LAYERS`]）。
+
+use std::path::{Path, PathBuf};
+
+use super::super::install::instance::{read_profiles, register_with, InstanceSettings, Isolation};
+use super::super::layout::GameLayout;
+use super::super::profiles::ProfileList;
+use super::candidate::{AdoptCandidate, AdoptTarget};
+use super::error::AdoptError;
+use super::fspaths;
+use super::inspect::inspect;
+use super::run_dir;
+use crate::platform::layout::LauncherLayout;
+
+/// 一次登记请求（CLI / presenter 的输入形状）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdoptRequest {
+    /// 要接进来的版本 id（= `versions/<id>/`）。
+    pub version_id: String,
+    /// 展示名；缺省 = 版本 id。
+    pub name: Option<String>,
+    /// 运行目录选择（缺省 [`AdoptTarget::InstanceDir`]，**不是** `isolated`）。
+    pub target: AdoptTarget,
+    /// 档案的创建时间（RFC-3339；core 不碰时钟格式，由调用方给）。
+    pub created_at: Option<String>,
+}
+
+impl AdoptRequest {
+    /// 最小请求（缺省名 + 缺省运行目录）。
+    #[must_use]
+    pub fn new(version_id: impl Into<String>) -> Self {
+        Self {
+            version_id: version_id.into(),
+            name: None,
+            target: AdoptTarget::default(),
+            created_at: None,
+        }
+    }
+}
+
+/// 一次登记的**计划**（不写任何东西；`--dry-run` / GUI 预检就吃这个）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdoptPlan {
+    /// 检查过的候选（含问题清单，正常时为空）。
+    pub candidate: AdoptCandidate,
+    /// 将写进档案的展示名。
+    pub name: String,
+    /// 运行目录选择。
+    pub target: AdoptTarget,
+    /// 生效隔离档。
+    pub isolation: Isolation,
+    /// 生效运行目录（= `--gameDir`）。
+    pub run_dir: PathBuf,
+    /// 人读提示（共享/版本目录的后果、已有同版本实例…）。
+    pub notes: Vec<String>,
+}
+
+/// 一次登记的结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdoptOutcome {
+    /// 实例 id（稳定 UUID）。
+    pub instance_id: String,
+    /// 展示名。
+    pub name: String,
+    /// 绑定的版本 id。
+    pub version_id: String,
+    /// 实例设置文件路径。
+    pub config_path: PathBuf,
+    /// 生效隔离档。
+    pub isolation: Isolation,
+    /// 运行目录选择。
+    pub target: AdoptTarget,
+    /// 生效运行目录。
+    pub run_dir: PathBuf,
+    /// 是否新建了档案（`false` 只可能是复用同名同版本档案，本命令会先拒绝那种情况）。
+    pub created: bool,
+    /// 是否新建了缺省运行目录（`false` = 目录已存在但为空、直接复用）。
+    pub dir_created: bool,
+    /// 人读提示（与 [`AdoptPlan::notes`] 同一份）。
+    pub notes: Vec<String>,
+}
+
+/// 计算一次登记：检查候选 + 解析名字 + 查重名 + 算运行目录。**零写盘**。
+///
+/// # Errors
+///
+/// - [`AdoptError::UnknownVersion`]：版本不在盘上；
+/// - [`AdoptError::NotAdoptable`]：候选有问题（清单坏/缺父/环/越界…，原因逐条给出；由
+///   [`inspect`] 判出来）；
+/// - [`AdoptError::DuplicateName`] / [`AdoptError::AlreadyRegistered`]：名字冲突 / 重复登记；
+/// - [`AdoptError::TargetNotEmpty`] / [`AdoptError::TargetInvalid`]：运行目录不可用；
+/// - [`AdoptError::Game`]：`profiles.json` 读不了。
+pub fn plan(
+    game: &GameLayout,
+    launcher: &LauncherLayout,
+    request: &AdoptRequest,
+) -> Result<AdoptPlan, AdoptError> {
+    // 写盘面两道判据都放在 `inspect` 之前（dry-run 也要报，别让预检说「可以」）：
+    // ① 默认写盘面不得与**受保护游戏树**重叠（r2 R2.2；整体迁移到游戏树外照旧允许）；
+    // ② 配置落点必须在 `<.ULL>` 内（r1 R2）。
+    // 放前面是有意的——检查候选的读盘也会穿过 `config/`（`profiles.json`），写面不可信时先停手。
+    fspaths::ensure_surfaces_clear_of_game_tree(game, launcher, None)?;
+    fspaths::ensure_config_write_surface(launcher)?;
+    // `inspect` 只在候选**可登记**时返回 `Ok`，不合格一律是 `NotAdoptable`（问题清单已带出）。
+    let candidate = inspect(game, launcher, &request.version_id)?;
+    let name = resolve_name(request.name.as_deref(), &candidate.version_id);
+    let profiles = read_profiles(launcher)?;
+    let mut notes = Vec::new();
+    // 重名与重复登记：**显式报错**，不静默复用（复用会把用户「导入这个」的意图改成「改一个别的实例」）。
+    if let Some(existing) = profiles
+        .profiles
+        .iter()
+        .find(|profile| profile.name == name)
+    {
+        if existing.version_id == candidate.version_id {
+            return Err(AdoptError::AlreadyRegistered {
+                version_id: candidate.version_id.clone(),
+                name,
+                instance_id: existing.id.as_str().to_owned(),
+            });
+        }
+        return Err(AdoptError::DuplicateName {
+            name,
+            instance_id: existing.id.as_str().to_owned(),
+        });
+    }
+    for profile in &candidate.registered {
+        notes.push(format!(
+            "这个版本已经有实例了：`{}`（id {}）——再登记会得到第二个实例，两个实例共用同一份版本文件",
+            profile.name, profile.id
+        ));
+    }
+
+    let (run_dir, bump_notes) = run_dir_of(
+        game,
+        launcher,
+        &candidate.version_id,
+        &name,
+        &request.target,
+        &profiles,
+    )?;
+    notes.extend(bump_notes);
+    // 缺省运行目录也要落在游戏树之外（`shared`/`version_dir`/`custom` 是显式选择，不复检）。
+    if request.target == AdoptTarget::InstanceDir {
+        fspaths::ensure_surfaces_clear_of_game_tree(game, launcher, Some(&run_dir))?;
+    }
+    notes.extend(target_notes(&request.target, &run_dir));
+
+    Ok(AdoptPlan {
+        candidate,
+        name,
+        target: request.target.clone(),
+        isolation: request.target.isolation(),
+        run_dir,
+        notes,
+    })
+}
+
+/// 按计划登记：先准备缺省运行目录（若选了它），再写实例设置与档案。
+///
+/// # Errors
+///
+/// 同 [`plan`]，外加建目录/写配置失败（[`AdoptError::Game`]）。
+pub fn adopt(
+    game: &GameLayout,
+    launcher: &LauncherLayout,
+    request: &AdoptRequest,
+) -> Result<AdoptOutcome, AdoptError> {
+    let plan = plan(game, launcher, request)?;
+    // `plan` 已核过；写盘前再核一次（中间可能有别人动过树），失败就一个字节都不写。
+    fspaths::ensure_surfaces_clear_of_game_tree(game, launcher, None)?;
+    if plan.target == AdoptTarget::InstanceDir {
+        fspaths::ensure_surfaces_clear_of_game_tree(game, launcher, Some(&plan.run_dir))?;
+    }
+    fspaths::ensure_config_write_surface(launcher)?;
+    let mut dir_created = false;
+    // 目录先建：建不出来就一个配置都不写（失败的残留是一个空目录，可复用）。
+    if plan.target == AdoptTarget::InstanceDir && !plan.run_dir.is_dir() {
+        run_dir::ensure_inside_data(launcher, &plan.run_dir)?;
+        std::fs::create_dir_all(&plan.run_dir)
+            .map_err(|error| AdoptError::Game(crate::game::GameError::io(&plan.run_dir, error)))?;
+        dir_created = true;
+        // 建完再核一次：`create_dir_all` 会沿已存在的目录联接走，越过边界就不算成功。
+        run_dir::ensure_inside_data(launcher, &plan.run_dir)?;
+    }
+    let settings = InstanceSettings {
+        isolation: Some(plan.isolation),
+        game_dir: match &plan.target {
+            // `custom` 档必须有运行目录：缺省目录与用户目录都要落进 `gameDir`。
+            AdoptTarget::InstanceDir | AdoptTarget::Custom(_) => Some(plan.run_dir.clone()),
+            AdoptTarget::Shared | AdoptTarget::VersionDir => None,
+        },
+    };
+    let registration = register_with(
+        launcher,
+        &plan.name,
+        &plan.candidate.version_id,
+        request.created_at.as_deref(),
+        &settings,
+    )?;
+    Ok(AdoptOutcome {
+        instance_id: registration.profile.id.as_str().to_owned(),
+        name: registration.profile.name.clone(),
+        version_id: registration.profile.version_id.clone(),
+        config_path: registration.config_path,
+        isolation: plan.isolation,
+        target: plan.target,
+        run_dir: plan.run_dir,
+        created: registration.created,
+        dir_created,
+        notes: plan.notes,
+    })
+}
+
+/// 运行目录的派生（缺省落点复用整合包导入的 `<data>/instances/<实例目录名>`）。
+///
+/// 缺省档**必须**查「已有实例占着哪个真实目录」（R1）：slug 与大小写不敏感都会让两个不同展示名
+/// 落到同一个物理目录上；撞上就顺延后缀（见 [`run_dir::derive_instance_dir`]），而不是让两个
+/// 实例悄悄共用一个运行目录。返回（目录，顺延提示）。
+fn run_dir_of(
+    game: &GameLayout,
+    launcher: &LauncherLayout,
+    version_id: &str,
+    name: &str,
+    target: &AdoptTarget,
+    profiles: &ProfileList,
+) -> Result<(PathBuf, Vec<String>), AdoptError> {
+    match target {
+        AdoptTarget::InstanceDir => {
+            let claims = run_dir::claims(launcher, profiles)?;
+            run_dir::derive_instance_dir(launcher, name, &claims)
+        }
+        AdoptTarget::Shared => Ok((game.root().to_path_buf(), Vec::new())),
+        AdoptTarget::VersionDir => Ok((game.version_dir(version_id), Vec::new())),
+        AdoptTarget::Custom(dir) => Ok((run_dir::resolve_custom_dir(dir)?, Vec::new())),
+    }
+}
+
+/// 运行目录选择的后果说明（人读；CLI 与 GUI 共用同一份话术）。
+///
+/// `shared` / `version_dir` 必须**明确告知**：它们会把玩家数据写进别人的 `.minecraft`
+/// （D20 的 `isolated` 档运行目录就是 `versions/<id>/`）。
+#[must_use]
+pub fn target_notes(target: &AdoptTarget, run_dir: &Path) -> Vec<String> {
+    match target {
+        AdoptTarget::InstanceDir => vec![format!(
+            "运行目录 = {}（ULL 数据区新建，与别人的 .minecraft 隔离；versions/libraries/assets 仍按 D20 恒共享，不复制）",
+            run_dir.display()
+        )],
+        AdoptTarget::Shared => vec![format!(
+            "运行目录 = 游戏根 {}（共享档）：mods/saves/config 会落在别人的 .minecraft 里，与其它启动器共用；\
+             要隔离请用缺省（ULL 数据区新目录）或 --isolation custom --game-dir <dir>",
+            run_dir.display()
+        )],
+        AdoptTarget::VersionDir => vec![format!(
+            "运行目录 = 版本目录 {}（版本隔离档）：第一次启动会在这里新增 mods/saves/config/logs，\
+             而这个目录是别的启动器的版本目录（不覆盖已有文件）；要隔离请用缺省或 --isolation custom",
+            run_dir.display()
+        )],
+        AdoptTarget::Custom(_) => vec![format!(
+            "运行目录 = {}（用户指定；不新建、不改动其中已有内容）",
+            run_dir.display()
+        )],
+    }
+}
+
+/// 展示名：去空格，空串退回版本 id（与 `pack import` 的「名字不给就用包名」同一口径）。
+fn resolve_name(name: Option<&str>, version_id: &str) -> String {
+    name.map(str::trim)
+        .filter(|name| !name.is_empty())
+        .map(str::to_string)
+        .unwrap_or_else(|| version_id.to_owned())
+}

crates/core/src/game/adopt/run_dir.rs

@@ -0,0 +1,217 @@
+//! 运行目录与**写盘边界**：缺省目录派生（含碰撞消歧）+ 数据区/配置写面的真实路径判据。
+//!
+//! # 两条铁律（都来自复审 r1 的实测缺陷）
+//!
+//! 1. **两个实例不许悄悄共用同一个运行目录**（R1）：展示名不重复不代表派生目录不重复
+//!    （`Better MC` 与 `Better-MC` 经 slug 同名；Windows 上 `Foo` 与 `foo` 是同一个目录）。
+//!    所以「目录是空的」**不足以**判可复用——还要看**已有实例已经占着哪个真实目录**；
+//!    撞上了就顺延到 `<base>-2`、`<base>-3`…（原因写进 notes），而不是让两个实例共用一个。
+//! 2. **只写 ULL 自己的配置**：配置写面与「默认写盘面不得与受保护游戏树重叠」两条判据在
+//!    [`super::fspaths`]（`ensure_config_write_surface` / `ensure_surfaces_clear_of_game_tree`），
+//!    本模块只负责**运行目录派生**与「缺省目录必须落在数据区」这一条。
+//!
+//! # 判据的基准（为什么不拿 `<data>/instances` 或 `<.ULL>/config` 当基准）
+//!
+//! 被保护的**边界自己是链接**时，拿它当基准等于把越界当正常。所以基准一律是**解析后的父级**：
+//! 数据写面看 `<data>`，配置写面看 `<.ULL>`、并额外排除游戏根。用户把整棵树迁到别的盘
+//! （`<.ULL>` 或 `<data>` 本身是联接/符号链接）仍然允许——判据是落点，不是路径长得像不像。
+//!
+//! # 已知边界
+//!
+//! 判据是「检查那一刻」的快照：检查与 `create_dir_all`/写盘之间被人换掉组件（TOCTOU）看不到。
+//! 本命令不是并发/对抗入口，不做跨进程锁。
+
+use std::path::{Path, PathBuf};
+
+use super::super::install::instance::read_instance_config;
+use super::super::install::pack_dir;
+use super::super::profiles::ProfileList;
+use super::error::AdoptError;
+use super::fspaths;
+use crate::platform::layout::LauncherLayout;
+
+/// 派生目录撞车时最多顺延多少个后缀（`-2` … `-33`）。撞满即报错，不无限找。
+const MAX_SUFFIX: u32 = 32;
+
+/// 一个「已有实例已经占着的运行目录」。
+///
+/// 只收 `gameDir`（现役设置文件里的，或 M27 前档案的遗留 `game_dir`）：`shared` / `isolated`
+/// 档的运行目录是**派生**的（游戏根 / `versions/<id>`），与缺省落点 `<data>/instances/<名>`
+/// 不可能相等，收进来只会制造噪音。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) struct RunDirClaim {
+    /// 占着这个目录的实例 id。
+    pub(super) instance_id: String,
+    /// 实例展示名（写进提示给人看）。
+    pub(super) name: String,
+    /// 声明/绑定的运行目录（原样，未真实化）。
+    pub(super) dir: PathBuf,
+    /// 比较用的键（真实化路径 + 大小写归一，见 [`dir_key`]）。
+    pub(super) key: String,
+}
+
+/// 收集现有实例占着的运行目录（读 `config/instances/<id>.json`；读不了就是错误，不猜）。
+///
+/// # Errors
+///
+/// 实例设置文件读不出来 / JSON 坏：`AdoptError::Game`。
+pub(super) fn claims(
+    launcher: &LauncherLayout,
+    profiles: &ProfileList,
+) -> Result<Vec<RunDirClaim>, AdoptError> {
+    let mut out = Vec::new();
+    for profile in &profiles.profiles {
+        let config = read_instance_config(launcher, profile.id.as_str())?;
+        let dir = config
+            .and_then(|config| config.game_dir)
+            .or_else(|| profile.game_dir.clone());
+        let Some(dir) = dir.filter(|dir| !dir.as_os_str().is_empty()) else {
+            continue;
+        };
+        out.push(RunDirClaim {
+            instance_id: profile.id.as_str().to_owned(),
+            name: profile.name.clone(),
+            key: dir_key(&dir),
+            dir,
+        });
+    }
+    Ok(out)
+}
+
+/// 缺省运行目录：`<data>/instances/<实例目录名>`，撞车/占用时顺延后缀。
+///
+/// 判据顺序（三条都要过）：
+/// 1. 路径上的已有祖先解析后必须仍在数据根内（[`ensure_inside_data`]）；
+/// 2. **不能**是已有实例占着的目录（按真实路径比较，[`dir_key`]）——撞上就顺延；
+/// 3. 目录必须不存在或为空（非空且无人认领 = 用户数据，拒绝而不是换目录）。
+///
+/// 返回派生目录 + 人读提示（顺延过就有一条，没顺延就是空）。
+///
+/// # Errors
+///
+/// 数据区越界（`TargetInvalid`）、非空目录（`TargetNotEmpty`）、后缀撞满（`NoFreeRunDir`）、
+/// 读实例设置失败（`Game`）。
+pub(super) fn derive_instance_dir(
+    launcher: &LauncherLayout,
+    name: &str,
+    claims: &[RunDirClaim],
+) -> Result<(PathBuf, Vec<String>), AdoptError> {
+    let base = pack_dir::instance_dir(launcher, name);
+    let mut bumped: Vec<RunDirClaim> = Vec::new();
+    let mut attempt = base.clone();
+    let mut suffix = 1;
+    loop {
+        ensure_inside_data(launcher, &attempt)?;
+        let key = dir_key(&attempt);
+        match claims.iter().find(|claim| claim.key == key) {
+            Some(claim) => {
+                bumped.push(claim.clone());
+                suffix += 1;
+                if suffix > MAX_SUFFIX {
+                    return Err(AdoptError::NoFreeRunDir { base });
+                }
+                attempt = with_suffix(&base, suffix);
+            }
+            None if directory_occupied(&attempt) => {
+                // 非空且没有实例认领 ⇒ 用户自己的数据：不覆盖，也不偷偷换个目录把它晾在一边。
+                return Err(AdoptError::TargetNotEmpty { path: attempt });
+            }
+            None => {
+                let mut notes = Vec::new();
+                if let Some(claim) = bumped.first() {
+                    notes.push(format!(
+                        "派生目录 {} 与已有实例 `{}`（id {}）的运行目录 {} 是同一个物理目录，\
+                         已改用 {} —— 两个实例不会共用同一个运行目录",
+                        base.display(),
+                        claim.name,
+                        claim.instance_id,
+                        claim.dir.display(),
+                        attempt.display()
+                    ));
+                }
+                return Ok((attempt, notes));
+            }
+        }
+    }
+}
+
+/// `<base>-2` / `<base>-3` …（只动最后一段）。
+fn with_suffix(base: &Path, suffix: u32) -> PathBuf {
+    let name = base
+        .file_name()
+        .map(|name| name.to_string_lossy().into_owned())
+        .unwrap_or_default();
+    base.with_file_name(format!("{name}-{suffix}"))
+}
+
+/// 缺省运行目录必须**真的**落在启动器数据根之下。
+///
+/// 边界是 `<data>`（`<root>/.ULL/data`）而不是 `<data>/instances`：后者本身可能就是链接，
+/// 拿它当基准等于把「越界」当成「正常」。
+///
+/// # Errors
+///
+/// 解析后跑出数据根（`TargetInvalid`）。
+pub(super) fn ensure_inside_data(launcher: &LauncherLayout, dir: &Path) -> Result<(), AdoptError> {
+    let Some(data_real) = fspaths::existing_real(&launcher.data()) else {
+        // 连数据根都还不存在 ⇒ 不可能已经有指向外面的链接。
+        return Ok(());
+    };
+    if let Some(dir_real) = fspaths::existing_real(dir) {
+        if !dir_real.starts_with(&data_real) {
+            return Err(AdoptError::TargetInvalid {
+                detail: format!(
+                    "运行目录 {} 解析到 {}，落在数据根 {} 之外：数据区里有指向外部的符号链接/目录联接，拒绝沿它写盘",
+                    dir.display(),
+                    dir_real.display(),
+                    data_real.display()
+                ),
+            });
+        }
+    }
+    Ok(())
+}
+
+/// `custom` 运行目录的用法判据（绝对路径 / 非空）。
+///
+/// # Errors
+///
+/// 相对路径或空路径：`TargetInvalid`。
+pub(super) fn resolve_custom_dir(dir: &Path) -> Result<PathBuf, AdoptError> {
+    if dir.as_os_str().is_empty() {
+        return Err(AdoptError::TargetInvalid {
+            detail: "运行目录为空".to_owned(),
+        });
+    }
+    if !dir.is_absolute() {
+        return Err(AdoptError::TargetInvalid {
+            detail: format!("--game-dir 需要绝对路径，收到 `{}`", dir.display()),
+        });
+    }
+    Ok(dir.to_path_buf())
+}
+
+/// 目录是否「有人在用」（存在且非空）。空目录是上次失败的残留，可复用。
+pub(super) fn directory_occupied(path: &Path) -> bool {
+    std::fs::read_dir(path).is_ok_and(|mut entries| entries.next().is_some())
+}
+
+/// **比较用**的真实路径键：真实化 + 平台别名归一（Win32 尾点/尾空格，见 [`fspaths`]）+ 大小写归一。
+///
+/// 大小写归一只在大小写不敏感的平台做（Windows / 默认 macOS）：`Foo` 与 `foo` 是同一个目录，
+/// 不归一会让「两个实例共用目录」这一条在 Windows 上漏掉（复审 r1 的实测之一）。
+/// **Windows 上还要折叠尾点/尾空格**（`Foo.` / `Foo ` 都是 `Foo`）——否则「尚不存在的认领目录」
+/// 会从这条缝里绕过碰撞判定（复审 r2 的 R2.1）。verbatim 路径（`\?\…`）不折叠，交给平台语义。
+///
+/// **策略是保守的**：macOS 也可能是大小写敏感的 APFS 卷，那时 `Foo` 与 `foo` 本来是**不同**目录，
+/// 归一后会判成碰撞 ⇒ 顺延 `-2`。代价是目录名可能多一个后缀，换来的是「绝不共用」这条不变量
+/// 在任何卷上都成立（判错的方向只能是「多一次顺延」，不能是「共用一个目录」）。
+///
+/// **目标可能还不存在**：这里不要求路径存在（[`fspaths::comparison_real`] 会拼回尚不存在的尾段），
+/// 因为「实例已经认领了、但目录还没被创建」（`custom` 档就是这种）同样必须参与比较。
+fn dir_key(path: &Path) -> String {
+    match fspaths::comparison_real(path) {
+        Some(real) => fspaths::normalize_key(&real),
+        None => fspaths::normalize_key(path),
+    }
+}

crates/core/src/game/install/instance.rs

@@ -16,7 +16,8 @@
 //! # 幂等
 //!
 //! 同一版本重复 `install`：按 `version_id` + 展示名复用已有档案，返回 `created = false`，
-//! 不产生第二个实例、不改已有实例的 id（id 一旦写进档案就是稳定的）。
+//! 不产生第二个实例、不改已有实例的 id（id 一旦写进档案就是稳定的）。登记本身（含
+//! [`InstanceSettings`] 与 `register_with`）在同目录的 `register` 子模块里。
 
 use std::collections::BTreeMap;
 use std::path::PathBuf;
@@ -26,10 +27,14 @@ use serde::{Deserialize, Serialize};
 use super::super::error::GameError;
 use super::super::isolation::{IsolationMode, ModeChange, ModeChangeWarning};
 use super::super::launch_overrides::LaunchOverrides;
-use super::super::profiles::{InstanceProfile, ProfileList};
+use super::super::profiles::ProfileList;
 use crate::platform::atomic::write_atomic;
 use crate::platform::layout::LauncherLayout;
 
+mod register;
+
+pub use register::{register, register_with, InstanceSettings, Registration};
+
 /// 每实例设置文件的 schema 版本。
 ///
 /// 与 `setting::instance_keys::instance_version` 的 minor 对应：D20 加了 `lastModeChange`，
@@ -215,71 +220,6 @@ impl InstanceConfig {
     }
 }
 
-/// 一次登记的结果。
-#[derive(Debug, Clone)]
-pub struct Registration {
-    /// 档案（新建或复用）。
-    pub profile: InstanceProfile,
-    /// 每实例设置文件路径。
-    pub config_path: PathBuf,
-    /// 是否新建（`false` = 已有同版本同名的实例，直接复用）。
-    pub created: bool,
-}
-
-/// 登记一个实例（幂等）。
-///
-/// 行为：
-/// 1. 已有"同 `version_id` + 同展示名"的档案 → 复用（`created = false`），只补写缺失的设置文件；
-/// 2. 否则新建档案（稳定 UUID）→ 写 `profiles.json` → 写 `config/instances/<id>.json`。
-///
-/// `created_at` 由调用方给（core::game 不碰时钟格式；CLI 用 `launch::time` 的 RFC3339）。
-///
-/// # Errors
-///
-/// 读/写 `profiles.json`、实例 id 不合法、原子写失败。
-pub fn register(
-    layout: &LauncherLayout,
-    name: &str,
-    version_id: &str,
-    created_at: Option<&str>,
-) -> Result<Registration, GameError> {
-    let mut profiles = read_profiles(layout)?;
-    let existing = profiles
-        .profiles
-        .iter()
-        .find(|profile| profile.version_id == version_id && profile.name == name)
-        .cloned();
-
-    if let Some(profile) = existing {
-        let config_path = instance_config_path(layout, profile.id.as_str())?;
-        // 老档案可能还没有设置文件（早期 CLI 只写 profiles.json），这里补齐。
-        if !config_path.is_file() {
-            write_instance_config(
-                layout,
-                &InstanceConfig::new(profile.id.as_str(), version_id),
-            )?;
-        }
-        return Ok(Registration {
-            profile,
-            config_path,
-            created: false,
-        });
-    }
-
-    let mut profile = InstanceProfile::new(name, version_id);
-    profile.created_at = created_at.map(str::to_string);
-    let id = profile.id.as_str().to_string();
-    profiles.upsert(profile.clone());
-    write_profiles(layout, &profiles)?;
-
-    let config_path = write_instance_config(layout, &InstanceConfig::new(id, version_id))?;
-    Ok(Registration {
-        profile,
-        config_path,
-        created: true,
-    })
-}
-
 /// 读实例清单（文件缺失 = 空列表，不算错误）。
 ///
 /// # Errors

crates/core/src/game/install/instance/register.rs

@@ -0,0 +1,150 @@
+//! 实例登记：把「用户点了一下导入/安装」变成 `profiles.json` + `config/instances/<id>.json`。
+//!
+//! 从 `install/instance.rs` 搬出来只为守 400 行硬线（M221 的 `register_with` 让那边到 430 行）；
+//! 搬动是纯挪，唯一新增的是 [`InstanceSettings`] 与 [`register_with`]（登记时一并定隔离档/运行目录）。
+//!
+//! # 幂等
+//!
+//! 同一 `version_id` + 同一展示名重复登记：复用已有档案（`created = false`），不产生第二个实例、
+//! 不改已有实例的 id（id 一旦写进档案就是稳定的）。
+//!
+//! # 写盘顺序（M221）
+//!
+//! **先写实例设置、后写档案**。中断时留下的是「没有档案的孤立设置文件」——不可见、下次登记同一 id
+//! 会覆盖；反过来（先档案后设置）会留下一个按全局档启动的实例，而全局缺省是 `isolated`，
+//! 那会把 `mods/saves/config` 造进 `versions/<versionId>/`（登记别人的版本时那正是别人的目录）。
+
+use std::path::PathBuf;
+
+use crate::game::error::GameError;
+use crate::game::profiles::InstanceProfile;
+use crate::platform::layout::LauncherLayout;
+
+use super::{
+    instance_config_path, read_profiles, write_instance_config, write_profiles, InstanceConfig,
+    Isolation,
+};
+
+/// 一次登记的结果。
+#[derive(Debug, Clone)]
+pub struct Registration {
+    /// 档案（新建或复用）。
+    pub profile: InstanceProfile,
+    /// 每实例设置文件路径。
+    pub config_path: PathBuf,
+    /// 是否新建（`false` = 已有同版本同名的实例，直接复用）。
+    pub created: bool,
+}
+
+/// 登记时一并落进 `config/instances/<id>.json` 的初始设置。
+///
+/// 为什么要有它：登记与「运行目录怎么定」原本是两件事，于是调用方只能先 `register` 再补写设置
+/// ——中间那段时间实例是 `inherit`（跟随全局 `isolated`）。把选择前移到登记这一步，就没有那个窗口。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct InstanceSettings {
+    /// 隔离档；`None` = 跟随全局（不落盘）。
+    pub isolation: Option<Isolation>,
+    /// 自定义运行目录（仅 `custom` 档需要）。
+    pub game_dir: Option<PathBuf>,
+}
+
+impl InstanceSettings {
+    /// 跟随全局（= 未引入 [`InstanceSettings`] 前的历史行为，不落任何设置键）。
+    #[must_use]
+    pub fn inherit() -> Self {
+        Self::default()
+    }
+
+    /// 是否什么都没选。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.isolation.is_none() && self.game_dir.is_none()
+    }
+}
+
+/// 登记一个实例（幂等，跟随全局隔离档）。
+///
+/// # Errors
+///
+/// 读/写 `profiles.json`、实例 id 不合法、原子写失败。
+pub fn register(
+    layout: &LauncherLayout,
+    name: &str,
+    version_id: &str,
+    created_at: Option<&str>,
+) -> Result<Registration, GameError> {
+    register_with(
+        layout,
+        name,
+        version_id,
+        created_at,
+        &InstanceSettings::inherit(),
+    )
+}
+
+/// 同 [`register`]，但把隔离档与运行目录**一并**写进新建实例的设置文件。
+///
+/// 复用已有档案（同版本 + 同名）时 `settings` 只在「设置文件缺失、需要补建」时生效——
+/// 已有设置文件绝不改写（那是用户的显式选择，登记不该覆盖它）。
+///
+/// # Errors
+///
+/// 同 [`register`]。
+pub fn register_with(
+    layout: &LauncherLayout,
+    name: &str,
+    version_id: &str,
+    created_at: Option<&str>,
+    settings: &InstanceSettings,
+) -> Result<Registration, GameError> {
+    let mut profiles = read_profiles(layout)?;
+    let existing = profiles
+        .profiles
+        .iter()
+        .find(|profile| profile.version_id == version_id && profile.name == name)
+        .cloned();
+
+    if let Some(profile) = existing {
+        let config_path = instance_config_path(layout, profile.id.as_str())?;
+        // 老档案可能还没有设置文件（早期 CLI 只写 profiles.json），这里补齐。
+        if !config_path.is_file() {
+            let mut config = InstanceConfig::new(profile.id.as_str(), version_id);
+            apply_settings(&mut config, settings);
+            write_instance_config(layout, &config)?;
+        }
+        return Ok(Registration {
+            profile,
+            config_path,
+            created: false,
+        });
+    }
+
+    let mut profile = InstanceProfile::new(name, version_id);
+    profile.created_at = created_at.map(str::to_string);
+    let id = profile.id.as_str().to_string();
+    let mut config = InstanceConfig::new(id, version_id);
+    apply_settings(&mut config, settings);
+    let config_path = write_instance_config(layout, &config)?;
+
+    profiles.upsert(profile.clone());
+    if let Err(error) = write_profiles(layout, &profiles) {
+        // 档案没落盘 ⇒ 撤掉刚写的设置文件，不留半登记状态。
+        let _ = std::fs::remove_file(&config_path);
+        return Err(error);
+    }
+    Ok(Registration {
+        profile,
+        config_path,
+        created: true,
+    })
+}
+
+/// 把登记时的初始设置贴到实例设置上（只动这两个键，其余保持稀疏缺省）。
+fn apply_settings(config: &mut InstanceConfig, settings: &InstanceSettings) {
+    if let Some(isolation) = settings.isolation {
+        config.isolation = Some(isolation);
+    }
+    if settings.game_dir.is_some() {
+        config.game_dir = settings.game_dir.clone();
+    }
+}

crates/core/src/game/mod.rs

@@ -24,9 +24,14 @@
 //! Java 管理（M33，[`java`]）：托管 JDK 的查询/下载/解压/探测（`.ULL/data/java-managed/`）
 //! 与 MC↔Java 映射表。同样只借 `core::download` 的引擎做下载，自己不拼镜像 URL。
 //!
+//! 已铺在盘上的版本接入（M221，[`adopt`]）：扫描/检查 `versions/` 里**别人装的**版本 → 只登记
+//! （`profiles.json` + 实例设置），不搬文件、不写游戏根。缺省运行目录落 ULL 数据区，
+//! 共用/写进对方的 `.minecraft` 必须显式选择（见 [`adopt::AdoptTarget`]）。
+//!
 //! 模块分工按"数据形状 / 纯计算 / 状态"切开，任何模块都不碰网络与 UI：
 //! 下载归 `core::download`、进程归 `core::launch`、配置落盘归 `core::setting`。
 
+pub mod adopt;
 pub mod arguments;
 pub mod capability;
 pub mod error;
@@ -44,6 +49,10 @@ pub mod snapshot;
 pub mod unlisted;
 pub mod version;
 
+pub use adopt::{
+    AdoptCandidate, AdoptError, AdoptOutcome, AdoptPlan, AdoptProblem, AdoptRequest, AdoptScan,
+    AdoptTarget, RegisteredInstance,
+};
 pub use arguments::{rules_allow, Arguments, Environment, ExpandedArguments, Rule, RuleAction};
 pub use capability::{
     is_vulkan_library, library_names_have_vulkan, VersionCapabilities, VULKAN_LIBRARY_ARTIFACT,

crates/core/tests/adopt/collision_cases.rs

@@ -0,0 +1,221 @@
+//! 运行目录**碰撞**：slug 同名 / 大小写不敏感 / 「空目录已被实例占着」/ 「认领目录还不存在」。
+//!
+//! 复审 r1 的 R1：旧实现只比展示名，第二次登记看到「目录是空的」就复用了 ⇒ 两个从未选择
+//! shared/custom 的实例共用一个运行目录（`mods`/`saves` 互相污染）。
+//! 判据必须是「有没有实例占着这个**真实**目录」，而不是「目录空不空」。
+
+use unlucky_core::game::adopt::{self, AdoptTarget};
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::install::pack_dir;
+
+use crate::fixture::{foreign_minecraft, request, TempRoot};
+
+/// **slug 碰撞**：`Better MC` 与 `Better-MC` 派生到同一个目录名 —— 两个实例必须落在不同目录。
+///
+/// 复审 r1 的 R1：旧实现只比展示名，第二次登记看到「目录是空的」就复用了，于是两个从未选择
+/// shared/custom 的实例共用一个运行目录（`mods`/`saves` 互相污染）。
+///
+/// 抓得住：
+/// - 判据只看目录空不空、不看已有实例占没占（两条 `run_dir` 不同的断言会红）；
+/// - 顺延目录没建出来 / 提示里没点出撞的是谁。
+///
+/// 抓不住：`pack_dir::instance_dir_name` 本身把两个名字折成同一个目录（那是既有行为，
+/// 本 mission 不改它，只保证**登记侧**不共用）。
+#[test]
+fn slug_colliding_names_do_not_share_a_run_dir() {
+    let root = TempRoot::new("slug-collide");
+    foreign_minecraft(&root.game_root());
+
+    let mut first = request("1.20.1", AdoptTarget::InstanceDir);
+    first.name = Some("Better MC".to_string());
+    let a = adopt::adopt(&root.game(), &root.launcher(), &first).expect("第一次登记");
+    let mut second = request("1.20.1", AdoptTarget::InstanceDir);
+    second.name = Some("Better-MC".to_string());
+    let b = adopt::adopt(&root.game(), &root.launcher(), &second).expect("第二次登记");
+
+    assert_ne!(a.run_dir, b.run_dir, "两个实例不许共用同一个运行目录");
+    assert!(
+        a.run_dir.is_dir() && b.run_dir.is_dir(),
+        "两个目录都要真实存在"
+    );
+    let bumped = b
+        .run_dir
+        .file_name()
+        .map(|name| name.to_string_lossy().into_owned());
+    assert!(
+        bumped.as_deref().is_some_and(|name| name.ends_with("-2")),
+        "撞车后应顺延成 -2：{:?}",
+        b.run_dir
+    );
+    assert!(
+        b.notes.iter().any(|note| note.contains("同一个物理目录")),
+        "必须把「撞了谁」说出来：{:?}",
+        b.notes
+    );
+
+    // 两份实例设置各自指向自己的目录（不是都指第一个）。
+    let config_a = read_instance_config(&root.launcher(), &a.instance_id)
+        .expect("读设置")
+        .expect("有设置文件");
+    let config_b = read_instance_config(&root.launcher(), &b.instance_id)
+        .expect("读设置")
+        .expect("有设置文件");
+    assert_eq!(config_a.game_dir.as_deref(), Some(a.run_dir.as_path()));
+    assert_eq!(config_b.game_dir.as_deref(), Some(b.run_dir.as_path()));
+}
+
+/// **大小写碰撞**（Windows/macOS）：`Foo` 与 `foo` 是同一个物理目录 ⇒ 同样必须顺延。
+///
+/// 抓得住：`dir_key` 不做大小写归一（Windows 上第二次登记会复用同一个目录）。
+/// 抓不住：Linux（大小写敏感，两条目录本来就不同——那里这条不适用，见 `cfg`）。
+#[cfg(windows)]
+#[test]
+fn names_differing_only_in_case_do_not_share_a_run_dir() {
+    let root = TempRoot::new("case-collide");
+    foreign_minecraft(&root.game_root());
+
+    let mut first = request("1.20.1", AdoptTarget::InstanceDir);
+    first.name = Some("Foo".to_string());
+    let a = adopt::adopt(&root.game(), &root.launcher(), &first).expect("第一次登记");
+    let mut second = request("1.20.1", AdoptTarget::InstanceDir);
+    second.name = Some("foo".to_string());
+    let b = adopt::adopt(&root.game(), &root.launcher(), &second).expect("第二次登记");
+
+    assert_ne!(a.run_dir, b.run_dir, "大小写不同不是「不同目录」的理由");
+    let a_real = a.run_dir.canonicalize().expect("真实路径 A");
+    let b_real = b.run_dir.canonicalize().expect("真实路径 B");
+    assert_ne!(a_real, b_real, "两个运行目录的真实路径必须不同");
+}
+
+/// 空目录**已被别的实例占着** ⇒ 也不能当「失败残留」复用，要顺延。
+///
+/// 这是 R1 的另一半：判据必须是「有没有实例占着」，而不是「目录空不空」。
+///
+/// 抓得住：只按 `directory_occupied` 判（第一次登记建出的空目录会被第二次白白复用）。
+/// 抓不住：目录非空且无人认领的情形（那条保持 `TargetNotEmpty`，见下一条用例）。
+#[test]
+fn an_empty_dir_owned_by_another_instance_is_not_reused() {
+    let root = TempRoot::new("owned-empty");
+    foreign_minecraft(&root.game_root());
+    let mut first = request("1.20.1", AdoptTarget::InstanceDir);
+    first.name = Some("Better MC".to_string());
+    let a = adopt::adopt(&root.game(), &root.launcher(), &first).expect("第一次登记");
+    // 目录此刻是空的（新建、还没启动过游戏）——旧判据会认为「可复用」。
+    let entries_before = std::fs::read_dir(&a.run_dir).expect("读目录").count();
+    assert_eq!(entries_before, 0, "夹具前提：这个目录此刻是空的");
+
+    let mut second = request("1.20.1", AdoptTarget::InstanceDir);
+    second.name = Some("Better-MC".to_string());
+    let b = adopt::adopt(&root.game(), &root.launcher(), &second).expect("第二次登记");
+    assert_ne!(b.run_dir, a.run_dir);
+}
+
+/// **认领的目录还不存在**时也必须能比对出碰撞。
+///
+/// 场景：第一个实例用 `--isolation custom --game-dir <某路径>` 登记（custom 档**不创建**目录），
+/// 那条路径恰好等于第二个实例缺省派生出来的目录名。第二个实例看到的目录「不存在、非空判据为假」，
+/// 但它已经被第一个实例认领了。
+///
+/// 抓得住：`claims`/`dir_key` 只在「路径存在」时才比较（那样第二条 `run_dir` 相同的断言会红）；
+/// 抓不住：跨卷/大小写之外的别名（例如 8.3 短名），本判据不覆盖。
+#[test]
+fn a_claim_on_a_not_yet_existing_dir_still_collides() {
+    let root = TempRoot::new("claim-missing");
+    foreign_minecraft(&root.game_root());
+    let default_dir = pack_dir::instance_dir(&root.launcher(), "Better MC");
+    assert!(!default_dir.exists(), "夹具前提：这个目录还不存在");
+
+    let mut first = request("1.20.1", AdoptTarget::Custom(default_dir.clone()));
+    first.name = Some("Better MC".to_string());
+    let a = adopt::adopt(&root.game(), &root.launcher(), &first).expect("custom 登记成功");
+    assert_eq!(a.run_dir, default_dir);
+    assert!(!default_dir.exists(), "custom 目标不该被创建");
+
+    let mut second = request("1.20.1", AdoptTarget::InstanceDir);
+    second.name = Some("Better-MC".to_string());
+    let b = adopt::adopt(&root.game(), &root.launcher(), &second).expect("第二次登记成功");
+
+    assert_ne!(b.run_dir, default_dir, "认领侧不存在也要能比对出碰撞");
+    assert!(
+        b.notes.iter().any(|note| note.contains("同一个物理目录")),
+        "碰撞要写进 notes：{:?}",
+        b.notes
+    );
+}
+
+/// **Win32 尾点/尾空格别名**：`custom` 认领 `Foo.`（目录还没建）与缺省派生 `Foo` 是**同一个物理目录**。
+///
+/// 复审 r2 的 R2.1：普通路径的尾点/尾空格会被 Win32 折叠，旧实现把尚不存在的尾段原样拼进比较键，
+/// 于是第二次默认登记仍拿到 `Foo`（两次都 exit0、两个 UUID、同一物理目录）。
+///
+/// 抓得住：`dir_key` 只做分隔符/大小写归一（`Foo.` 与 `Foo` 键不等，第二条断言红）。
+///
+/// 抓不住：verbatim 路径（`\\?\…`）——那种写法**不**折叠，是另一个物理目录，见下一条用例。
+#[cfg(windows)]
+#[test]
+fn a_trailing_dot_claim_still_collides_with_the_derived_dir() {
+    for suffix in [".", " "] {
+        let root = TempRoot::new("win32-alias");
+        foreign_minecraft(&root.game_root());
+        let claimed = pack_dir::instance_dir(&root.launcher(), &format!("Foo{suffix}"))
+            .with_file_name(format!("Foo{suffix}"));
+        assert!(!claimed.exists(), "夹具前提：认领目录还不存在");
+
+        let mut first = request("1.20.1", AdoptTarget::Custom(claimed.clone()));
+        first.name = Some("First".to_string());
+        let a = adopt::adopt(&root.game(), &root.launcher(), &first).expect("custom 登记成功");
+
+        let mut second = request("1.20.1", AdoptTarget::InstanceDir);
+        second.name = Some("Foo".to_string());
+        let b = adopt::adopt(&root.game(), &root.launcher(), &second)
+            .expect("第二次默认登记应成功（顺延到 -2，而不是复用同一目录）");
+
+        assert_ne!(
+            b.run_dir, a.run_dir,
+            "尾点/尾空格别名不许让两个实例共用一个运行目录（suffix={suffix:?}）"
+        );
+        assert!(
+            b.run_dir
+                .file_name()
+                .map(|name| name.to_string_lossy().ends_with("-2"))
+                .unwrap_or(false),
+            "应顺延成 -2：{}",
+            b.run_dir.display()
+        );
+        assert!(
+            !a.run_dir.exists(),
+            "custom 认领的目录不该被创建：{}",
+            a.run_dir.display()
+        );
+    }
+}
+
+/// 正向：**verbatim** 路径（`\\?\…`）不折叠 —— 它是另一个物理目录，必须允许并存。
+///
+/// 抓得住：归一化时盲目 trim（verbatim 的 `Foo.` 会被折叠成 `Foo`，这条第二次登记会顺延，
+/// `-2` 断言红）。
+///
+/// 抓不住：别的重解析点形态；也不验 8.3 短名。
+#[cfg(windows)]
+#[test]
+fn a_verbatim_trailing_dot_path_is_not_folded() {
+    let root = TempRoot::new("verbatim");
+    foreign_minecraft(&root.game_root());
+    let base = pack_dir::instance_dir(&root.launcher(), "Bar");
+    let verbatim =
+        std::path::PathBuf::from(format!(r"\\?\{}", base.with_file_name("Bar.").display()));
+    let mut first = request("1.20.1", AdoptTarget::Custom(verbatim.clone()));
+    first.name = Some("First".to_string());
+    adopt::adopt(&root.game(), &root.launcher(), &first).expect("verbatim custom 登记成功");
+
+    let mut second = request("1.20.1", AdoptTarget::InstanceDir);
+    second.name = Some("Bar".to_string());
+    let b = adopt::adopt(&root.game(), &root.launcher(), &second).expect("默认登记成功");
+    assert_eq!(
+        b.run_dir
+            .file_name()
+            .map(|n| n.to_string_lossy().into_owned()),
+        Some("Bar".to_string()),
+        "verbatim 的 Bar. 与普通 Bar 是两个目录，不该顺延"
+    );
+}

crates/core/tests/adopt/fixture.rs

@@ -0,0 +1,349 @@
+//! 真实磁盘夹具：一份「别的启动器铺好的」`.minecraft` + 全量快照工具。
+//!
+//! # 为什么必须是真盘
+//!
+//! 本 mission 的核心判据是**「登记前后外部文件一个字节都不变」**。内存里的假目录证明不了这件事
+//! ——mtime、目录项、符号链接都只有真文件系统才存在。所以每个用例都在 `std::env::temp_dir()`
+//! 下建一棵真目录树，`Drop` 时整棵删掉。
+//!
+//! # 夹具里放了什么（逐项都有用意）
+//!
+//! | 路径 | 用意 |
+//! | --- | --- |
+//! | `versions/1.20.1/` | 正常版本（清单 + jar） |
+//! | `versions/1.20.1-fabric-0.15.0/` | 正常版本，`inheritsFrom` 指向 1.20.1（父链闭合） |
+//! | `versions/1.20.1-broken/` | 清单不是合法 JSON |
+//! | `versions/1.20.1-orphan/` | `inheritsFrom` 指向不存在的父 |
+//! | `versions/cycle-a/` `versions/cycle-b/` | 互相继承（成环） |
+//! | `versions/1.20.1-nomanifest/` | 只有目录、没有同名清单 |
+//! | `libraries/` `assets/` | 恒共享层（登记不该碰） |
+//! | `mods/` `saves/` `config/` | 玩家数据（登记不该碰） |
+//! | `launcher_profiles.json` | 别的启动器的元数据（连读都不该读，更不该写） |
+//!
+//! 快照工具在 `snapshot.rs`（**全节点**：目录/文件/链接各记形状与 mtime，读盘失败即失败），
+//! 本模块只做 `pub use`，测试统一从 `crate::fixture::{snapshot, assert_unchanged, …}` 取。
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use unlucky_core::game::adopt::{AdoptRequest, AdoptTarget};
+use unlucky_core::game::GameLayout;
+
+pub use super::snapshot::{assert_unchanged, snapshot, snapshot_opt, Node};
+use unlucky_core::platform::layout::LauncherLayout;
+
+/// 唯一临时目录守卫（`drop` 时递归删除）。
+pub struct TempRoot {
+    path: PathBuf,
+}
+
+impl TempRoot {
+    /// 建一个唯一临时根。
+    pub fn new(tag: &str) -> Self {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map_or(0, |d| d.as_nanos());
+        let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let path = std::env::temp_dir().join(format!(
+            "ull-adopt-{tag}-{}-{nanos}-{seq}",
+            std::process::id()
+        ));
+        std::fs::create_dir_all(&path).expect("临时根应可创建");
+        Self { path }
+    }
+
+    /// 临时根路径。
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// `.minecraft`（游戏根）。
+    pub fn game_root(&self) -> PathBuf {
+        self.path.join(".minecraft")
+    }
+
+    /// 游戏布局。
+    pub fn game(&self) -> GameLayout {
+        GameLayout::new(self.game_root())
+    }
+
+    /// 启动器数据布局（`<root>/.ULL`）。
+    pub fn launcher(&self) -> LauncherLayout {
+        LauncherLayout::new(self.path.join(".ULL"))
+    }
+}
+
+impl Drop for TempRoot {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.path);
+    }
+}
+
+/// 造一份「别的启动器已经铺好的」`.minecraft`（见模块文档的表）。
+pub fn foreign_minecraft(root: &Path) {
+    let versions = root.join("versions");
+    // 正常版本：清单 + jar。
+    version_with(&versions, "1.20.1", MANIFEST_VANILLA, true);
+    // 正常版本：带父链（fabric 形态：只有清单、没有自己的 jar）。
+    version_with(&versions, "1.20.1-fabric-0.15.0", MANIFEST_FABRIC, false);
+    // 清单坏掉。
+    let broken = versions.join("1.20.1-broken");
+    std::fs::create_dir_all(&broken).expect("建坏清单目录");
+    std::fs::write(broken.join("1.20.1-broken.json"), b"{ this is not json").expect("写坏清单");
+    // 缺父版本。
+    version_with(&versions, "1.20.1-orphan", MANIFEST_ORPHAN, true);
+    // 成环。
+    version_with(&versions, "cycle-a", MANIFEST_CYCLE_A, true);
+    version_with(&versions, "cycle-b", MANIFEST_CYCLE_B, true);
+    // 只有目录、没有清单。
+    std::fs::create_dir_all(versions.join("1.20.1-nomanifest")).expect("建无清单目录");
+
+    // 恒共享层：库与资源（登记一个字节都不该动）。
+    write_file(
+        &root.join("libraries/com/mojang/brigadier/1.0.18/brigadier-1.0.18.jar"),
+        b"library-bytes",
+    );
+    write_file(&root.join("assets/indexes/5.json"), b"{\"objects\":{}}");
+    write_file(
+        &root.join("assets/objects/ab/abcdef0123456789abcdef0123456789abcdef01"),
+        b"asset-bytes",
+    );
+    // 玩家数据。
+    write_file(&root.join("mods/jei.jar"), b"mod-bytes");
+    write_file(&root.join("saves/World/level.dat"), b"save-bytes");
+    write_file(&root.join("config/example.toml"), b"config = 1\n");
+    // 别的启动器的元数据（登记不该读、更不该写）。
+    write_file(
+        &root.join("launcher_profiles.json"),
+        br#"{"profiles":{"1.20.1":{"name":"1.20.1","lastVersionId":"1.20.1"}}}"#,
+    );
+}
+
+fn version_with(versions: &Path, id: &str, manifest: &str, jar: bool) {
+    let dir = versions.join(id);
+    std::fs::create_dir_all(&dir).expect("建版本目录");
+    std::fs::write(dir.join(format!("{id}.json")), manifest.as_bytes()).expect("写清单");
+    if jar {
+        std::fs::write(dir.join(format!("{id}.jar")), b"jar-bytes").expect("写 jar");
+    }
+}
+
+fn write_file(path: &Path, bytes: &[u8]) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建父目录");
+    }
+    std::fs::write(path, bytes).expect("写文件");
+}
+
+/// 原版形态的最小清单（`downloads.client` 有值、无继承）。
+const MANIFEST_VANILLA: &str = r#"{
+  "id": "1.20.1",
+  "type": "release",
+  "mainClass": "net.minecraft.client.main.Main",
+  "assets": "5",
+  "assetIndex": { "id": "5" },
+  "arguments": {
+    "game": ["--username", "${auth_player_name}", "--version", "${version_name}",
+             "--gameDir", "${game_directory}"],
+    "jvm": ["-Djava.library.path=${natives_directory}", "-cp", "${classpath}"]
+  },
+  "libraries": [],
+  "downloads": { "client": { "size": 9, "url": "http://example.invalid/client.jar" } }
+}"#;
+
+/// Fabric 形态：`inheritsFrom` 指 1.20.1（父链闭合）。
+const MANIFEST_FABRIC: &str = r#"{
+  "id": "1.20.1-fabric-0.15.0",
+  "type": "release",
+  "inheritsFrom": "1.20.1",
+  "mainClass": "net.fabricmc.loader.impl.launch.knot.KnotClient",
+  "libraries": []
+}"#;
+
+/// 缺父版本（父 id 在盘上不存在）。
+const MANIFEST_ORPHAN: &str = r#"{
+  "id": "1.20.1-orphan",
+  "type": "release",
+  "inheritsFrom": "1.20.1-not-on-disk",
+  "mainClass": "net.minecraft.client.main.Main",
+  "libraries": []
+}"#;
+
+/// 环的一侧。
+const MANIFEST_CYCLE_A: &str = r#"{
+  "id": "cycle-a",
+  "type": "release",
+  "inheritsFrom": "cycle-b",
+  "mainClass": "net.minecraft.client.main.Main",
+  "libraries": []
+}"#;
+
+/// 环的另一侧。
+const MANIFEST_CYCLE_B: &str = r#"{
+  "id": "cycle-b",
+  "type": "release",
+  "inheritsFrom": "cycle-a",
+  "mainClass": "net.minecraft.client.main.Main",
+  "libraries": []
+}"#;
+
+/// 一次登记请求（测试用：固定 `created_at`，名字缺省 = 版本 id）。
+pub fn request(version_id: &str, target: AdoptTarget) -> AdoptRequest {
+    AdoptRequest {
+        version_id: version_id.to_string(),
+        name: None,
+        target,
+        created_at: Some("2026-11-09T00:00:00.000Z".to_string()),
+    }
+}
+
+/// 建目录符号链接（`true` = 建成）。Windows 上未开开发者模式/非管理员时可能失败。
+pub fn try_symlink_dir(target: &Path, link: &Path) -> bool {
+    #[cfg(unix)]
+    let created = std::os::unix::fs::symlink(target, link).is_ok();
+    #[cfg(windows)]
+    let created = std::os::windows::fs::symlink_dir(target, link).is_ok();
+    created
+}
+
+/// 用 `mklink /J` 建目录联接（junction 不需要管理员权限；建不出来返回 `false`）。
+///
+/// 只在 Windows 上有意义：junction 不是 `is_symlink`，是把别人版本目录挂进 `versions/` 最常见的
+/// 形态，所以越界判据必须能看见它——这条夹具就是用来证明这点的。
+#[cfg(windows)]
+pub fn try_junction(target: &Path, link: &Path) -> bool {
+    // `cmd /c mklink /J <link> <target>`：三个参数分开传，别拼成一整条（拼成一串会被 cmd 当语法错），
+    // 路径也必须**逐段 join**（`cmd` 把正斜杠当开关）。
+    let output = std::process::Command::new("cmd")
+        .args(["/c", "mklink", "/J"])
+        .arg(link)
+        .arg(target)
+        .output();
+    match output {
+        Ok(output) if output.status.success() && link.is_dir() => true,
+        Ok(output) => {
+            eprintln!(
+                "[junction] mklink /J {} {} 失败（{:?}）：{}{}",
+                link.display(),
+                target.display(),
+                output.status.code(),
+                String::from_utf8_lossy(&output.stdout),
+                String::from_utf8_lossy(&output.stderr)
+            );
+            false
+        }
+        Err(error) => {
+            eprintln!("[junction] 调不起 cmd：{error}");
+            false
+        }
+    }
+}
+
+/// 建目录链接：Windows 先试符号链接、再试联接；其它平台只有符号链接。
+pub fn try_link_dir(target: &Path, link: &Path) -> bool {
+    if try_symlink_dir(target, link) {
+        return true;
+    }
+    #[cfg(windows)]
+    {
+        try_junction(target, link)
+    }
+    #[cfg(not(windows))]
+    {
+        false
+    }
+}
+
+/// 链接夹具建不出来时怎么走（**真值表**，复审 r1 的 R4 抓的就是这张表被写反）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LinkGate {
+    /// 建成了：照常跑断言。
+    Run,
+    /// 没建成且**没要求强制**：打印一行记录后跳过（不静默）。
+    Skip,
+    /// 没建成且 `ULL_ADOPT_TEST_SYMLINK_REQUIRE=1`：**必红**，不许空跑。
+    Fail,
+}
+
+/// 纯判据：`(建成了吗, 是否强制)` → 怎么走。
+#[must_use]
+pub fn link_gate(created: bool, required: bool) -> LinkGate {
+    match (created, required) {
+        (true, _) => LinkGate::Run,
+        (false, true) => LinkGate::Fail,
+        (false, false) => LinkGate::Skip,
+    }
+}
+
+/// `ULL_ADOPT_TEST_SYMLINK_REQUIRE=1` 时链接夹具**不许**空跑。
+#[must_use]
+pub fn links_required() -> bool {
+    std::env::var("ULL_ADOPT_TEST_SYMLINK_REQUIRE")
+        .as_deref()
+        .map(str::trim)
+        == Ok("1")
+}
+
+/// 链接夹具的守卫：返回 `true` = 继续跑断言；`false` = 已显式跳过（调用方 `return`）。
+///
+/// `required` 由环境变量决定（[`links_required`]）；判据本身是 [`link_gate`]。
+pub fn link_guard(created: bool, what: &str) -> bool {
+    link_guard_with(created, links_required(), what)
+}
+
+/// 同 [`link_guard`]，但 `required` 显式传入（测试要能**执行**强制分支，而不靠改进程环境）。
+///
+/// # Panics
+///
+/// `required` 且没建成链接/联接：**红**（这是复审 r1 的 R4：旧写法把方向写反了，
+/// 强制模式下建不出来反而直接「成功」返回）。
+pub fn link_guard_with(created: bool, required: bool, what: &str) -> bool {
+    match link_gate(created, required) {
+        LinkGate::Run => true,
+        LinkGate::Skip => {
+            eprintln!(
+                "[link-guard] {what}：本机建不出符号链接/目录联接，已显式跳过这条用例；                 设 ULL_ADOPT_TEST_SYMLINK_REQUIRE=1 可让它必跑（建不出来即红）"
+            );
+            false
+        }
+        LinkGate::Fail => panic!(
+            "[link-guard] {what}：ULL_ADOPT_TEST_SYMLINK_REQUIRE=1，但本机建不出符号链接/目录联接             ——这条用例不许空跑，判红"
+        ),
+    }
+}
+
+/// 真值表的回归：**强制模式建不出来必须致命**（R4 的反转就是这张表写错）。
+///
+/// 抓得住：把 `(false, true)` 判成 `Skip`（旧实现的写法）、或把 `(false, false)` 判成 `Fail`。
+/// 抓不住：真实建链接是否成功（那由各链接用例自己走 [`link_guard`]）。
+#[test]
+fn link_gate_truth_table() {
+    assert_eq!(link_gate(true, false), LinkGate::Run);
+    assert_eq!(link_gate(true, true), LinkGate::Run);
+    assert_eq!(link_gate(false, false), LinkGate::Skip);
+    assert_eq!(
+        link_gate(false, true),
+        LinkGate::Fail,
+        "强制模式下建不出链接必须红"
+    );
+}
+
+/// **执行**守卫的三个分支（不只测纯判据）：Run 继续、Skip 返回 false、Fail panic。
+///
+/// 抓得住：把 `Fail` 分支写成 `return false`（`catch_unwind` 捕不到 panic，最后一条断言红）；
+/// 把 `Skip` 写成 panic（第一条 `catch_unwind` 不再 ok）。
+/// 抓不住：真实建链接是否成功（各链接用例自己走 [`link_guard`]）；也不依赖进程级环境变量，
+/// 因此可与并行用例共存。
+#[test]
+fn link_guard_executes_all_three_branches() {
+    assert!(link_guard_with(true, false, "已建成"));
+    assert!(
+        std::panic::catch_unwind(|| link_guard_with(false, false, "非强制模式 · 建不出")).is_ok(),
+        "非强制模式不许 panic"
+    );
+    assert!(!link_guard_with(false, false, "非强制模式 · 建不出"));
+    let forced = std::panic::catch_unwind(|| link_guard_with(false, true, "强制模式 · 建不出"));
+    assert!(forced.is_err(), "强制模式下建不出来必须 panic（R4）");
+}

crates/core/tests/adopt/fixture_cases.rs

@@ -0,0 +1,141 @@
+//! 快照工具自身的回归：它必须抓得住「凭空多出一个空目录」（复审 r1 的 R5）。
+//!
+//! 早先的快照只记文件：`scan` 或 `--dry-run` 若在外部树里建了一个空目录（例如
+//! `<game>/versions/<v>/mods`），快照完全不变，于是「零写入」这条承诺可以是假绿。
+//! 这里用**同一份** `snapshot.rs` 证明：目录节点、链接节点都进快照，读盘失败不吞。
+
+use std::path::Path;
+
+use crate::fixture::{
+    link_guard, snapshot, snapshot_opt, try_link_dir, try_symlink_dir, Node, TempRoot,
+};
+
+/// 目录 / 文件 / 链接三类节点都记，且链接**不跟随**（目标内容不会挂到链接路径下）。
+///
+/// 抓得住：
+/// - 目录节点缺失（`dir` 断言红）；
+/// - 跟随链接（`link/inside.txt` 会同时出现在链接路径下，`is_none` 断言红）；
+/// - 链接被当成普通目录（`Node::Link` 断言红）。
+///
+/// 抓不住：链接目标本身的内容变化（不跟随就看不见——这正是本工具要的语义）。
+#[test]
+fn snapshot_records_dirs_files_and_links_without_following() {
+    let root = TempRoot::new("snap-shapes");
+    let real = root.path().join("real");
+    std::fs::create_dir_all(&real).expect("建真实目录");
+    std::fs::write(real.join("inside.txt"), b"x").expect("写文件");
+    let link = root.path().join("link");
+    if !link_guard(try_symlink_dir(&real, &link), "快照链接夹具") {
+        // 链接建不出来时仍要验目录/文件两类（guard 已显式记录跳过原因）。
+        let snap = snapshot(root.path());
+        assert!(matches!(snap.get("real"), Some(Node::Dir { .. })));
+        assert!(matches!(
+            snap.get("real/inside.txt"),
+            Some(Node::File { .. })
+        ));
+        return;
+    }
+
+    let snap = snapshot(root.path());
+    assert!(
+        matches!(snap.get("."), Some(Node::Dir { .. })),
+        "根自身也要记"
+    );
+    assert!(matches!(snap.get("real"), Some(Node::Dir { .. })));
+    assert!(matches!(
+        snap.get("real/inside.txt"),
+        Some(Node::File { .. })
+    ));
+    assert!(
+        matches!(snap.get("link"), Some(Node::Link { .. })),
+        "链接要记成 Link：{:?}",
+        snap.get("link")
+    );
+    assert!(
+        !snap.contains_key("link/inside.txt"),
+        "不许跟随链接（否则根外/别处内容会被算进这棵树）"
+    );
+}
+
+/// **新增一个空目录**必须让快照变化（R5 的核心判据）。
+///
+/// 抓得住：只记文件的旧快照（`before == after` 会让第一条断言红）。
+/// 抓不住：目录 mtime 的精度（这条只比路径集合与节点形状；mtime 由 `assert_unchanged` 另外守）。
+#[test]
+fn snapshot_catches_a_new_empty_directory() {
+    let root = TempRoot::new("snap-newdir");
+    let game = root.game_root().join("versions").join("1.20.1");
+    std::fs::create_dir_all(&game).expect("建版本目录");
+    let before = snapshot(&root.game_root());
+
+    // 「登记过程凭空建了一个空目录」——正是旧快照看不见的那种改动。
+    let planted = game.join("mods");
+    std::fs::create_dir_all(&planted).expect("建空目录");
+    let after = snapshot(&root.game_root());
+
+    assert_ne!(before, after, "新增空目录必须改变快照");
+    assert!(
+        !before.contains_key("versions/1.20.1/mods"),
+        "改动前不该有这个节点"
+    );
+    assert!(
+        matches!(after.get("versions/1.20.1/mods"), Some(Node::Dir { .. })),
+        "新增的空目录要作为目录节点出现：{:?}",
+        after.get("versions/1.20.1/mods")
+    );
+
+    // 反向：删掉之后路径集合回到原样（目录 mtime 会变，所以只比键集合）。
+    std::fs::remove_dir(&planted).expect("删空目录");
+    let again = snapshot(&root.game_root());
+    assert_eq!(
+        before.keys().collect::<Vec<_>>(),
+        again.keys().collect::<Vec<_>>(),
+        "删掉空目录后路径集合应回到原样"
+    );
+}
+
+/// 目录的 mtime 变化也要能看见（条目增删会改父目录 mtime）。
+///
+/// 抓得住：目录节点只记路径不记 mtime（那样 `Node::Dir{mtime_ns}` 相同，第二条断言红）。
+/// 抓不住：某些文件系统对 mtime 的粗粒度（本机 NTFS 是 100ns 级；真粗到同一 tick 时这条会软过）。
+#[test]
+fn snapshot_notices_a_directory_mtime_change() {
+    let root = TempRoot::new("snap-dirmtime");
+    let dir = root.path().join("watched");
+    std::fs::create_dir_all(&dir).expect("建目录");
+    let before = snapshot(root.path());
+    std::fs::write(dir.join("new.txt"), b"x").expect("写文件");
+    let after = snapshot(root.path());
+    let before_node = before.get("watched").expect("有该目录节点");
+    let after_node = after.get("watched").expect("有该目录节点");
+    assert_ne!(
+        before_node, after_node,
+        "目录里加了文件，目录节点（含 mtime）必须变"
+    );
+}
+
+/// 目标根本不存在 ⇒ `snapshot_opt` 给 `None`（与「空树」区分开）。
+///
+/// 抓得住：把「不存在」当成空快照（那样「dry-run 建了 .ULL」就看不出来）。
+/// 抓不住：存在但权限不足（那一支直接 panic，见模块文档）。
+#[test]
+fn a_missing_target_is_none_not_an_empty_snapshot() {
+    let root = TempRoot::new("snap-missing");
+    let absent: &Path = &root.path().join("nope");
+    assert!(snapshot_opt(absent).is_none());
+    std::fs::create_dir_all(absent).expect("建空目录");
+    assert!(snapshot_opt(absent).is_some(), "空目录也算存在");
+}
+
+/// 链接建不出来时 `try_link_dir` 会退回联接（Windows）；这条只验它不 panic。
+#[test]
+fn link_fixtures_are_total() {
+    let root = TempRoot::new("snap-link-total");
+    let target = root.path().join("target");
+    std::fs::create_dir_all(&target).expect("建目标");
+    let link = root.path().join("link");
+    let created = try_link_dir(&target, &link);
+    if created {
+        assert!(link.is_dir());
+    }
+}

crates/core/tests/adopt/main.rs

@@ -0,0 +1,24 @@
+//! M221 core 侧集成测试入口：从**别人的** `.minecraft` 只读登记版本（adopt）。
+//!
+//! 分工：
+//! - `fixture`：临时真实磁盘目录 + 一份「别的启动器铺好的」`.minecraft`；
+//! - `snapshot`：**全节点**快照（目录/文件/链接 + mtime），core 与 CLI 测试共用这一份；
+//! - `scan_cases`：`scan` / `inspect` 的判据（正常 / 坏 JSON / 缺父 / 成环 / 缺清单 / 越界符号链接）；
+//! - `plan_cases`：还没登记时的**只读**判据与拒绝理由（dry-run 零写盘 / 缺父 / 不存在 / 非法目标）；
+//! - `collision_cases`：缺省运行目录**不许被两个实例共用**（slug / 大小写 / 已被占 / 认领但未创建）；
+//! - `register_cases`：`adopt` 的落点与写盘面（缺省独立目录 / shared / isolated / custom /
+//!   重名 / 重复 / 非空目录 / 数据区联接 / **slug 与大小写碰撞不许共用运行目录** / 外部树全节点不变）；
+//! - `surface_cases`：配置写面被链接走出去必须拒绝（R2）、`versions` 入口断链必须报错（R3）；
+//! - `fixture_cases`：快照工具自身的回归（它得抓得住「凭空多一个空目录」，R5）。
+//!
+//! 这些用例**不启动真实 Minecraft**：验的是「登记这一步做了什么、没做什么」，启动链路由
+//! `tests/game/*` 与 CLI 的 `launch --dry-run` 各自覆盖。
+
+mod collision_cases;
+mod fixture;
+mod fixture_cases;
+mod plan_cases;
+mod register_cases;
+mod scan_cases;
+mod snapshot;
+mod surface_cases;

crates/core/tests/adopt/plan_cases.rs

@@ -0,0 +1,118 @@
+//! `plan` / `inspect` 的**只读**判据与拒绝理由：零写盘、缺父/不存在/非法目标的报错形状。
+//!
+//! 与 `register_cases` 的分工：那边验「登记写出了什么」，这边验「还没登记时算出了什么、拒绝得对不对」。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::adopt::{self, AdoptError, AdoptTarget};
+use unlucky_core::game::install::instance::Isolation;
+
+use crate::fixture::{
+    assert_unchanged, foreign_minecraft, request, snapshot, snapshot_opt, TempRoot,
+};
+
+/// 缺省档位本身就是「数据区独立目录」，而且**不是** `isolated`（判据的单一真相源）。
+///
+/// 抓得住：把 `#[default]` 挪到 `VersionDir`/`Shared`（第一条断言红），或让缺省档映射到
+/// `Isolated`（第二条断言红）——后者正是「导入别人的版本后第一次启动就在他的 `versions/<id>/`
+/// 里长 mods/saves」的那个坑。
+/// 抓不住：CLI 是否真的用 `AdoptTarget::default()`（那条由 cli/adopt_test 的行为断言钉着）。
+#[test]
+fn the_default_target_is_an_own_dir_not_the_global_isolated_mode() {
+    let target = AdoptTarget::default();
+    assert_eq!(target, AdoptTarget::InstanceDir);
+    assert_eq!(target.as_str(), "instance_dir");
+    assert_eq!(target.isolation(), Isolation::Custom);
+    assert_ne!(target.isolation(), Isolation::Isolated);
+}
+
+/// `--isolation custom --game-dir <相对路径>` ⇒ 明确报错（不猜、不悄悄改成绝对路径）。
+///
+/// 抓得住：相对路径被默默接受（`TargetInvalid` 变成成功）。
+/// 抓不住：Windows 上 `C:foo` 这种「带盘符但非绝对」的形状，只看 `is_absolute`。
+#[test]
+fn custom_target_requires_an_absolute_directory() {
+    let root = TempRoot::new("custom-rel");
+    foreign_minecraft(&root.game_root());
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::Custom(PathBuf::from("relative/dir"))),
+    )
+    .expect_err("相对路径应被拒");
+    assert_eq!(error.code(), "adopt_target_invalid");
+    assert!(error.to_string().contains("绝对路径"), "{error}");
+}
+
+/// `--dry-run` 的 core 形态（`plan`）：一个文件都不写、目录也不建。
+///
+/// 抓得住：`plan` 顺手建了运行目录或写了档案（两种断言都会红）。
+/// 抓不住：CLI 的 `--dry-run` 是否真的只调 `plan`（那条在 cli 侧用例里）。
+#[test]
+fn plan_writes_nothing_at_all() {
+    let root = TempRoot::new("plan");
+    foreign_minecraft(&root.game_root());
+    let before = snapshot(root.path());
+
+    let plan = adopt::plan(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("计划应成功");
+    let after = snapshot(root.path());
+    assert_unchanged(&before, &after, "plan 之后（含 .ULL）");
+
+    assert!(plan.candidate.adoptable());
+    assert!(!plan.run_dir.exists(), "plan 不该建目录");
+    // `.ULL` 连**空目录**都不许出现（存在性用 `snapshot_opt`，与「空树」区分开）。
+    assert!(
+        snapshot_opt(&root.path().join(".ULL")).is_none(),
+        "plan 不该建配置目录（连空的也不行）"
+    );
+}
+
+/// 不可登记的版本（缺父）⇒ 一条都不登记，问题清单原样带出。
+///
+/// 抓得住：缺父的版本被登记（启动必失败却显示「导入成功」）、问题被折叠成一句空话。
+/// 抓不住：用户在原来的启动器里修好之后重试（那条由重试路径自然覆盖）。
+#[test]
+fn not_adoptable_versions_are_refused_with_their_reasons() {
+    let root = TempRoot::new("refuse");
+    foreign_minecraft(&root.game_root());
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1-orphan", AdoptTarget::InstanceDir),
+    )
+    .expect_err("缺父版本应被拒");
+    assert_eq!(error.code(), "adopt_not_adoptable");
+    let codes: Vec<&str> = error
+        .problems()
+        .iter()
+        .map(|problem| problem.code())
+        .collect();
+    assert_eq!(codes, vec!["missing_parent"]);
+    assert!(
+        !root.path().join(".ULL/config/profiles.json").exists(),
+        "拒绝时不许留档案"
+    );
+}
+
+/// 不存在的版本 ⇒ `adopt_version_not_found`（不是「帮你在网上下一个」）。
+///
+/// 抓得住：不存在的 id 被当成可登记（档案指向空版本）。
+/// 抓不住：`versions/` 整个不存在的情形（上一条扫描用例覆盖）。
+#[test]
+fn an_unknown_version_is_reported_as_not_found() {
+    let root = TempRoot::new("unknown");
+    foreign_minecraft(&root.game_root());
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("9.9.9", AdoptTarget::InstanceDir),
+    )
+    .expect_err("不存在的版本应报错");
+    assert!(matches!(error, AdoptError::UnknownVersion { .. }));
+    assert_eq!(error.code(), "adopt_version_not_found");
+}

crates/core/tests/adopt/register_cases.rs

@@ -0,0 +1,298 @@
+//! `plan` / `adopt` 的落点与写盘面：登记只写自己的配置，外部 `.minecraft` 一个字节都不动。
+//!
+//! 每条用例都带「抓得住 / 抓不住」，并且**外部快照断言**是每条的核心：`versions/`
+//! `libraries/` `assets/` `mods/` `saves/` `config/` `launcher_profiles.json` 的路径集合、
+//! 字节数、内容哈希、mtime 全都不许变（`fixture::assert_unchanged`）。
+
+use unlucky_core::game::adopt::{self, AdoptTarget};
+use unlucky_core::game::install::instance::{read_instance_config, read_profiles, Isolation};
+use unlucky_core::game::isolation::{derive_game_dir, IsolationMode};
+
+use crate::fixture::{assert_unchanged, foreign_minecraft, request, snapshot, TempRoot};
+
+/// 缺省（不给 `--isolation`）：运行目录落 ULL 数据区的独立目录，隔离档写 `custom`。
+///
+/// 抓得住：缺省沿用全局 `isolated`（那样 `run_dir` 会变成 `versions/1.20.1`）、
+/// `gameDir` 没落盘、外部文件被写（哈希/mtime 断言）、profiles 没登记。
+/// 抓不住：真实启动是否真的把 `--gameDir` 用上（core 侧只验派生结果，CLI 侧用 `launch --dry-run` 验）。
+#[test]
+fn default_target_lands_in_the_launcher_data_area() {
+    let root = TempRoot::new("default");
+    foreign_minecraft(&root.game_root());
+    let before = snapshot(&root.game_root());
+
+    let outcome = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("登记应成功");
+    let after = snapshot(&root.game_root());
+    assert_unchanged(&before, &after, "缺省登记之后");
+
+    assert_eq!(outcome.isolation, Isolation::Custom);
+    assert!(outcome.created);
+    assert!(outcome.dir_created, "缺省目录应被新建");
+    let instances_dir = root.path().join(".ULL/data/instances");
+    assert!(
+        outcome.run_dir.starts_with(&instances_dir),
+        "运行目录必须在 ULL 数据区：{}",
+        outcome.run_dir.display()
+    );
+    assert!(outcome.run_dir.is_dir());
+    assert!(
+        !outcome.run_dir.starts_with(root.game_root()),
+        "缺省运行目录不许落在别人的 .minecraft 里"
+    );
+
+    // 落盘的三样东西：profiles.json、实例设置、新建的空运行目录。
+    let profiles = read_profiles(&root.launcher()).expect("读档案");
+    assert_eq!(profiles.profiles.len(), 1);
+    assert_eq!(profiles.profiles[0].name, "1.20.1");
+    assert_eq!(profiles.profiles[0].version_id, "1.20.1");
+    let config = read_instance_config(&root.launcher(), &outcome.instance_id)
+        .expect("读设置")
+        .expect("设置文件存在");
+    assert_eq!(config.isolation, Some(Isolation::Custom));
+    assert_eq!(config.game_dir.as_deref(), Some(outcome.run_dir.as_path()));
+
+    // 启动时 `--gameDir` 真的会取这个目录（D20 覆盖链的权威求值）。
+    let derivation = derive_game_dir(
+        &root.game(),
+        "1.20.1",
+        IsolationMode::Isolated,
+        Some(&config),
+        None,
+    )
+    .expect("派生运行目录");
+    assert_eq!(derivation.game_dir, outcome.run_dir);
+    assert_eq!(derivation.isolation, Isolation::Custom);
+}
+
+/// `--isolation shared`：运行目录 = 别人的游戏根，且**人读提示必须说出后果**。
+///
+/// 抓得住：shared 档被当成 custom 写 `game_dir`、提示里没提「共用/别人的 .minecraft」、
+/// 登记过程往游戏根写了东西（哈希断言）。
+/// 抓不住：用户是否真的读到了这句提示（那属于 UI 验收）。
+#[test]
+fn shared_target_points_at_the_game_root_and_says_what_it_means() {
+    let root = TempRoot::new("shared");
+    foreign_minecraft(&root.game_root());
+    let before = snapshot(&root.game_root());
+
+    let outcome = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::Shared),
+    )
+    .expect("登记应成功");
+    let after = snapshot(&root.game_root());
+    assert_unchanged(&before, &after, "shared 登记之后");
+
+    assert_eq!(outcome.isolation, Isolation::Shared);
+    assert_eq!(outcome.run_dir, root.game_root());
+    assert!(
+        outcome.notes.iter().any(|note| note.contains("共用")),
+        "必须告知「共用别人的 .minecraft」：{:?}",
+        outcome.notes
+    );
+    let config = read_instance_config(&root.launcher(), &outcome.instance_id)
+        .expect("读设置")
+        .expect("设置文件存在");
+    assert_eq!(config.isolation, Some(Isolation::Shared));
+    assert_eq!(config.game_dir, None, "shared 档不该固化成 custom");
+}
+
+/// `--isolation isolated`：运行目录 = `versions/<id>`，**登记这一刻仍不往那里写任何东西**。
+///
+/// 抓得住：`VersionDir` 被漏做（`isolation` 不是 `Isolated`）、提示里没提「会新增玩家数据」、
+/// 登记当场就在版本目录里建了 `mods/`（下面的目录内容断言会红）。
+/// 抓不住：首次启动之后游戏自己往里写（那是启动链路的事，本 mission 不跑真游戏）。
+#[test]
+fn version_dir_target_is_explicit_and_writes_nothing_yet() {
+    let root = TempRoot::new("isolated");
+    foreign_minecraft(&root.game_root());
+    let before = snapshot(&root.game_root());
+
+    let outcome = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::VersionDir),
+    )
+    .expect("登记应成功");
+    let after = snapshot(&root.game_root());
+    assert_unchanged(&before, &after, "isolated 登记之后");
+
+    assert_eq!(outcome.isolation, Isolation::Isolated);
+    assert_eq!(outcome.run_dir, root.game_root().join("versions/1.20.1"));
+    assert!(
+        outcome.notes.iter().any(|note| note.contains("新增")),
+        "必须告知「第一次启动会在这里新增玩家数据」：{:?}",
+        outcome.notes
+    );
+    assert!(!outcome.dir_created, "版本目录已存在，不该新建");
+    let mut entries: Vec<String> = std::fs::read_dir(&outcome.run_dir)
+        .expect("读版本目录")
+        .filter_map(|entry| Some(entry.ok()?.file_name().to_string_lossy().into_owned()))
+        .collect();
+    entries.sort();
+    assert_eq!(
+        entries,
+        vec!["1.20.1.jar".to_string(), "1.20.1.json".to_string()],
+        "版本目录里不该多出任何东西"
+    );
+}
+
+/// 展示名已被别的实例占用 ⇒ 显式报错，不改任何档案（不静默复用别的版本）。
+///
+/// 抓得住：`register` 的幂等复用路径被当成「导入成功」（那样第二个版本会指向第一个实例的档案）。
+/// 抓不住：CLI 的 hint 文案（那条在 cli 侧用例里）。
+#[test]
+fn a_taken_name_is_an_explicit_error() {
+    let root = TempRoot::new("dupname");
+    foreign_minecraft(&root.game_root());
+    adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("第一个登记成功");
+    let profiles_before =
+        std::fs::read(root.path().join(".ULL/config/profiles.json")).expect("读档案");
+
+    let mut second = request("1.20.1-fabric-0.15.0", AdoptTarget::InstanceDir);
+    second.name = Some("1.20.1".to_string());
+    let error = adopt::adopt(&root.game(), &root.launcher(), &second).expect_err("重名应被拒");
+    assert_eq!(error.code(), "adopt_duplicate_name");
+    let profiles_after =
+        std::fs::read(root.path().join(".ULL/config/profiles.json")).expect("读档案");
+    assert_eq!(profiles_before, profiles_after, "失败不许改档案");
+}
+
+/// 同一个版本重复登记 ⇒ 无副作用失败（`adopt_already_registered`），档案逐字节不变。
+///
+/// 抓得住：重复登记变成「静默成功」（第二条断言会红），或失败时仍改写了档案。
+/// 抓不住：并发两次 adopt 的竞态（没有锁；本命令不是并发入口，如实记在这里）。
+#[test]
+fn repeating_the_same_adopt_fails_without_side_effects() {
+    let root = TempRoot::new("repeat");
+    foreign_minecraft(&root.game_root());
+    adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("第一次登记成功");
+    let config_dir = root.path().join(".ULL/config");
+    let before = snapshot(&config_dir);
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("重复登记应报错");
+    assert_eq!(error.code(), "adopt_already_registered");
+    let after = snapshot(&config_dir);
+    assert_unchanged(&before, &after, "重复登记失败之后");
+}
+
+/// 缺省运行目录已存在且非空 ⇒ 拒绝（不猜「合并进已有实例」，不覆盖用户内容）。
+///
+/// 抓得住：非空目录被复用（内容被游戏写进去只是时间问题）、拒绝时仍写了档案。
+/// 抓不住：空目录复用那条正向路径（见下一条用例）。
+#[test]
+fn a_non_empty_default_run_dir_is_refused() {
+    let root = TempRoot::new("occupied");
+    foreign_minecraft(&root.game_root());
+    let plan = adopt::plan(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("先算一次落点");
+    std::fs::create_dir_all(&plan.run_dir).expect("建目录");
+    std::fs::write(plan.run_dir.join("someone-elses-file.txt"), b"keep me").expect("写文件");
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("非空目录应被拒");
+    assert_eq!(error.code(), "adopt_target_not_empty");
+    assert_eq!(
+        std::fs::read(plan.run_dir.join("someone-elses-file.txt")).expect("读文件"),
+        b"keep me"
+    );
+    assert!(
+        !root.path().join(".ULL/config/profiles.json").exists(),
+        "拒绝时不许留档案"
+    );
+}
+
+/// 缺省运行目录存在但**为空** ⇒ 复用（上次失败的残留不该让用户永远重试不了）。
+///
+/// 抓得住：空目录也被拒（那就把「先建目录再登记」这条路堵死了）。
+/// 抓不住：目录里的隐藏文件（`read_dir` 能看见，但平台差异在这里没覆盖）。
+#[test]
+fn an_empty_default_run_dir_is_reused() {
+    let root = TempRoot::new("empty-dir");
+    foreign_minecraft(&root.game_root());
+    let plan = adopt::plan(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("先算一次落点");
+    std::fs::create_dir_all(&plan.run_dir).expect("建空目录");
+
+    let outcome = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("空目录可复用");
+    assert!(!outcome.dir_created, "已存在的空目录不算新建");
+    assert_eq!(outcome.run_dir, plan.run_dir);
+}
+
+/// 数据区里预先放了指向外部的目录联接 ⇒ 缺省运行目录拒绝沿它写盘。
+///
+/// 抓得住：`create_dir_all` 直接沿联接在数据根之外建目录（外部会多出条目，最后一条断言红），
+/// 或错误码不是 `adopt_target_invalid`。
+/// 抓不住：数据根**自己**是链接的情形——那是用户的数据目录迁移手法，允许（判据是落点仍在
+/// 解析后的数据根内）；也抓不住检查与建目录之间的 TOCTOU。
+#[cfg(windows)]
+#[test]
+fn a_junction_inside_the_data_area_does_not_get_written_through() {
+    let root = TempRoot::new("datajunction");
+    foreign_minecraft(&root.game_root());
+    let outside = root.path().join("outside-instances");
+    std::fs::create_dir_all(&outside).expect("建外部目录");
+    // 逐段 join：`mklink` 把正斜杠当开关，拼成一串带 `/` 的路径会被判「无效参数」。
+    let data_instances = root.path().join(".ULL").join("data").join("instances");
+    std::fs::create_dir_all(data_instances.parent().expect("父目录")).expect("建 data 目录");
+    if !crate::fixture::link_guard(
+        crate::fixture::try_junction(&outside, &data_instances),
+        "数据区目录联接",
+    ) {
+        return;
+    }
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("数据区里的联接必须被拒");
+    assert_eq!(error.code(), "adopt_target_invalid", "{error}");
+    let entries: Vec<String> = std::fs::read_dir(&outside)
+        .expect("读外部目录")
+        .filter_map(|entry| Some(entry.ok()?.file_name().to_string_lossy().into_owned()))
+        .collect();
+    assert!(
+        entries.is_empty(),
+        "不许沿联接在数据根之外建目录：{entries:?}"
+    );
+}

crates/core/tests/adopt/scan_cases.rs

@@ -0,0 +1,347 @@
+//! `scan` / `inspect` 的判据：正常版本能不能过、坏东西是不是**逐条**说清楚。
+//!
+//! 每条断言下面都标了「抓得住 / 抓不住」：抓得住的是变异实现会变红的具体结论，
+//! 抓不住的是只能靠人读的东西（措辞、是否还有别的静默吞掉路径）。
+
+use unlucky_core::game::adopt::{self, AdoptCandidate};
+
+use crate::fixture::{assert_unchanged, foreign_minecraft, snapshot, TempRoot};
+
+/// 扫一次并按 id 取候选（`inspect` 对不合格候选返回 `Err`，扫描则逐项列出，断言更好写）。
+fn candidate_of(root: &TempRoot, version_id: &str) -> AdoptCandidate {
+    let scan = adopt::scan(&root.game(), &root.launcher()).expect("扫描应成功");
+    scan.candidates
+        .into_iter()
+        .find(|candidate| candidate.version_id == version_id)
+        .unwrap_or_else(|| panic!("扫描里没有 {version_id}"))
+}
+
+/// 正常 / 缺清单 / 坏 JSON / 缺父 / 成环：一次扫描把每个候选的结论都说出来。
+///
+/// 抓得住：`scan` 把坏东西当空列表（`candidates` 少项就红）、漏掉父链（`inherits` 长度变）、
+/// 缺父被当成可登记（`adoptable` 变真）、成环没被检出（`cycle-*` 会变可登记）。
+/// 抓不住：问题文案的措辞，以及 `versions/` 之外的地方有没有被读写（由下面的哈希断言覆盖）。
+#[test]
+fn scan_reports_every_version_with_its_reason() {
+    let root = TempRoot::new("scan");
+    foreign_minecraft(&root.game_root());
+    let before = snapshot(root.path());
+
+    let scan = adopt::scan(&root.game(), &root.launcher()).expect("扫描应成功");
+    let after = snapshot(root.path());
+    assert_unchanged(&before, &after, "scan 之后");
+
+    let ids: Vec<&str> = scan
+        .candidates
+        .iter()
+        .map(|candidate| candidate.version_id.as_str())
+        .collect();
+    assert_eq!(
+        ids,
+        vec![
+            "1.20.1",
+            "1.20.1-broken",
+            "1.20.1-fabric-0.15.0",
+            "1.20.1-nomanifest",
+            "1.20.1-orphan",
+            "cycle-a",
+            "cycle-b",
+        ],
+        "扫描必须列出每一个目录（含不可登记的），不能少一行"
+    );
+
+    let by_id = |id: &str| {
+        scan.candidates
+            .iter()
+            .find(|candidate| candidate.version_id == id)
+            .unwrap_or_else(|| panic!("缺候选 {id}"))
+    };
+
+    let vanilla = by_id("1.20.1");
+    assert!(
+        vanilla.adoptable(),
+        "正常版本应可登记：{:?}",
+        vanilla.problems
+    );
+    assert!(vanilla.jar_present);
+    assert_eq!(vanilla.inherits, vec!["1.20.1"]);
+    assert!(!vanilla.is_registered());
+
+    let fabric = by_id("1.20.1-fabric-0.15.0");
+    assert!(fabric.adoptable(), "{:?}", fabric.problems);
+    assert!(!fabric.jar_present, "fabric 版本自己没有 jar");
+    assert_eq!(
+        fabric.inherits,
+        vec!["1.20.1-fabric-0.15.0", "1.20.1"],
+        "父链必须走到底"
+    );
+
+    let codes = |id: &str| -> Vec<&'static str> {
+        by_id(id)
+            .problems
+            .iter()
+            .map(|problem| problem.code())
+            .collect()
+    };
+    assert_eq!(codes("1.20.1-broken"), vec!["manifest_invalid_json"]);
+    assert_eq!(codes("1.20.1-nomanifest"), vec!["manifest_missing"]);
+    assert_eq!(codes("1.20.1-orphan"), vec!["missing_parent"]);
+    assert_eq!(codes("cycle-a"), vec!["circular_inheritance"]);
+    assert_eq!(codes("cycle-b"), vec!["circular_inheritance"]);
+    for id in ["1.20.1-broken", "1.20.1-orphan", "cycle-a"] {
+        assert!(!by_id(id).adoptable(), "{id} 不该被判成可登记");
+    }
+}
+
+/// 缺父要说清**缺哪个**、成环要说清**环长什么样**（不是一句「继承有问题」）。
+///
+/// 抓得住：`MissingParent` 丢了 `parent` 字段、环链只剩最后一个 id（两个都会被下面的 contains 抓到）。
+/// 抓不住：错误码是否被 CLI 原样透出（那条在 cli/tests/adopt_test 里）。
+#[test]
+fn missing_parent_and_cycle_name_what_is_wrong() {
+    let root = TempRoot::new("chain");
+    foreign_minecraft(&root.game_root());
+    let scan = adopt::scan(&root.game(), &root.launcher()).expect("扫描应成功");
+    let problems = |id: &str| {
+        scan.candidates
+            .iter()
+            .find(|candidate| candidate.version_id == id)
+            .expect("有候选")
+            .problems
+            .clone()
+    };
+
+    let orphan = problems("1.20.1-orphan");
+    let message = orphan.first().expect("一条问题").to_string();
+    assert!(message.contains("1.20.1-not-on-disk"), "{message}");
+    assert!(message.contains("1.20.1-orphan"), "{message}");
+
+    let cycle = problems("cycle-a");
+    let message = cycle.first().expect("一条问题").to_string();
+    assert!(message.contains("cycle-a"), "{message}");
+    assert!(message.contains("cycle-b"), "{message}");
+}
+
+/// 坏 JSON 要带**行列号**（用户才知道去改哪一行）。
+///
+/// 抓得住：把 serde 的错误文本换成一句「解析失败」（`line` 就没了）。
+/// 抓不住：具体行列号对不对（不同 serde_json 版本的措辞会变，只断言关键字）。
+#[test]
+fn broken_json_message_carries_a_line_number() {
+    let root = TempRoot::new("badjson");
+    foreign_minecraft(&root.game_root());
+    let candidate = candidate_of(&root, "1.20.1-broken");
+    let message = candidate.problems.first().expect("一条问题").to_string();
+    assert!(message.contains("line"), "{message}");
+    assert!(message.contains("1.20.1-broken"), "{message}");
+}
+
+/// 清单 `id` 与目录名不一致 ⇒ 拒绝（启动时会按清单 id 找 jar，必然找不到）。
+///
+/// 抓得住：去掉 `ManifestIdMismatch` 这条判据后，这个版本会变成「可登记」。
+/// 抓不住：真实启动是否真的失败（那需要真跑游戏，本 mission 不做）。
+#[test]
+fn manifest_id_must_match_the_directory_name() {
+    let root = TempRoot::new("idmismatch");
+    foreign_minecraft(&root.game_root());
+    let dir = root.game_root().join("versions/1.20.1-copy");
+    std::fs::create_dir_all(&dir).expect("建目录");
+    std::fs::write(
+        dir.join("1.20.1-copy.json"),
+        br#"{"id":"1.20.1","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写清单");
+    std::fs::write(dir.join("1.20.1-copy.jar"), b"jar").expect("写 jar");
+
+    let candidate = candidate_of(&root, "1.20.1-copy");
+    let codes: Vec<&str> = candidate
+        .problems
+        .iter()
+        .map(|problem| problem.code())
+        .collect();
+    assert_eq!(codes, vec!["manifest_id_mismatch"]);
+}
+
+/// 版本 id 不能当路径用（`../` / 盘符 / 结尾点号）⇒ 一条结构化问题，不去碰盘。
+///
+/// 抓得住：删掉 id 校验后 `inspect("../escape")` 会去读游戏根之外的路径（下面断言问题码）。
+/// 抓不住：Windows 大小写不敏感之类的平台细节（与判据无关）。
+#[test]
+fn version_ids_that_cannot_be_paths_are_rejected() {
+    let root = TempRoot::new("badid");
+    foreign_minecraft(&root.game_root());
+    let escape = root.path().join("outside");
+    std::fs::create_dir_all(escape.join("1.20.1")).expect("建外部同名目录");
+    std::fs::write(
+        escape.join("1.20.1/1.20.1.json"),
+        br#"{"id":"1.20.1","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写外部清单");
+
+    // `versions/../../outside/1.20.1` 这种形状：目录真的存在（能解析出去），但 id 里含分隔符。
+    let error = adopt::inspect(&root.game(), &root.launcher(), "../../outside/1.20.1")
+        .expect_err("非法 id 应报错，而不是去读游戏根之外的目录");
+    assert_eq!(error.code(), "adopt_not_adoptable");
+    let codes: Vec<&str> = error
+        .problems()
+        .iter()
+        .map(|problem| problem.code())
+        .collect();
+    assert_eq!(codes, vec!["version_id_invalid"], "{error}");
+
+    for bad in ["1.20.1.", "1.20.1 ", "C:", "a/b"] {
+        let error =
+            adopt::inspect(&root.game(), &root.launcher(), bad).expect_err("非法 id 应报错");
+        assert!(
+            error
+                .problems()
+                .iter()
+                .any(|problem| problem.code() == "version_id_invalid"),
+            "{bad:?} 应被当成非法 id：{error}"
+        );
+    }
+}
+
+/// 版本目录是指向游戏根**之外**的符号链接 ⇒ 拒绝不跟随（也不读它）。
+///
+/// 抓得住：`ensure_inside` 不比较解析后的真实路径（那样 `1.20.1-link` 会变成「可登记」）。
+/// 抓不住 / 已知局限：
+/// - 本机不允许建符号链接（Windows 未开开发者模式、或非管理员）时这条会打印 `[link-guard]`
+///   并**跳过**——显式记录而不是静静通过；设 `ULL_ADOPT_TEST_SYMLINK_REQUIRE=1` 则建不出来**必红**；
+/// - 目录联接（junction）由下面单独那条用例覆盖（不需要管理员权限，是更常见的形态）。
+#[test]
+fn a_symlinked_version_pointing_outside_the_game_root_is_rejected() {
+    let root = TempRoot::new("symlink");
+    foreign_minecraft(&root.game_root());
+    let outside = root.path().join("other-launcher");
+    std::fs::create_dir_all(outside.join("1.20.1")).expect("建外部版本目录");
+    std::fs::write(
+        outside.join("1.20.1/1.20.1.json"),
+        br#"{"id":"1.20.1","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写外部清单");
+    let link = root.game_root().join("versions/1.20.1-link");
+    // 建不出来时：非强制模式打印一行并跳过；`ULL_ADOPT_TEST_SYMLINK_REQUIRE=1` 必红（R4）。
+    if !crate::fixture::link_guard(
+        crate::fixture::try_symlink_dir(&outside.join("1.20.1"), &link),
+        "根外符号链接",
+    ) {
+        return;
+    }
+
+    let candidate = candidate_of(&root, "1.20.1-link");
+    let codes: Vec<&str> = candidate
+        .problems
+        .iter()
+        .map(|problem| problem.code())
+        .collect();
+    assert!(
+        codes.contains(&"outside_game_root"),
+        "越界链接必须被点名：{codes:?}"
+    );
+    assert!(!candidate.adoptable(), "越界链接的版本不许登记");
+}
+
+/// 游戏根内的符号链接（指向同一棵树里的真实版本目录）**不**拒绝：那是合法的省盘做法。
+///
+/// 抓得住：`check_symlink` 一刀切拒绝所有符号链接（这条会红）。
+/// 抓不住：本机建不出链接时同上跳过（打印 `[link-guard]`，强制模式下必红）。
+#[test]
+fn a_symlink_inside_the_game_root_is_allowed() {
+    let root = TempRoot::new("symlink-in");
+    foreign_minecraft(&root.game_root());
+    // 真实版本目录放在根内的 `hidden/` 下（清单 id 与目录名一致），再在 `versions/` 里挂一条链接。
+    let real = root.game_root().join("hidden/1.20.1-thin");
+    std::fs::create_dir_all(&real).expect("建真实版本目录");
+    std::fs::write(
+        real.join("1.20.1-thin.json"),
+        br#"{"id":"1.20.1-thin","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写清单");
+    let link = root.game_root().join("versions/1.20.1-thin");
+    if !crate::fixture::link_guard(
+        crate::fixture::try_symlink_dir(&real, &link),
+        "根内符号链接",
+    ) {
+        return;
+    }
+    let candidate = candidate_of(&root, "1.20.1-thin");
+    assert!(
+        candidate.adoptable(),
+        "根内链接不该被拒：{:?}",
+        candidate.problems
+    );
+}
+
+/// `versions/` 不存在 = 空结果（新数据根不是错误），但**不存在的游戏根不会被建出来**。
+///
+/// 抓得住：`scan` 顺手 `create_dir_all(versions)`（下面的断言会红），或把「不存在」当错误。
+/// 抓不住：读目录失败（ENOTDIR/EACCES）那条分支——真造一个不可读目录在 Windows 上不可靠，
+/// 那一条由代码审读把关。
+#[test]
+fn a_missing_versions_dir_is_empty_not_an_error() {
+    let root = TempRoot::new("noversions");
+    let scan = adopt::scan(&root.game(), &root.launcher()).expect("应成功");
+    assert!(scan.candidates.is_empty());
+    assert!(
+        !root.game_root().exists(),
+        "扫描不该顺手建游戏根目录：{}",
+        root.game_root().display()
+    );
+}
+
+/// Windows 目录联接（junction）指向根外 ⇒ **同样**拒绝，而且不去读那个目录。
+///
+/// 为什么要单列：junction 不是 `is_symlink`，只看链接类型的实现会放行它——而 junction
+/// **不需要管理员权限**就能建，是把别人版本目录挂进 `versions/` 最常见的形态。
+///
+/// 抓得住：
+/// - 判据退回 `is_symlink`（除 Windows junction 外全都看不到，此时候选会变成「可登记」，第一条断言红）；
+/// - 判据排到**解析清单之后**：根外那份清单是合法 JSON 且 id 与目录名一致，一旦走到解析，
+///   `manifest_id` 就会被填上（第二条断言红）——所以它至少能证明「没解析过根外清单」；
+/// - 建不出链接时走 `fixture::link_guard`：非强制模式打印 `[link-guard]` 并跳过，
+///   强制模式（`ULL_ADOPT_TEST_SYMLINK_REQUIRE=1`）**必红**（真值表见 `fixture::link_gate_truth_table`）。
+///
+/// 抓不住（证据边界，别把它读大）：**只 stat/只 open 不解析**的读取这里看不出来
+/// （`manifest_id` 为 `None` 只说明没解析过，不说明没碰过文件）；「边界检查排在
+/// `read_manifest` 之前」这条由 `inspect.rs::check` 的代码顺序保证，靠人读。
+/// 也抓不住检查与读取之间的 TOCTOU（本模块不是并发/对抗入口）。
+#[cfg(windows)]
+#[test]
+fn a_junction_pointing_outside_is_rejected_without_reading_it() {
+    let root = TempRoot::new("junction");
+    foreign_minecraft(&root.game_root());
+    // 逐段 join：`cmd` / `mklink` 会把正斜杠当开关，拼成一串带 `/` 的路径会被判「无效参数」。
+    let outside = root.path().join("other-launcher").join("1.20.1-junction");
+    std::fs::create_dir_all(&outside).expect("建外部版本目录");
+    std::fs::write(
+        outside.join("1.20.1-junction.json"),
+        br#"{"id":"1.20.1-junction","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写外部清单");
+    let link = root.game_root().join("versions").join("1.20.1-junction");
+    if !crate::fixture::link_guard(
+        crate::fixture::try_junction(&outside, &link),
+        "根外目录联接",
+    ) {
+        return;
+    }
+
+    let candidate = candidate_of(&root, "1.20.1-junction");
+    let codes: Vec<&str> = candidate
+        .problems
+        .iter()
+        .map(|problem| problem.code())
+        .collect();
+    assert!(
+        codes.contains(&"outside_game_root"),
+        "联接越界必须被点名：{codes:?} / {:?}",
+        candidate.problems
+    );
+    assert!(!candidate.adoptable(), "越界联接的版本不许登记");
+    assert!(
+        candidate.manifest_id.is_none() && candidate.inherits.is_empty(),
+        "拒绝之后不许再读根外那份清单：{:?}",
+        candidate.manifest_id
+    );
+}

crates/core/tests/adopt/snapshot.rs

@@ -0,0 +1,180 @@
+//! 目录树**全节点**快照：目录 / 文件 / 链接各记自己的类型与适用 mtime。
+//!
+//! # 为什么不是「只记文件」
+//!
+//! 复审 r1 的 R5：早先版本遇到目录只递归、不记录，于是「登记过程凭空建了一个空目录」
+//! （例如错误地在 `<game>/versions/<v>/mods` 里 `create_dir_all`）在快照上**完全看不出来**。
+//! 「只读外部」这条承诺必须能抓住新增/删除的**目录节点**，所以这里：
+//!
+//! - 根自身、每个目录、每个文件、每个链接都进快照（相对路径 → [`Node`]）；
+//! - 目录记 mtime（条目增删会改它），文件记字节数 + mtime + 内容哈希；
+//! - **链接不跟随**：只记目标路径（跟随会把根外的内容算进「外部树」，让越界写入看起来像「没变化」）；
+//!   Windows 的目录联接（junction）不是 `is_symlink`，这里额外用重解析点属性识别它；
+//! - 任何读盘失败都**直接失败**（`panic`），不吞成「这项没变」——吞错就是假绿。
+//!
+//! # 为什么 CLI 测试也用这一份
+//!
+//! 以前 core 与 CLI 各写一份 walk，两份都漏了目录节点（同一处缺口两遍）。现在 CLI 的
+//! `adopt_test/fixture.rs` 用 `#[path = "../../../core/tests/adopt/snapshot.rs"]` 复用本文件：
+//! **判据只有一份**，不会再次漂移。
+
+use std::collections::hash_map::DefaultHasher;
+use std::collections::BTreeMap;
+use std::hash::{Hash, Hasher};
+use std::path::{Path, PathBuf};
+use std::time::UNIX_EPOCH;
+
+/// 快照里的一个节点。
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Node {
+    /// 目录（只记 mtime：条目增删会改它）。
+    Dir {
+        /// mtime（纳秒；取不到记 0）。
+        mtime_ns: u128,
+    },
+    /// 文件（字节数 + mtime + 内容哈希）。
+    File {
+        /// 字节数。
+        len: u64,
+        /// mtime（纳秒）。
+        mtime_ns: u128,
+        /// 内容哈希（稳定即可，不要密码学强度）。
+        hash: u64,
+    },
+    /// 符号链接 / Windows 目录联接：只记目标，**不跟随**。
+    Link {
+        /// 链接目标（原样，可能是相对路径；读不出来时记 `<unreadable-link>`）。
+        target: PathBuf,
+    },
+}
+
+/// 一次快照：相对路径（根自身是 `.`）→ 节点。
+pub type Snapshot = BTreeMap<String, Node>;
+
+/// 拍一次全节点快照（目标不存在 = 空快照，见 [`snapshot_opt`] 的区分）。
+///
+/// # Panics
+///
+/// 任何目录/元数据/文件读不出来都 panic：读不出来不能当成「没变化」。
+pub fn snapshot(root: &Path) -> Snapshot {
+    snapshot_opt(root).unwrap_or_default()
+}
+
+/// 同 [`snapshot`]，但目标**不存在**时返回 `None`（用于区分「空树」与「根本没有」）。
+///
+/// # Panics
+///
+/// 同上（存在但读不出来即 panic）。
+pub fn snapshot_opt(root: &Path) -> Option<Snapshot> {
+    match std::fs::symlink_metadata(root) {
+        Ok(_) => {}
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return None,
+        Err(error) => panic!("快照根读不出来 {}：{error}", root.display()),
+    }
+    let mut out = Snapshot::new();
+    out.insert(".".to_string(), node_of(root));
+    walk(root, root, &mut out);
+    Some(out)
+}
+
+fn walk(root: &Path, dir: &Path, out: &mut Snapshot) {
+    let entries = std::fs::read_dir(dir)
+        .unwrap_or_else(|error| panic!("目录应可读 {}：{error}", dir.display()));
+    for entry in entries {
+        let entry = entry.unwrap_or_else(|error| panic!("目录项应可读 {}：{error}", dir.display()));
+        let path = entry.path();
+        let relative = path
+            .strip_prefix(root)
+            .unwrap_or(&path)
+            .to_string_lossy()
+            .replace('\\', "/");
+        let node = node_of(&path);
+        let is_dir = matches!(node, Node::Dir { .. });
+        out.insert(relative, node);
+        if is_dir {
+            walk(root, &path, out);
+        }
+    }
+}
+
+/// 单个节点的形状（链接/联接**不跟随**）。
+fn node_of(path: &Path) -> Node {
+    let meta = std::fs::symlink_metadata(path)
+        .unwrap_or_else(|error| panic!("元数据应可读 {}：{error}", path.display()));
+    if link_like(&meta) {
+        let target =
+            std::fs::read_link(path).unwrap_or_else(|_| PathBuf::from("<unreadable-link>"));
+        return Node::Link { target };
+    }
+    let mtime_ns = meta
+        .modified()
+        .ok()
+        .and_then(|time| time.duration_since(UNIX_EPOCH).ok())
+        .map_or(0, |duration| duration.as_nanos());
+    if meta.file_type().is_dir() {
+        return Node::Dir { mtime_ns };
+    }
+    let bytes = std::fs::read(path)
+        .unwrap_or_else(|error| panic!("文件应可读 {}：{error}", path.display()));
+    Node::File {
+        len: bytes.len() as u64,
+        mtime_ns,
+        hash: hash(&bytes),
+    }
+}
+
+/// 符号链接（所有平台）或 Windows 重解析点（junction / mount point）。
+///
+/// `FileType::is_symlink` 对 junction 返回 `false`，所以 Windows 上另看
+/// `FILE_ATTRIBUTE_REPARSE_POINT`：不识别它就会把 junction 当普通目录**递归进去**，
+/// 等于跟随链接读根外内容。
+fn link_like(meta: &std::fs::Metadata) -> bool {
+    if meta.file_type().is_symlink() {
+        return true;
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::MetadataExt;
+        const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0400;
+        meta.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0
+    }
+    #[cfg(not(windows))]
+    {
+        false
+    }
+}
+
+/// 内容哈希（只要稳定、不需要密码学强度）。
+fn hash(bytes: &[u8]) -> u64 {
+    let mut hasher = DefaultHasher::new();
+    bytes.hash(&mut hasher);
+    hasher.finish()
+}
+
+/// 断言两次快照**完全一致**：路径集合（含目录/链接）与每个节点的形状都不许变。
+///
+/// 抓得住：
+/// - 新增/删除**空目录**（目录节点进快照）、目录条目变化（目录 mtime 变）；
+/// - 文件被改写（哈希变、mtime 变）或被删（路径集合变）；
+/// - 链接目标被改（`Link.target` 变）。
+///
+/// 抓不住：只读打开（无可观测痕迹）、文件内容相同且 mtime 未被改写的「伪写」、
+/// 以及检查期间的 TOCTOU。
+///
+/// # Panics
+///
+/// 快照不一致即 panic（消息里点名第一个不同的路径）。
+pub fn assert_unchanged(before: &Snapshot, after: &Snapshot, what: &str) {
+    assert_eq!(
+        before.keys().collect::<Vec<_>>(),
+        after.keys().collect::<Vec<_>>(),
+        "{what}：路径集合（含目录/链接节点）变了"
+    );
+    for (path, node) in before {
+        assert_eq!(
+            node,
+            after.get(path).expect("同一路径"),
+            "{what}：节点被改动 -> {path}"
+        );
+    }
+}

crates/core/tests/adopt/surface_cases.rs

@@ -0,0 +1,320 @@
+//! 写盘面与入口可用性：**配置目录被链出去**必须拒绝（R2）、**versions 入口断链**必须具名报错（R3）。
+//!
+//! 两类都属于「本 mission 承诺的东西被链接绕过」：前者是「只写自己的配置」被
+//! `config/instances` 的目录联接打穿（会替别人的启动器在 `.minecraft/config` 里造 UUID 文件），
+//! 后者是「坏东西不能当空列表」被 `read_dir` 的 NotFound 打穿（断链 junction 与「真没有」同态）。
+//!
+//! 两条都用**真链接夹具**；建不出链接时走 `fixture::link_guard`（强制模式下必红，见 R4）。
+
+use unlucky_core::game::adopt::{self, AdoptTarget};
+
+use crate::fixture::{
+    assert_unchanged, foreign_minecraft, link_guard, request, snapshot, try_link_dir, TempRoot,
+};
+
+/// `config/instances` 被目录联接指到游戏根的 `config/`：adopt 必须先拒绝，且游戏根零写入。
+///
+/// 抓得住：
+/// - 只核运行目录、不核配置写面（那样这次登记会 exit0，并在 `.minecraft/config/<uuid>.json`
+///   多出一个文件——`before/after` 全节点快照与「外部 config 目录为空」两条都会红）；
+/// - `plan`（dry-run）也放行（第四条断言红：预检说「可以」，真写才失败）；
+/// - 拒绝时先写了目录/配置（快照与目录列举都会红）。
+///
+/// 抓不住：检查与写入之间的 TOCTOU（本模块不是并发/对抗入口）。
+#[cfg(windows)]
+#[test]
+fn a_junction_on_the_instances_dir_must_not_write_into_the_game_root() {
+    use crate::fixture::try_junction;
+
+    let root = TempRoot::new("cfg-instances-junction");
+    foreign_minecraft(&root.game_root());
+    let game_config = root.game_root().join("config");
+    std::fs::create_dir_all(&game_config).expect("建别人的 config 目录");
+    let instances_dir = root.path().join(".ULL").join("config").join("instances");
+    std::fs::create_dir_all(instances_dir.parent().expect("config 目录")).expect("建 .ULL/config");
+    if !link_guard(
+        try_junction(&game_config, &instances_dir),
+        "config/instances 目录联接",
+    ) {
+        return;
+    }
+    let before = snapshot(&root.game_root());
+    // 别人的 `config/` 里本来就有文件（`example.toml` 是玩家配置）：判据是**没有新增条目**。
+    let config_before = listing(&game_config);
+
+    let plan_error = adopt::plan(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("配置写面被链走时，dry-run 也必须报错");
+    assert_eq!(plan_error.code(), "adopt_write_surface_in_game_tree");
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("配置写面被链走时必须拒绝登记");
+    assert_eq!(error.code(), "adopt_write_surface_in_game_tree");
+
+    let after = snapshot(&root.game_root());
+    assert_unchanged(&before, &after, "拒绝之后（游戏根零写入）");
+    assert_eq!(
+        config_before,
+        listing(&game_config),
+        "绝不许在别人的 .minecraft/config 里新增文件（尤其 UUID 配置）"
+    );
+    assert!(
+        !listing(&game_config)
+            .iter()
+            .any(|name| name.ends_with(".json") && name.len() == 41),
+        "不该出现 UUID 形状的 json：{:?}",
+        listing(&game_config)
+    );
+}
+
+/// `config/` 整层被链到游戏根：同样拒绝（判定粒度到**每一个**写盘目标，不只看 `instances`）。
+///
+/// 抓得住：只检查 `config/instances` 而不检查 `config/` 与 `profiles.json`（那样这条会 exit0）。
+/// 抓不住：跨卷/跨盘的整体迁移（`<.ULL>` 自己是联接）——那是允许的，见 `run_dir` 模块文档。
+#[test]
+fn a_linked_config_dir_must_not_write_into_the_game_root() {
+    let root = TempRoot::new("cfg-dir-link");
+    foreign_minecraft(&root.game_root());
+    let game_config = root.game_root().join("config");
+    std::fs::create_dir_all(&game_config).expect("建别人的 config 目录");
+    let ull = root.path().join(".ULL");
+    std::fs::create_dir_all(&ull).expect("建 .ULL");
+    let config_dir = ull.join("config");
+    if !link_guard(try_link_dir(&game_config, &config_dir), "config 目录链接") {
+        return;
+    }
+    let before = snapshot(&root.game_root());
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("config/ 被链走时必须拒绝登记");
+    assert_eq!(error.code(), "adopt_write_surface_in_game_tree");
+
+    let after = snapshot(&root.game_root());
+    assert_unchanged(&before, &after, "拒绝之后（游戏根零写入）");
+}
+
+/// `versions/` 入口**存在但断链**（目标被移走）⇒ 具名报错，而不是「这个数据根还没有版本」。
+///
+/// 抓得住：`read_dir` 的 `NotFound` 一律当空列表（旧实现；Windows 断链 junction 正是这个形状）
+/// ——第一条断言会红成「成功空列表」。
+/// 抓不住：`versions/` 是普通文件的情形（走 `GameError::io`，错误码不同，靠人读）。
+#[test]
+fn a_dangling_versions_entry_is_an_error_not_an_empty_scan() {
+    let root = TempRoot::new("dangling-versions");
+    std::fs::create_dir_all(root.game_root()).expect("建游戏根");
+    let moved = root.path().join("moved-versions");
+    std::fs::create_dir_all(moved.join("1.20.1")).expect("建将被移走的 versions");
+    let versions = root.game_root().join("versions");
+    if !link_guard(try_link_dir(&moved, &versions), "versions 入口链接") {
+        return;
+    }
+    // 目标被移走 ⇒ 入口成为断链；lstat 仍然看得见它。
+    std::fs::remove_dir_all(&moved).expect("移走目标");
+    assert!(
+        std::fs::symlink_metadata(&versions).is_ok(),
+        "夹具有问题：断链入口应当仍能被 lstat 看到"
+    );
+
+    let error = adopt::scan(&root.game(), &root.launcher())
+        .expect_err("断链的 versions 入口必须报错，不能当空列表");
+    assert_eq!(error.code(), "adopt_versions_unreadable", "{error}");
+}
+
+/// `versions` 真不存在 ⇒ 仍然是空结果（别把「新数据根」误报成故障）。
+///
+/// 抓得住：为了修 R3 把所有 NotFound 都当错误（这条会红）。
+/// 抓不住：真正不可读（EACCES）那一支——Windows 上造不可读目录不可靠。
+#[test]
+fn a_truly_missing_versions_dir_stays_empty() {
+    let root = TempRoot::new("no-versions");
+    std::fs::create_dir_all(root.game_root()).expect("建空游戏根");
+    let scan = adopt::scan(&root.game(), &root.launcher()).expect("真不存在 ⇒ 空结果");
+    assert!(scan.candidates.is_empty());
+}
+
+/// 目录里直接子项的名字（排序后，用于「有没有新增」的判据）。
+fn listing(dir: &std::path::Path) -> Vec<String> {
+    let mut names: Vec<String> = std::fs::read_dir(dir)
+        .expect("读目录")
+        .filter_map(|entry| Some(entry.ok()?.file_name().to_string_lossy().into_owned()))
+        .collect();
+    names.sort();
+    names
+}
+
+/// `.ULL/data` 被预先联接到**游戏树**上 ⇒ 默认登记必须拒绝（r2 R2.2），而不是写完再说「隔离」。
+///
+/// 复审 r2 的实跑：`data -> .minecraft` 时 dry-run 与 adopt 都 exit0，外部多出
+/// `instances/<slug>` 且游戏根 mtime 变化，输出仍称「与别人的 .minecraft 隔离」。
+///
+/// 抓得住：写面重叠不核（那样这次登记会成功，游戏树快照与「外部零新增」断言都会红）；
+/// 只核配置不核 data（`data` 面上的缺省运行目录仍会落进游戏树）。
+///
+/// 抓不住：检查与写入之间的 TOCTOU；也不把「后续游戏自己写盘」算作本判据的证据。
+#[cfg(windows)]
+#[test]
+fn data_linked_into_the_game_tree_is_refused_before_any_write() {
+    use crate::fixture::try_junction;
+
+    let root = TempRoot::new("data-to-game");
+    foreign_minecraft(&root.game_root());
+    let data = root.path().join(".ULL").join("data");
+    std::fs::create_dir_all(data.parent().expect(".ULL")).expect("建 .ULL");
+    if !link_guard(try_junction(&root.game_root(), &data), "data -> 游戏树联接") {
+        return;
+    }
+    let before = snapshot(&root.game_root());
+
+    let plan_error = adopt::plan(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("dry-run 也必须拒绝与游戏树重叠的写盘面");
+    assert_eq!(plan_error.code(), "adopt_write_surface_in_game_tree");
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("默认登记必须拒绝与游戏树重叠的 data 写面");
+    assert_eq!(error.code(), "adopt_write_surface_in_game_tree");
+
+    assert_unchanged(
+        &before,
+        &snapshot(&root.game_root()),
+        "拒绝之后（游戏树零写入）",
+    );
+    assert!(
+        !root.game_root().join("instances").exists(),
+        "绝不许在别人的 .minecraft 里建 instances 目录"
+    );
+}
+
+/// `.ULL` 整棵树被预先联接到游戏树 ⇒ 同样拒绝（配置 + data 一起落进游戏树）。
+///
+/// 抓得住：只核 `data` 或只核 `config/instances`（那样 `profiles.json` 与 `data/` 仍会写穿）。
+///
+/// 抓不住：`<.ULL>` 自己是链接但指向**游戏树之外**的情形——那是合法迁移，见下一条正向对照。
+#[cfg(windows)]
+#[test]
+fn home_linked_into_the_game_tree_is_refused_before_any_write() {
+    use crate::fixture::try_junction;
+
+    let root = TempRoot::new("home-to-game");
+    foreign_minecraft(&root.game_root());
+    let home = root.path().join(".ULL");
+    if !link_guard(try_junction(&root.game_root(), &home), ".ULL -> 游戏树联接") {
+        return;
+    }
+    let before = snapshot(&root.game_root());
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("默认登记必须拒绝与游戏树重叠的 .ULL 写面");
+    assert_eq!(error.code(), "adopt_write_surface_in_game_tree");
+
+    assert_unchanged(
+        &before,
+        &snapshot(&root.game_root()),
+        "拒绝之后（游戏树零写入）",
+    );
+}
+
+/// **正向对照**：把 `data` 整体迁到游戏树**之外**仍然允许（迁移是合法的，重叠才拒）。
+///
+/// 抓得住：把「与游戏树重叠」写成「任何链接都拒」（这条正向用例会红）。
+/// 抓不住：迁移后的数据目录内容（只断言登记成功且游戏树不变）。
+#[test]
+fn data_migrated_outside_the_game_tree_still_registers() {
+    let root = TempRoot::new("data-outside");
+    foreign_minecraft(&root.game_root());
+    let external = root.path().join("external-data");
+    std::fs::create_dir_all(&external).expect("建外部数据目录");
+    let data = root.path().join(".ULL").join("data");
+    std::fs::create_dir_all(data.parent().expect(".ULL")).expect("建 .ULL");
+    if !link_guard(try_link_dir(&external, &data), "data -> 游戏树之外的联接") {
+        return;
+    }
+    let before = snapshot(&root.game_root());
+
+    let outcome = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("迁到游戏树之外的 data 应允许");
+    // 对外返回的是**逻辑**路径（`<.ULL>/data/instances/<slug>`），真实位置才是迁移后的目录。
+    let real = outcome.run_dir.canonicalize().expect("运行目录真实路径");
+    let external_real = external.canonicalize().expect("外部数据目录真实路径");
+    assert!(
+        real.starts_with(&external_real),
+        "运行目录的真实位置应落在迁移后的数据目录里：{}",
+        real.display()
+    );
+    assert_unchanged(
+        &before,
+        &snapshot(&root.game_root()),
+        "登记之后（游戏树零写入）",
+    );
+}
+
+/// **更高祖先断链**（r2 R2.3）：完整版本树挂在迁移联接下面，联接目标被搬走后 scan 不许报空。
+///
+/// 复审 r2 的对照：`--data-dir link/nested` 断开前 total=1；把 `link` 的目标改名后，
+/// `versions` 与游戏根本身都 NotFound，旧实现返回 `ok:true / total:0`。
+///
+/// 抓得住：只在 `versions` 与游戏根两层 lstat（更高层断链会漏，第二条断言红）；
+/// 或反过来把「真正的新数据根」也判成错误（断开**之前**那条 total==1 的断言与
+/// `a_truly_missing_versions_dir_stays_empty` 会红）。
+#[test]
+fn a_dangling_ancestor_above_the_game_root_is_not_an_empty_scan() {
+    let root = TempRoot::new("ancestor-dangling");
+    let real = root.path().join("target");
+    let game = real.join("nested").join(".minecraft");
+    std::fs::create_dir_all(game.join("versions").join("1.20.1")).expect("建完整版本树");
+    std::fs::write(
+        game.join("versions/1.20.1/1.20.1.json"),
+        br#"{"id":"1.20.1","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写清单");
+    let link = root.path().join("game-parent-link");
+    if !link_guard(try_link_dir(&real, &link), "游戏根上层联接") {
+        return;
+    }
+    let data_root = root.path().join("data");
+    std::fs::create_dir_all(&data_root).expect("建数据根");
+    let minecraft = link.join("nested").join(".minecraft");
+    let game_layout = unlucky_core::game::GameLayout::new(&minecraft);
+    let launcher = unlucky_core::platform::layout::LauncherLayout::new(data_root.join(".ULL"));
+
+    // 断开之前：完整版本树看得见。
+    let scan = adopt::scan(&game_layout, &launcher).expect("联接完好的树应可扫");
+    assert_eq!(scan.candidates.len(), 1, "完整版本树应扫到 1 个候选");
+
+    // 断开：把联接目标改名，入口还在但解析不出来（versions 与游戏根本身都 NotFound）。
+    std::fs::rename(&real, root.path().join("moved-target")).expect("移走联接目标");
+    assert!(
+        std::fs::symlink_metadata(&link).is_ok(),
+        "夹具有问题：断链入口应仍能被 lstat 看到"
+    );
+
+    let error =
+        adopt::scan(&game_layout, &launcher).expect_err("祖先断链必须具名报错，不能当空结果");
+    assert_eq!(error.code(), "adopt_versions_unreadable", "{error}");
+}